---
title: erp-health 健康管理模块
updated: 2026-05-03
status: implemented
tags: [health, patient, appointment, follow-up, consultation, content, points, dialysis, offline-events]
---

# 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** — 已迁移到 `erp_core::crypto::PiiCrypto`（AES-256-GCM + KEK/DEK 分层 + HMAC 盲索引），`crypto.rs` 保留兼容层

## 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/          ← 46 个 SeaORM Entity
│   ├── service/         ← 25 个业务 service + validation + masking + trend
│   ├── handler/         ← 21 个路由 handler
│   ├── dto/             ← 15 个请求/响应 DTO
│   ├── validation.rs    ← 输入验证逻辑 (302 行, 104 纯函数测试)
│   ├── masking.rs       ← PII 数据脱敏 (手机号/身份证)
│   ├── health_provider_impl.rs ← AI 数据桥接（当前 stub）
│   └── seed.rs          ← 租户种子数据 + 软删除清理
```

### 实体模型（46 个实体）

| 域 | 实体 |
|----|------|
| 患者管理 | patient, patient_family_member, patient_tag, patient_tag_relation, patient_doctor_relation, patient_devices, blind_index, consent |
| 医护管理 | doctor_profile, doctor_schedule |
| 健康数据 | health_record, vital_signs, vital_signs_hourly, daily_monitoring, lab_report, health_trend, diagnosis, medication_record, device_readings |
| 透析管理 | dialysis_record |
| 预约排班 | appointment |
| 随访管理 | follow_up_task, follow_up_record, follow_up_template, follow_up_template_field |
| 咨询管理 | consultation_session, consultation_message |
| 内容管理 | article, article_category, article_tag, article_article_tag, article_revision |
| 告警系统 | alerts, alert_rules, critical_alert, critical_alert_response, critical_value_threshold |
| 积分商城 | points_account, points_rule, points_product, points_order, points_transaction, points_checkin |
| 线下活动 | offline_event, offline_event_registration |

### 权限码（39 个）

| 权限码 | 说明 |
|--------|------|
| `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` | 文章查看/管理 |
| `health.articles.review` | 文章审核 |
| `health.points.list` / `health.points.manage` | 积分查看/管理 |
| `health.device-readings.list` / `health.device-readings.manage` | 设备数据查看/管理 |
| `health.devices.list` / `health.devices.manage` | 设备查看/管理 |
| `health.alerts.list` / `health.alerts.manage` | 告警查看/管理 |
| `health.alert-rules.list` / `health.alert-rules.manage` | 告警规则查看/管理 |
| `health.critical-alerts.list` / `health.critical-alerts.manage` | 危急值告警查看/管理 |
| `health.critical-value-thresholds.list` / `health.critical-value-thresholds.manage` | 危急值阈值查看/管理 |
| `health.follow-up-templates.list` / `health.follow-up-templates.manage` | 随访模板查看/管理 |
| `health.daily-monitoring.list` / `health.daily-monitoring.manage` | 日常监测查看/管理 |
| `health.consent.list` / `health.consent.manage` | 知情同意查看/管理 |
| `health.medication-records.list` / `health.medication-records.manage` | 用药记录查看/管理 |
| `health.medication-reminders.list` / `health.medication-reminders.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` | 消息通知（预留） |
| 订阅 ← | 设备同步 | `device.readings.synced` | 触发告警引擎评估 |
| 订阅 ← | 事件总线 | `patient.*` | 发送欢迎消息 |
| 订阅 ← | 事件总线 | `appointment.*` | 通知 + 号源释放 |
| 订阅 ← | 事件总线 | `follow_up.overdue` | 升级通知 |
| 订阅 ← | 事件总线 | `health_data.critical_alert` | 创建危急值告警 |

## 3. 代码逻辑

### API 前缀: `/api/v1/health/`

关键端点分组：
- `/patients` — 患者列表/详情/标签管理/健康摘要/家庭成员/医生关联/知情同意
- `/patients/{id}/vital-signs` — 日常监测数据（血压/心率/体重/血糖）
- `/patients/{id}/lab-reports` — 化验报告（JSONB 指标数据）
- `/patients/{id}/health-records` — 健康档案
- `/patients/{id}/trends` — 健康趋势报告（自动/手动生成，时间序列查询）
- `/patients/{id}/diagnoses` — 诊断记录
- `/patients/{id}/dialysis-records` — 透析记录
- `/patients/{id}/daily-monitoring` — 日常监测记录
- `/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 + 审核状态机（draft→pending_review→published）
- `/articles/{id}/submit` — 提交审核
- `/articles/{id}/approve` — 批准发布
- `/articles/{id}/reject` — 拒绝（附原因）
- `/articles/{id}/unpublish` — 撤回已发布文章
- `/articles/{id}/view` — 增加阅读计数
- `/article-categories` — 分类 CRUD
- `/article-tags` — 标签 CRUD
- `/points/rules` — 积分规则 CRUD
- `/points/products` — 积分商品 CRUD
- `/points/orders` — 积分订单
- `/points/accounts` — 积分账户 + 签到
- `/offline-events` — 线下活动 CRUD + 报名
- `/stats/*` — 统计概览（透析/化验/预约/体征上报率）
- `/critical-value-thresholds` — 危急值阈值管理

