hms/wiki/erp-health.md

title, updated, status, tags

title	updated	status	tags
erp-health 健康管理模块	2026-04-25	implemented	health patient appointment follow-up consultation

erp-health 健康管理模块

从 index 导航。关联: erp-core erp-server database frontend

设计规格: docs/superpowers/specs/2026-04-23-health-management-module-design.md

1. 设计决策

为什么用原生模块而非 WASM 插件？

WASM 插件限制	健康模块需求
实体上限 20 个	18 强类型医疗实体
JSONB 动态存储	医疗数据需要强类型、索引、关联
无自定义 API	趋势分析、统计报表需专用端点
无文件上传	化验单、体检报告需存储
沙箱限制	无法引入加密、AI、外部 API

为什么患者/医护账号走 erp-auth？

复用现有用户体系（认证、JWT、权限），erp-health 只存医疗扩展字段。患者可先建档（体检中心导入），后续再绑定账号。

核心架构选择

• 原生 Rust crate — 与 erp-auth、erp-workflow 同等地位，直接访问数据库
• ErpModule trait 实现 — HealthModule 在 erp-server 注册，路由挂载到 /api/v1/health
• EventBus 通信 — 发布 patient.created、appointment.confirmed 等，订阅 workflow.task.completed
• HealthCrypto — AES-256-GCM 加密 + HMAC-SHA256 哈希，保护 PII 数据

2. 关键文件 + 数据流

目录结构

crates/erp-health/
├── src/
│   ├── lib.rs           ← 模块导出 (HealthCrypto, HealthModule, HealthState)
│   ├── module.rs        ← ErpModule trait 实现, 14 权限码, 全部路由定义
│   ├── error.rs         ← HealthError (17 变体) → AppError
│   ├── state.rs         ← HealthState { db, event_bus, crypto }
│   ├── crypto.rs        ← AES-256-GCM 加密 + HMAC-SHA256 (PII 保护)
│   ├── event.rs         ← 事件处理器 (订阅 workflow/message 事件)
│   ├── entity/          ← 18 个 SeaORM Entity (872 行)
│   ├── service/         ← 11 个业务 service (4122 行)
│   ├── handler/         ← 7 个路由 handler (1493 行)
│   ├── dto/             ← 7 个请求/响应 DTO (814 行)
│   ├── validation.rs    ← 输入验证逻辑 (302 行, 57 纯函数测试)
│   ├── masking.rs       ← PII 数据脱敏 (手机号/身份证)
│   └── seed.rs          ← 租户种子数据 + 软删除清理

实体模型（18 个实体，对应数据库表 + 1 个文章实体）

域	实体
患者管理	patient, patient_family_member, patient_tag, patient_tag_relation, patient_doctor_relation
医护管理	doctor_profile
健康数据	health_record, vital_signs, lab_report, health_trend
预约排班	appointment, doctor_schedule
随访管理	follow_up_task, follow_up_record
咨询管理	consultation_session, consultation_message
内容管理	article

权限码（14 个）

权限码	说明
health.patient.list / health.patient.manage	患者查看/管理
health.health-data.list / health.health-data.manage	健康数据查看/管理
health.appointment.list / health.appointment.manage	预约查看/管理
health.follow-up.list / health.follow-up.manage	随访查看/管理
health.consultation.list / health.consultation.manage	咨询查看/管理
health.doctor.list / health.doctor.manage	医护查看/管理
health.articles.list / health.articles.manage	文章查看/管理

集成契约

方向	模块	接口	触发时机
提供 →	erp-server	HealthModule	启动时注册 /api/v1/health/*
调用 →	erp-core	EventBus	发布/订阅领域事件
关联 →	erp-auth	users 表 (user_id FK)	患者/医护关联账号
订阅 ←	erp-workflow	workflow.task.completed	随访任务状态更新
订阅 ←	erp-message	message.sent	咨询会话 last_message_at

3. 代码逻辑

API 前缀: /api/v1/health/

关键端点分组：

• /patients — 患者列表/详情/标签管理/健康摘要/家庭成团/医生关联
• /patients/{id}/vital-signs — 日常监测数据（血压/心率/体重/血糖）
• /patients/{id}/lab-reports — 化验报告（JSONB 指标数据）
• /patients/{id}/health-records — 健康档案
• /patients/{id}/trends — 健康趋势报告（自动/手动生成，时间序列查询）
• /vital-signs/trend — 小程序趋势（JWT user → patient）
• /vital-signs/today — 小程序当日体征摘要
• /appointments — 预约管理 + 状态变更（pending→confirmed→completed/cancelled/no_show）
• /appointments/{id}/status — 预约状态流转（乐观锁）
• /doctor-schedules — 排班管理 CRUD + 日历视图
• /doctor-schedules/calendar — 月度排班日历
• /follow-up-tasks — 随访任务 CRUD + 逾期自动标记
• /follow-up-tasks/{id}/records — 随访记录
• /consultation-sessions — 咨询会话管理 + 消息 + 导出 + 关闭
• /consultation-messages — 咨询消息发送
• /doctors — 医护档案 CRUD
• /articles — 健康文章 CRUD

预约并发控制

创建预约时使用原子 CAS（事务内）：

1. 查找匹配日期+时段的排班
2. 原子 UPDATE current_appointments + 1 WHERE current < max
3. CAS 成功后 INSERT 预约记录
4. 事务保证 CAS + INSERT 原子性

预约状态机

pending → confirmed → completed
                   → no_show → confirmed (重新确认)
                   → cancelled
pending → cancelled

PII 数据保护

• HealthCrypto: AES-256-GCM 加密敏感字段，HMAC-SHA256 哈希身份证号
• masking.rs: 手机号脱敏 138****1234，身份证脱敏 110****1111
• 生产密钥通过环境变量 ERP__HEALTH__AES_KEY / ERP__HEALTH__HMAC_KEY 配置

后台任务

• 随访逾期检查器 — 每 5 分钟扫描 follow_up_task 中超过 planned_date 仍未完成的任务

⚡ 不变量: 预约创建必须走原子 CAS，不能用 read-then-write ⚡ 不变量: patient.user_id 允许 NULL（先建档后绑定） ⚡ 不变量: doctor_id 在创建预约时必填（关联排班做 CAS） ⚡ 不变量: 状态流转必须带 version 字段（乐观锁）

4. 活跃问题 + 陷阱

当前状态: ✅ 已完成

18 实体、14 权限、13 Web 页面、20 小程序页面，全链路流通性验证通过。

待优化

问题	级别	说明
文件上传基础能力	P1	化验单/体检报告需要文件存储服务
健康趋势图 ECharts	P1	小程序已有 echarts 集成，Web 端待接入
咨询导出 Excel	P2	后端已有 rust_xlsxwriter 依赖，导出端点已实现

全链路验证结果（2026-04-25）

链路	API	前端 UI	状态
医生 CRUD	创建/搜索/编辑	医护管理页面	✅
排班管理	创建/列表/日历	排班管理页面	✅
预约管理	创建+状态流转	预约列表/新建弹窗	✅
随访管理	创建→进行→完成	随访列表/操作	✅
咨询管理	创建会话+消息	咨询列表/导出	✅
患者详情	详情/编辑/标签	详情页+健康数据标签	✅

5. 变更记录

日期	变更
2026-04-25	全面更新为已实现状态：18 实体、14 权限、全链路验证通过
2026-04-23	创建模块 wiki 页，设计规格确认