🔄 数据同步规则文档
1总体概览
▼本系统共有 5 个数据同步模块，数据来源 全部为轻流 API，同步后写入本地 MySQL 数据库（nursing 库）。
轻流平台 (care.yckycn.com)
│
├── openApi ────────── ① 入住协议 (resident_info)
│ └─ 脚本: sync_resident_info.py
│ └─ AppKey: 8a7fonqg0o02
│
├── VIEW API ──────── ② 护理记录 (nursing_records)
│ └─ 脚本: sync_db.py
│ └─ AppKey: 8h0q8g841402
│
├── openApi ────────── ③ 评估记录 (assessment_records)
│ └─ 脚本: sync_assessment.py
│ └─ AppKey: 8hjq5k381401
│
└── openApi ────────── ④ 机构-休养区 (org_area_mapping)
└─ server.py 内嵌逻辑
└─ AppKey: 8a7fonqg0o02
│
└── openApi ────────── ⑤ 不良事件 (adverse_events)
└─ 脚本: sync_adverse_events.py
└─ AppKey: dtonmhf02801
| 模块 | 目标表 | 数据来源 | 同步脚本 | 同步方式 |
|---|---|---|---|---|
| ① 入住协议 | resident_info | 轻流 openApi | sync_resident_info.py | 增量（默认）/ 全量（勾选） |
| ② 护理记录 | nursing_records | 轻流 VIEW API | sync_db.py | 增量（按 record_time） |
| ③ 评估记录 | assessment_records | 轻流 openApi | sync_assessment.py | 全量（--full） |
| ④ 机构-休养区 | org_area_mapping | 轻流 openApi | server.py 内嵌 | 全量 |
| ⑤ 不良事件 | adverse_events | 轻流 openApi | sync_adverse_events.py | 全量（唯一模式） |
💡 关键结论：所有同步模块的数据来源均为轻流 API，并非 MySQL 数据库。本地 MySQL 是"目标"，不是"来源"。
2入住协议同步（resident_info）
▼resident_info（入住/离院状态，护理等级，床位等） |
轻流 openApi — AppKey: 8a7fonqg0o02 |
/opt/leakcheck/sync_resident_info.py |
187f968c-48a4-4874-95bc-edb084a4083d |
同步方式
| 模式 | 触发方式 | 行为 | 耗时 |
|---|---|---|---|
| 增量同步 | 直接点击"开始同步" | 对比数据库已有记录与轻流最新数据，只更新有变化的行（新增/更新/标记离院），无变化跳过 | 快（秒级） |
| 全量同步 | 勾选"全量同步"后点击 | 先 DELETE FROM resident_info 清空整表，再从轻流逐条重新写入 |
慢（1-2分钟） |
删除行为
⚠️ 增量同步：不删除。轻流已删除的人，本地数据库仍保留（脏数据）。
✅ 全量同步：会删除。先清空再全量写入，保证与轻流100%一致。
✅ 全量同步：会删除。先清空再全量写入，保证与轻流100%一致。
删除逻辑总结
| 场景 | 增量同步 | 全量同步 |
|---|---|---|
| 轻流新增一条入住协议 | 新增 | 新增 |
| 轻流更新一条入住协议 | 更新 | 更新 |
| 轻流删除一条入住协议 | 不删除 | 同步删除 |
📌 建议：日常同步直接点按钮（增量）；如果怀疑数据不一致，或数据库被手动改过，再勾选"全量同步"彻底刷新。
3护理记录同步（nursing_records）
▼nursing_records（生命体征：体温、脉搏、呼吸、血压、血氧等） |
轻流 VIEW API — AppKey: 8h0q8g841402 |
/opt/leakcheck/sync_db.py |
6f206710-dbc6-43ac-9414-9d13842a2f41 |
https://care.yckycn.com/api/view/8h0q8g841402/apply/filter |
同步方式
| 模式 | 触发方式 | 行为 |
|---|---|---|
| 增量同步 | 点击"开始同步" | 获取数据库最新 record_time，仅从轻流拉取比它更新的数据，插入或更新 |
| 全量同步（30天） | 内部脚本参数 | 拉取最近30天全量数据（非清空表），自动清理30天前的旧记录 |
删除行为
⚠️ 不会同步删除。轻流里删除了某条护理记录，本地数据库不会删除它。该记录会一直保留在
唯一的删除操作是自动清理 30天前 的旧记录（
nursing_records 表中。唯一的删除操作是自动清理 30天前 的旧记录（
DELETE FROM nursing_records WHERE record_date < ...），与轻流是否删除无关。
删除逻辑总结
| 场景 | 增量/全量同步 |
|---|---|
| 轻流新增一条护理记录 | 新增 |
| 轻流更新一条护理记录 | 更新 |
| 轻流删除一条护理记录 | 不删除（本地保留） |
| 记录超过30天 | 自动清理（与轻流无关） |
💡 说明：如果需要"轻流删除后本地也同步删除"，需要修改
sync_db.py 增加对比删除逻辑（当前未启用此能力）。
4评估记录同步（assessment_records）
▼assessment_records（12项必查评估：能力、压疮、跌倒等） |
轻流 openApi — AppKey: 8hjq5k381401 |
/opt/leakcheck/sync_assessment.py |
187f968c-48a4-4874-95bc-edb084a4083d |
同步方式
| 模式 | 行为 | 后续步骤 |
|---|---|---|
| 全量同步（--full） | 清空表 → 从轻流分页拉取全部数据 → 逐条写入 | 自动运行 analyze_assessment.py 重新分析漏评 |
删除行为
✅ 会同步删除。全量同步先清空表再重新写入，轻流里已删除的评估记录不会出现在本地数据库中，等于同步删除。
删除逻辑总结
| 场景 | 全量同步 |
|---|---|
| 轻流新增一条评估记录 | 新增 |
| 轻流更新一条评估记录 | 更新 |
| 轻流删除一条评估记录 | 同步删除（表中不出现） |
5机构-休养区同步（org_area_mapping）
▼org_area_mapping（机构 ↔ 休养区域映射关系） |
轻流 openApi — AppKey: 8a7fonqg0o02 |
server.py 内嵌（_run_org_area_sync_in_background 函数） |
| 19 家养老机构及其休养区 |
同步方式
| 模式 | 行为 |
|---|---|
| 全量同步 | 从轻流拉取最新机构与休养区数据 → 清空并重新写入 org_area_mapping 表 |
删除行为
✅ 会同步删除。每次同步都是全量重建，轻流删掉的机构或休养区不会保留在本地。
删除逻辑总结
| 场景 | 全量同步 |
|---|---|
| 轻流新增机构/休养区 | 新增 |
| 轻流更新机构/休养区 | 更新 |
| 轻流删除机构/休养区 | 同步删除 |
5b不良事件同步（adverse_events）
▼adverse_events（不良事件类型、事发时间、地点、班次等） |
轻流 openApi — AppKey: dtonmhf02801 |
/opt/leakcheck/sync_adverse_events.py |
187f968c-48a4-4874-95bc-edb084a4083d（Header 传 accessToken） |
同步方式
ℹ️ 不良事件为永久保留数据，始终采用全量同步模式，不做增量、不清理旧数据。
| 模式 | 行为 |
|---|---|
| 全量（唯一模式） | 不设日期过滤，拉取轻流所有记录；同步后删除轻流中已不存在的记录，确保 DB 与轻流完全一致 |
删除行为
✅ 会同步删除。每次全量同步后，比对本次拉取到的所有
apply_id，删除 DB 中存在但轻流中已不存在的记录：
DELETE FROM adverse_events WHERE apply_id NOT IN (本次拉取的所有apply_id)这样确保 DB 数据与轻流业务表完全一致：轻流新增的会插入，轻流修改的会更新，轻流删除的也会从 DB 删除。
删除逻辑总结
| 场景 | 全量同步 |
|---|---|
| 轻流新增一条不良事件 | 新增（upsert） |
| 轻流更新一条不良事件 | 更新（upsert） |
| 轻流删除一条不良事件 | 同步删除 |
⚠️ 安全防护：若 API 返回的 apply_id 列表为空，跳过删除操作（防止误删全表）。
6删除逻辑对比总结
▼以下汇总：当轻流端删除了某条数据后，本地 MySQL 是否会同步删除。
| 模块 | 同步方式 | 轻流删除 → 本地同步删除？ | 原因 |
|---|---|---|---|
| 🏠 入住协议 | 增量（默认） | ❌ 不会 | 只对比差异，不检测删除 |
| 🏠 入住协议 | 全量（勾选） | ✅ 会 | 先 DELETE 整表再全量写入 |
| 💊 护理记录 | 增量（按 record_time） | ❌ 不会 | 只拉取新数据，不对比已删除 |
| 📋 评估记录 | 全量（--full） | ✅ 会 | 清空表+全量写入，无残留 |
| 🏥 机构-休养区 | 全量 | ✅ 会 | 每次全量重建映射表 |
| ⚠️ 不良事件 | 全量（唯一模式） | ✅ 会 | upsert + 删除轻流中不存在的记录 |
⚠️ 特别注意：护理记录同步是目前唯一一个完全不会同步删除的模块。无论增量还是30天全量，轻流删除的记录都会一直保留在本地，直到超过30天被自动清理。
如果需要"轻流删、本地也删"的能力，需要修改
sync_db.py 增加对比删除逻辑。
📌 快速记忆：
- 全量同步（清空+重建）→ 会删除：入住协议(全量)、评估记录、机构-休养区
- 全量同步（upsert+删除不存在记录）→ 会删除：不良事件
- 增量同步（追加+更新）→ 不删除：入住协议(增量)、护理记录