### 预约并发控制

创建预约时使用原子 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
```

### 文章审核状态机

```
draft → pending_review → published → draft (撤回)
                       → rejected → pending_review (重新提交)
```

- `submit` — draft/rejected → pending_review
- `approve` — pending_review → published（自动设置 published_at、reviewed_by）
- `reject` — pending_review → rejected（附 review_note）
- `unpublish` — published → draft

### PII 数据保护

- `PiiCrypto`（erp-core）: AES-256-GCM 加密，KEK/DEK 分层管理（每租户独立 DEK）
- `masking.rs`: 手机号脱敏 `138****1234`，身份证脱敏 `110****1111`
- HMAC 盲索引: 支持加密字段的等值查询（手机号、身份证号搜索）
- 生产密钥通过环境变量 `ERP__CRYPTO__KEK` 配置 KEK，DEK 由 `tenant_crypto_keys` 表管理

### 事件发布（25 个事件）

| 服务 | 事件类型 |
|------|---------|
| patient_service | patient.created, patient.updated |
| appointment_service | appointment.created, appointment.confirmed, appointment.cancelled |
| consultation_service | consultation.opened, consultation.closed |
| article_service | article.published, article.rejected |
| consent_service | consent.granted, consent.revoked |
| device_reading_service | device.readings.synced |
| doctor_service | doctor.online_status_changed |
| daily_monitoring_service | daily_monitoring.created |
| follow_up_service | follow_up.created, follow_up.completed, follow_up.overdue |
| health_data_service | lab_report.uploaded, health_data.critical_alert |
| points_service | points.earned, points.exchanged, points.expired |
| alert_engine | alert.triggered |

所有消费者都有幂等保护（`is_event_processed` / `mark_event_processed`）。

### 后台任务

- 随访逾期检查器 — 每 6 小时扫描 `follow_up_task` 中超过 `planned_date` 仍未完成的任务
- 积分过期清理 — 每 24 小时扫描并处理过期积分
- 预约提醒 — 每 1 小时扫描即将到来的预约并发送提醒

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

## 4. 活跃问题 + 陷阱

### 当前状态: ✅ 已完成

46 实体、26 个 handler（~160 个 pub fn）、39 权限、25+ Web 路由页面 + 工作台组件，~27k 行 Rust 代码。状态转换验证统一到 validation 模块（104 纯函数测试）。24 个集成测试文件覆盖所有子域。

### 待优化

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

### 2026-04-30 审计发现

**功能域评分**（审计报告 8 个域）：

| 域 | 评分 | 关键问题 |
|----|------|---------|
| 患者管理 | 93% | 健康摘要仅 MP，家庭医生管理仅 Web |
| 健康数据 | 85% | 小程序丢失晚间血压/体温/血氧字段 |
| 预约管理 | 95% | Web/MP 基本对齐 |
| 随访管理 | 88% | MP 仅列表+创建 |
| 咨询管理 | 94% | 高度对齐 |
| 内容管理 | 86% | MP 仅只读 published 文章 |
| 积分商城 | 90% | 角色分叉正常 |
| 告警系统 | 87% | 前端权限码拼写错误（`alert` vs `alerts`） |

**关键审计发现**：

| 发现 | 严重性 | 说明 |
|------|--------|------|
| 告警管理按钮不显示 | CRITICAL | 前端 `health.alert.manage` 缺 s，应为 `health.alerts.manage` |
| 小程序晚间血压丢失 | CRITICAL | indicator_type 固定映射 `*_morning`，`*_evening` 从未写入 |
| 小程序透析管理缺失 | HIGH | 后端 12 路由完整，小程序 0 入口 |
| 小程序知情同意缺失 | HIGH | 后端完整，小程序 0 入口 |
| 运行时日志不足 | HIGH | 26 个 service 仅 11 处 tracing |
| 14 事件无消费者 | LOW | 发布到 EventBus，SSE 推送仍有价值 |
| DTO 覆盖率 | 100% | 105 个 DTO 完整覆盖 23 个 handler |
| 调用链连通性 | 100% | Handler→Service→Entity 全部连通 |

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

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

## 5. 变更记录

| 日期 | 变更 |
|------|------|
| 2026-05-01 | 审计数据更新：权限码 22→39、审计发现（2 CRITICAL + 3 HIGH）、功能域评分、DTO/调用链 100% |
| 2026-04-28 | 全面数据刷新：45 实体（+10 告警/设备/随访模板/体征小时聚合等）、21 handler、39 权限、25+ Web 路由、事件系统完善（25 发布/25+ 消费者）、3 个后台任务、PiiCrypto 迁移到 erp-core |
| 2026-04-26 | 全面更新：34 实体（+13 积分/透析/诊断/日常监测/线下活动/危急值/知情同意）、16 handler、stats 统计端点、validation 统一模块（83 测试）、PII 加密扩展（doctor_profile/dialysis_record/lab_report/diagnosis key_version） |
| 2026-04-26 | 新增内容管理：article_category/article_tag/article_article_tag/article_revision 4 实体、审核状态机 |
| 2026-04-25 | 全面更新为已实现状态：18 实体、14 权限、全链路验证通过 |
| 2026-04-23 | 创建模块 wiki 页，设计规格确认 |