🏗️ 系统架构文档

护理质量监测与分析平台 — 代码结构、数据流向与功能模块全景图

v2.0 · 模块化架构 · --
-项目总文件
-总代码行数
-核心服务文件
-同步脚本
-数据库表
-业务页面
-API 接口
📐
一、系统分层架构 自上而下调用关系
入口层ENTRY
server.py 程序入口，负责启动服务
共享层SHARED
shared.py Flask 后端：数据库连接、锁函数、配置常量（所有模块的基石）
sync_base.py 同步公共基类：轻流API拉取、MySQL upsert、日志（所有同步脚本共用）
shared-report.css 报表类页面公共样式：进度条、卡片、筛选栏、分页、按钮
shared-report.js 报表类公共JS：API请求、统计卡片、CSV导出、分页、日期工具
shared-doc.css 规则文档类公共样式：侧边栏导航、折叠section、移动端汉堡
shared-doc.js 规则文档类公共JS：侧边栏切换、section折叠、滚动导航高亮
路由层ROUTES
routes/static.py 工作台首页 + 全部 HTML 页面路由跳转
routes/leak_check.py 护理漏测报表 — 全部 API（筛选/查询/导出）
routes/assessment.py 评估报表 — 全部 API（图表/详情/规则）
routes/adverse_events.py 不良事件报表 + 不良事件同步触发
routes/care_plan.py 照护计划同步 + 完成情况检查
routes/hr_report.py 人力综合报表 + 花名册同步 + 机构版 HR
routes/resident.py 入住协议同步 + 机构休养区同步
routes/cron_manager.py 定时任务管理（查看/启停/编辑）
routes/project_stats.py 项目代码统计（文件数/行数）
同步层SYNC
sync_resident_info.py 入住协议 → base_resident_info 表
sync_db.py 护理记录 → biz_nursing_records 表
sync_assessment.py 评估记录 → biz_assessment_records 表
sync_adverse_events.py 不良事件 → biz_adverse_events 表
sync_staff_roster.py 花名册 → biz_staff_roster + 调动子表
sync_care_plans.py 照护计划 → biz_care_plans 表
sync_org_area.py 机构休养区映射 → base_org_area 表
分析层ANALYZE
analyze_db.py 护理漏测分析（双周/等级/合格判定）
analyze_db_v3.py 护理漏测分析 V3 版本
analyze_legacy.py 旧版分析逻辑（历史保留）
analyze_assessment.py 评估结果分析（总分/时间趋势）
数据库MYSQL
base_resident_info入住协议主表（老人基础信息+状态）
base_org_area机构 ↔ 休养区 映射关系
biz_nursing_records护理测量记录（体温/血压/血糖等）
biz_leak_check_result漏测检查结果（双周合格/不合格）
biz_assessment_records评估原始记录
biz_assessment_analysis评估分析结果（总分×维度）
biz_care_plans照护计划（制定日期/截止/内容）
biz_adverse_events不良事件（类型/时间/分级）
biz_staff_roster员工花名册（在职+离职）
biz_staff_transfers员工调动子表
biz_sync_log同步操作日志
🔄
二、数据流向 从外部系统到最终展示
☁️
轻流平台
→
⬇️
Sync 脚本
→
🗄️
MySQL 数据库
→
🔧
Analyze 分析
↓
🌐
Flask API
→
🖥️
前端页面
→
👤
用户浏览器
📋
三、功能模块一览 按业务域分类
📊
护理漏测报表
双周漏测检测，按机构/等级/休养区筛选，显示每位老人的测量完成情况和合格率
报表核心功能
📋
评估报表
评估总分趋势、各维度得分对比、评估明细查询
报表图表
⚠️
不良事件报表
事件类型分布、时段统计、跌倒分级、管路拔出分析
报表统计分析
👥
HR 综合报表
职级×性别、学历分布、年龄段、岗位序列、入离职分析、离职率
报表多 Sheet
🏢
机构版 HR 报表
分机构的在岗流动、入职分析、老带新、离职分析、离职率
报表多维度
✅
照护计划检查
在住老人计划覆盖率检查 + 新入住老人 7 日内计划制定检查
检查合规
🔄
手动同步工具
7 种数据的一键同步面板，含进度状态和日志查看
工具运维
⏰
Cron 定时任务
7 个定时任务的查看、启停、执行时间编辑
工具运维
🏠
工作台首页
系统总览入口，卡片式导航到所有功能模块
导航入口
📈
项目代码统计
按类别统计所有文件的代码行数，追踪项目规模变化
工具管理
📖
规则文档
每套报表/同步/检查配套的业务规则说明文档
文档说明
🗄️
四、数据库表结构 MySQL · nursing 库 · Docker 部署
前缀 表名 用途说明 数据来源
base_ base_resident_info 老人基础信息：姓名、身份证、机构、休养区、床位号、护理等级、离院状态等 轻流「入住协议」
base_ base_org_area 机构名称 ↔ 休养区名称 的对应关系（一对多） 轻流「机构休养区」
biz_ biz_nursing_records 护理测量记录：体温、血压、血糖、血氧等生命体征数据 轻流「护理记录」
biz_ biz_leak_check_result 漏测检查结果：每人每双周的合格/不合格判定 分析计算生成
biz_ biz_assessment_records 评估原始记录：每次评估的维度分数 轻流「评估记录」
biz_ biz_assessment_analysis 评估分析汇总：总分排名、各维度均值 分析计算生成
biz_ biz_care_plans 照护计划：计划类型、制定日期、截止日期、是否生效 轻流「照护计划」
biz_ biz_adverse_events 不良事件：事件类型、发生时间、分级、管路类型 轻流「不良事件」
biz_ biz_staff_roster 员工花名册：姓名、岗位、职级、司龄、在职/离职状态 轻流「花名册」
biz_ biz_staff_transfers 员工调动记录：调出/调入机构、调动时间 轻流「花名册」子表
sys_ biz_sync_log 同步日志：每次同步的时间、耗时、成功/失败记录数 系统自动写入
命名规范：base_ = 基础数据（人/组织）   biz_ = 业务数据（记录/事件/结果）   sys_ = 系统数据（日志/配置）
🖥️
五、前端页面清单 共 13 个业务页面 (规则文档未计入)
页面路由地址类型
工作台首页/导航入口
护理漏测报表/leak-check报表
评估报表/assessment报表
不良事件报表/adverse-events-report报表
HR 综合报表/hr-report报表
机构版 HR 报表/institution-hr-report报表
照护计划检查/care-plan-check检查
手动同步工具/sync-tools工具
Cron 定时任务/cron-manager工具
项目代码统计/project-stats工具
架构设计文档/architecture-design文档
护理数据规则/nursing-data-rules文档
评估规则/assessment-rules文档
HR 报表规则/hr-report-rules文档
机构 HR 规则/institution-hr-report-rules文档
同步规则/sync-rules文档
Cron 规则/cron-rules文档
照护计划检查规则/care-plan-check-rules文档
培训考核规则/training-assessment-rules文档
+ 其他备份/废弃页面约 10 个
📐
六、开发规范速查 已积累的经验教训
🔴 进度条组件
<span> 是内联元素，必须加 display:block 或 display:inline-block，否则高度失效导致灰色。
🔴 Flex 容器压缩
父容器设了 align-items:center 后，子元素会被压缩。需给子元素加 width:100%。
🔴 统计卡片筛选
统计数字只受「机构+休养区」影响，不受「完成状态」「分页」影响。用两套 WHERE 分别处理。
🔴 同步锁机制
所有同步统一用 _get_task_status() + _set_task_status()，带 PID 校验 + 超时检测防假锁。
🔴 脚本路径
新增同步端点时，脚本文件名以服务器 ls 实际为准。禁止硬编码绝对路径，标准写法：[sys.executable, os.path.join(LEAK_DIR,'实际文件名.py')]
🔴 批量替换保护
CRON_JOBS 的 cmd_keyword 和 log_file 是文件名不是表名，批量替换时必须排除。
🟡 多表 JOIN
同时 JOIN ≥2 张 1:N 业务表会产生笛卡尔积。先子查询聚合到每人一行再 JOIN 主表。
🔵 新增功能流程
用户描述需求 → AI 判断归属 → routes/ 新建或修改文件 → server.py 注册路由 → 前端新建/修改 HTML → 部署验证 → 更新此文档
🖥️
七、部署环境
项值
云服务器腾讯云 VM-0-7-ubuntu · root@110.42.221.197
Flask 服务Python 3 · 端口 9090 · nohup 后台运行
静态文件路径/opt/site/ + /opt/leakcheck/（双路径部署）
代码仓库root@110.42.221.197:/opt/nursing.git（Git裸仓库）
数据库Docker MySQL · 容器名 mysql-nursing· 库名 nursing
外部数据源轻流 care.yckycn.com · OpenAPI · Token 认证
定时任务系统 crontab · 每日凌晨 01:30 ~ 04:30 执行
本地仓库C:/Users/mmtme/WorkBuddy/2026-06-06-18-01-28/

📝 此文档由系统自动维护 · 每次代码结构变更后自动更新 · 最后更新: 2026-06-12 v2.0