架构设计与分析
1 架构总览图
▼以下为当前系统的数据流向与架构分层示意图：
架构模式：ETL（Extract-Transform-Load）+ 数据副本（Data Replica）+ 读写分离（Read/Write Split）。轻流是唯一的业务数据录入端（Source of Truth），MySQL 是只读分析副本。
💧 数据流向：饮水系统类比
将六层数据流比作城市供水系统，便于非技术人员理解各模块的作用：
轻流 API
↓
水源
(数据源头)
→
同步脚本
↓
抽水机
(sync_*.py)
→
MySQL
↓
蓄水池
(数据仓库)
→
分析脚本
↓
净水器
(analyze_*.py)
→
中间结果
↓
直饮水
(result.json)
→
server.py
↓
水管
(API接口)
→
前端页面
↓
水龙头
(HTML页面)
| 层级 | 比喻 | 实际模块 | 缺了会怎样 |
|---|---|---|---|
| 1. 数据源 | 水源 | 轻流 API（入住协议/护理/评估等） | 无水可抽，整个系统空转 |
| 2. 同步层 | 抽水机 | sync_*.py（7个同步脚本） | 数据库是空的，分析跑不了 |
| 3. 存储层 | 蓄水池 | MySQL（10张表，base_/biz_ 前缀） | 数据无处存放 |
| 4. 分析层 | 净水器 | analyze_*.py（漏测/漏评分析） | 原始数据有但核心指标出不来 |
| 5. 接口层 | 水管 | server.py（Flask API 路由） | 前端调不到数据，页面打不开 |
| 6. 展示层 | 水龙头 | HTML 前端页面（漏测/评估/HR/报表等） | 数据有但你看不见 |
⚠️ 核心结论：六层缺一不可。同步脚本虽不直接面向用户，但它是数据链路的起点——没有它，后面五层都是空的。四块核心代码（同步+分析+server+前端）合计 11,139 行，占总代码量的 49%。
2 架构说明
▼每层职责
| 层级 | 组件 | 职责说明 |
|---|---|---|
① 数据源层 | 轻流各应用 | 所有业务数据的唯一录入端，保持 Source of Truth 地位，不从此端删除或修改同步后的数据 |
② ETL 同步层 | 同步脚本 + cron | 通过轻流 API 拉取数据，清洗转换后写入 MySQL。支持增量同步（快速）和全量同步（覆盖） |
③ 数据存储层 | MySQL 数据库 | 存储所有业务数据的副本，支持跨表 JOIN、复杂查询、统计分析。与轻流完全解耦 |
④ 应用层 | Flask + 前端页面 | 提供 Web 界面，用户通过浏览器访问，执行漏测检查、数据查阅、同步操作等功能 |
行业术语对应
| 你正在做的事 | 行业术语 | 解释 |
|---|---|---|
| 从轻流拉数据到 MySQL | ETL | Extract（抽取）→ Transform（转换）→ Load（加载） |
| MySQL 里的数据副本 | 数据副本 / 影子库 | 原始数据的只读拷贝，用于分析不影响生产系统 |
| 轻流做业务，MySQL 做分析 | 读写分离 | 写操作在轻流，读/分析操作在 MySQL |
| 多个业务数据汇聚到一起 | 轻量级数据中台 | 把多个源头的数据汇聚、建模、统一分析 |
| 当前整体架构 | OLTP → OLAP | 轻流处理日常业务（OLTP），MySQL 做分析报表（OLAP） |
3 合理性分析
▼
✅ 结论：对当前业务规模和需求来说，架构完全合理，长期可行。
合理的理由
| 理由 | 说明 |
|---|---|
| 🎯 轻流不是数据库 | 轻流擅长数据采集和审批流转，不擅长复杂跨表关联分析、统计报表、自动预警。把数据拉到 MySQL，等于给轻流配了一个"分析师大脑" |
| 🛡️ 不对业务系统造成干扰 | 所有分析都在 MySQL 副本上跑，轻流该干嘛干嘛，互不影响。典型的读写分离思想 |
| 📈 灵活可扩展 | 后续任何新业务（不良事件、培训考核……），来一个拉一个，所有数据在 MySQL 里可以随便关联，这是轻流内部做不到的 |
| 💰 成本低 | 不需要买新系统，用一台云服务器 + MySQL 就搞定了，对当前规模的机构来说完全够用 |
打个比方
轻流就像是一本手写台账，每天记录业务发生情况，方便、直观。
MySQL 副本就像是专门的分析师，把台账里的数据抄下来，整理成报表、找出问题、给出预警。
台账不会被分析师弄乱，分析师也不会因为台账在忙就做不了分析。
MySQL 副本就像是专门的分析师，把台账里的数据抄下来，整理成报表、找出问题、给出预警。
台账不会被分析师弄乱，分析师也不会因为台账在忙就做不了分析。
4 风险与应对
▼| 风险 | 严重程度 | 说明 | 应对方案 |
|---|---|---|---|
| API 限流 | ⚠️ 中 | 轻流对 openApi 可能有限流策略 | 目前每天只同步一次，问题不大。后续数据源多了，错开时间同步即可 |
| 数据不一致 | ℹ️ 低 | 同步有时差（如之前 2778 vs 2779） | 对漏测检查场景（T+1 天看结果）完全够用，不需要实时 |
| MySQL 单机瓶颈 | ℹ️ 低 | 单机 MySQL 性能上限 | 目前才几万条数据，MySQL 能轻松扛到百万级。真正需要操心是千万级以上，离现在还很远 |
| 同步脚本维护 | ⚠️ 中 | 后续脚本多了难以管理 | 建议抽象成通用同步框架，统一管理（见第7节建议） |
5 对业务服务器的影响
▼
结论：基本没有影响。
为什么没有影响？
| 对比项 | 说明 |
|---|---|
| 📊 请求频率 | 每天只调一次 API（凌晨 cron），每次 200~300 次请求，分摊到几分钟内完成 |
| 👥 用户操作 | 轻流服务器本身要处理几百个用户日常操作，你这一轮同步的负载微不足道 |
| ⏱️ 增量同步 | 现在的增量同步设计只拉新数据，避免了全量拉取的大量请求 |
| 🔒 只读操作 | 同步是只读轻流数据，不会修改轻流任何内容 |
打个比方：轻流是一个大超市，你每天凌晨去抄一次库存清单，抄完就走。超市的正常营业不会因为你在抄清单而受影响。
唯一需要注意的
不要频繁触发全量同步。全量同步会拉取近30天所有数据（~50000条），对轻流 API 有一定压力。现在的增量同步设计已经避免了这个问题，日常使用没有问题。
6 可扩展功能路线图
▼第一期：已有数据，加规则即可
| 功能 | 说明 | 难度 |
|---|---|---|
| 📋 护理记录质量评分 | 按护理员统计完整率、及时率，出排名 | 低（数据已有） |
| 🏥 评估预警看板 | 哪些老人评估结果异常（压疮风险高、跌倒风险高等），主动预警 | 低（数据已有） |
| 📊 入住/离院趋势 | 利用入住协议数据，统计月度入住率、离院率、在住人数变化曲线 | 低（数据已有） |
| 👤 跨业务数据关联 | 例如：某老人跌倒风险评估高 → 查看他最近有没有跌倒不良事件 → 关联护理记录看是否加强了巡视 | 中（需要关联规则） |
第二期：等待数据接入后可做
| 功能 | 依赖数据 | 难度 |
|---|---|---|
| 📋 不良事件分析 | 不良事件表接入后 | 低 |
| 🏋️ 培训考核通过率 | 培训考核数据接入后 | 低 |
| 👨⚕️ 医生巡诊完成率 | 巡诊记录接入后 | 低 |
| 📑 照护计划执行跟踪 | 照护计划数据接入后 | 中 |
| 👥 人效分析 | 人力资源数据（排班、工时）接入后 | 中 |
第三期：终极形态 —— 管理驾驶舱
把所有业务数据整合后，做一个管理驾驶舱：一个页面看到整个机构的核心指标 —— 在住人数、今日护理完成率、本周不良事件数、本月培训完成率、人员到岗率……就像汽车仪表盘一样，管理层一眼看清运营全貌。
7 后续建议
▼| 建议 | 说明 | 优先级 |
|---|---|---|
| 📦 数据同步统一管理 | 现在有 sync_db.py、sync_assessment.py、sync_resident_info.py 三套同步脚本，后续数据源多了会更乱。可以考虑抽象成一个通用同步框架，统一配置、统一日志、统一错误处理 | 🔴 高 |
| 🗂️ MySQL 表设计提前规划 | 每接入一个新业务，表命名、字段命名保持统一风格（目前已经做得不错），方便后续跨表 JOIN | 🟡 中 |
| 🔒 保留轻流作为唯一录入端 | 不要在 MySQL 副本里直接改数据、再反向同步回轻流。保持"轻流是唯一真相来源，MySQL 是只读分析副本"的定位，这是最安全的设计 | 🔴 高 |
| 📈 增加同步监控 | 在 sync-tools.html 页面增加同步历史记录展示（已有 _sync_log 表），方便排查问题 | 🟡 中 |
| ⚡ 评估同步性能优化 | 评估同步目前约 5 分钟（openApi 不支持大 pageSize），可后续研究改用 view API 或增加多线程并发 | 🟢 低 |
总结一句话：这条路走得通，而且已经走对了。你现在做的事情，本质上就是软件行业里"数据中台"要做的事情，只是规模小、工具轻，但思路和大型企业一模一样。