---
title: erp-health 健康管理模块
updated: 2026-04-23
status: developing
tags: [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 个 | 16+ 强类型医疗实体 |
| JSONB 动态存储 | 医疗数据需要强类型、索引、关联 |
| 无自定义 API | 趋势分析、统计报表需专用端点 |
| 无文件上传 | 化验单、体检报告需存储 |
| 沙箱限制 | 无法引入加密、AI、外部 API |

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

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

### 核心架构选择

- **原生 Rust crate** — 与 erp-auth、erp-workflow 同等地位，直接访问数据库
- **固有方法暴露路由** — `public_routes()` / `protected_routes()`，在 erp-server 中 `.nest("/api/v1/health", ...)`
- **EventBus 通信** — 发布 `patient.created`、`appointment.confirmed` 等，订阅 `workflow.task.completed`

## 2. 关键文件 + 数据流

### 目录结构

```
crates/erp-health/
├── src/
│   ├── lib.rs           ← ErpModule trait + routes()
│   ├── error.rs         ← HealthError → AppError
│   ├── state.rs         ← HealthState
│   ├── entity/          ← 16 个 SeaORM Entity
│   ├── service/         ← 5 个业务 service
│   ├── handler/         ← 5 个路由 handler
│   ├── dto/             ← 请求/响应结构体
│   └── event.rs         ← 事件定义和处理器
```

### 实体模型（16 张表）

| 域 | 实体 |
|----|------|
| 患者管理 | 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 |

### 集成契约

| 方向 | 模块 | 接口 | 触发时机 |
|------|------|------|---------|
| 提供 → | [[erp-server]] | `protected_routes()` | 启动时注册 `/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/trends` — 健康趋势报告（自动/手动生成）
- `/appointments` — 预约管理（状态机: pending→confirmed→completed）
- `/doctor-schedules` — 排班管理（日历视图）
- `/follow-up-tasks` — 随访任务（逾期自动标记）
- `/consultation-sessions` — 咨询会话管理

### 预约并发控制

创建预约时使用原子 CAS：`UPDATE doctor_schedule SET current_appointments = current_appointments + 1 WHERE id = $1 AND current_appointments < max_appointments RETURNING *`

### 随访自动链接

`follow_up_record.next_follow_up_date` 不为空时，自动创建新的 `follow_up_task`。

### 权限码

`health.patient.list/manage` · `health.health-data.list/manage` · `health.appointment.list/manage` · `health.follow-up.list/manage` · `health.consultation.list/manage` · `health.doctor.list/manage`

⚡ **不变量**: 预约创建必须走原子 CAS，不能用 read-then-write
⚡ **不变量**: `patient.user_id` 允许 NULL（先建档后绑定）
⚡ **不变量**: `consultation_message` 对 `created_at` 按月分区，超 1 年归档

## 4. 活跃问题 + 陷阱

### 当前状态: 🔧 开发中

设计规格已确认，尚未开始编码。

### 待解决

| 问题 | 级别 | 说明 |
|------|------|------|
| 文件上传基础能力 | P1 | 化验单/体检报告需要文件存储服务 |
| ECharts 趋势图 | P1 | 前端健康趋势可视化 |
| 导出功能 | P2 | 随访台账/咨询记录导出 Excel |

## 5. 变更记录

| 日期 | 变更 |
|------|------|
| 2026-04-23 | 创建模块 wiki 页，设计规格确认 |