# Phase 2 交接文档 — 患者体验（2026 年 8-9 月）

> 日期: 2026-05-04 | 类型: 交接文档 | Phase: Phase 2

## 背景

Phase 0（基础加固）和 Phase 1（关怀引擎 MVP）已全部完成。Phase 2 的目标是将患者和家庭体验从"健康数据查看器"转变为"被关怀的体验"。

## Phase 0 + Phase 1 完成状态

### Phase 0（全部完成）
- AI 自动分析管道修复（建议生成 + 事件发布）
- `ai.analysis.requested` 事件消费连接
- 建议状态生命周期
- 4 个千行 service 文件拆分
- 事件测试补全
- 核心健康管理页面测试
- 护士工作台 Phase 1

### Phase 1（全部完成，8/8 项）
| # | 功能 | 提交 |
|---|------|------|
| 1 | 每日关怀工作台（Plan B 工作流驱动） | 已完成 |
| 2 | 护理计划（Care Plan）实体和服务层 | 已完成 |
| 3 | 透析专用风险评分（KDIGO 规则） | 已完成 |
| 4 | 班次管理与护士分配 | `7b17f94` |
| 5 | BLE 网关后端接入端点（API Key + 批量上传） | `7e57565` |
| 6 | "关怀已送达"通知管道 | 已完成 |
| 7 | 透析会话工作流（BPMN 集成） | `0a9272b` |
| 8 | 家庭成员健康代理（同意 + 查看） | `95fa09c` |

---

## Phase 2 任务清单

### P2-1: 老年患者小程序重设计（年龄适配 UI）— XL

**目标**: 65+ 患者可无障碍使用（大字体、高对比度、≤3 步操作）

**当前状态**: 小程序 182 源文件 / 40+ 页面，使用 Taro 4.2 + React 18。无年龄适配设计。

**实施方向**:
1. 在小程序样式层增加 `--elderly-*` CSS 变量/token：
   - 基础字号 18-22px（标准 14px）
   - 触摸目标 ≥ 48px
   - 对比度 7:1（WCAG AAA）
   - 导航最多 4-5 项
2. 新建 `pages/elderly/` 区块，着陆页设计：
   - 温暖问候 + 护士照片名字
   - "您的护理团队 X 小时前查看了您的健康数据，一切稳定"
   - 一个大号"呼叫护士"按钮
   - 用药提醒（大复选框）
3. 简化导航：从当前 TabBar 5 项减少到 3-4 项
4. 后端已有 `health.family-proxy` API 支持家庭成员查看健康摘要

**关键文件**:
- `apps/miniprogram/src/app.config.ts` — 路由和 TabBar 配置
- `apps/miniprogram/src/styles/` — 全局样式
- `apps/miniprogram/src/pages/` — 页面目录
- 后端 API: `GET /health/family/patients/{id}/health-summary`

**验收标准**: 65+ 患者可在 3 步内完成核心操作（查看今日关怀 / 确认用药 / 呼叫护士）

---

### P2-2: 透析专属健康教育内容管道 — M

**目标**: 基于患者当前风险指标智能推送肾病教育内容

**当前状态**: 已有完整 CMS（`erp-health` 文章模块：article/article_category/article_tag + 审核工作流 + 阅读统计）

**实施方向**:
1. 利用现有 CMS 策展透析患者专属内容库：
   - "认识你的透析指标"
   - "透析间期如何控制水分"
   - "高磷食物避坑指南"
   - "什么时候该联系护理团队"
2. 基于患者 KDIGO 风险评分自动推送相关文章
   - 血磷高风险 → 推送高磷食物指南
   - 体重增长过快 → 推送水分控制指南
   - Kt/V 不达标 → 推送透析充分性科普
3. 后端新增"智能推送"服务：读取患者风险评分 → 匹配文章标签 → 创建推送记录

**关键文件**:
- `crates/erp-health/src/service/article_service.rs` — 已有文章 CRUD
- `crates/erp-health/src/entity/article.rs` — 文章实体
- `crates/erp-health/src/entity/article_tag.rs` — 标签实体
- Phase 1 新增的 KDIGO 评分服务 — 风险评分来源
- `crates/erp-health/src/service/ai_action_dispatcher.rs` — 可扩展推送逻辑

**验收标准**: 高风险透析患者自动收到与当前风险相关的教育文章

---

### P2-3: BLE 网关试点部署（10 位患者） — L

**目标**: 10 位透析患者居家使用 BLE 网关，体征数据自动流入系统

**当前状态**: 后端 BLE 网关接入已完成（Phase 1 #5）：
- `ble_gateways` 表 + `gateway_patient_bindings` 表
- API Key SHA-256 认证中间件
- 批量上传端点 `POST /health/gateway/upload`（多患者批量）
- 心跳端点 `POST /health/gateway/heartbeat`
- 复用 `device_reading_service::batch_create_readings` 管道
- 迁移 `m20260505_000113_create_ble_gateways.rs`

**剩余工作**:
1. 采购/选型商用 BLE 网关（如 Teltonika、Quectel）
2. 网关固件配置：连接 BLE 设备（血压计/血糖仪/体重秤）→ HTTPS POST 到 HMS
3. 10 位患者试点部署 + 数据验证
4. 前端管理页面（网关状态监控，已有后端 CRUD）

**关键文件**:
- `crates/erp-health/src/service/ble_gateway_service.rs` — 网关管理 + 上传处理
- `crates/erp-health/src/gateway_auth.rs` — API Key 认证
- `crates/erp-health/src/dto/ble_gateway_dto.rs` — GatewayUploadReq（多患者批量格式）
- `crates/erp-server/src/main.rs` — 网关路由注册（gateway_auth 中间件层）

**验收标准**: 10 位患者居家体征数据每日自动上传，网关在线率 > 95%

---

### P2-4: 多 Provider AI + 成本感知路由 — M

**目标**: 简单分析走本地规则，复杂分析走 LLM，Provider 不可用时自动回退

**当前状态**: 仅 Claude 单 Provider，`LocalRulesEngine` 已存在但未集成到路由层

**实施方向**:
1. 扩展 `AiConfig` 使用当前死字段（model/max_tokens/temperature/cache_ttl/rate_limit）
2. 实现路由策略：
   - 阈值检查 → 本地规则引擎（零成本）
   - 趋势解读/化验单分析 → Claude（高成本）
   - Provider 不可用 → 回退本地规则 + 标记"降级分析"
3. 添加 token 用量追踪（每次分析记录 input_tokens/output_tokens/cost_usd）
4. 缓存生效：`find_cached` 已存在但从未被调用，接入分析管道

**关键文件**:
- `crates/erp-ai/src/service/auto_analysis.rs` — 自动分析批处理
- `crates/erp-ai/src/service/local_rules_engine.rs` — 本地规则引擎
- `crates/erp-ai/src/entity/ai_config.rs` — AI 配置实体（有死字段待激活）
- `crates/erp-ai/src/entity/ai_suggestion.rs` — 建议实体（Phase 0 新增）
- `crates/erp-ai/src/module.rs` — 模块注册

**验收标准**: Provider 不可用时系统自动降级到本地规则，用户无感知中断

---

### P2-5: 关怀结果测量（干预前后对比） — M

**目标**: 干预后 7/14/30 天体征对比可量化

**当前状态**: Phase 1 已有 `care_plan_outcomes` 表（metric, baseline, target, current, measured_at）

**实施方向**:
1. 扩展 `care_plan_outcomes` 服务：自动从 `vital_signs` / `device_readings` 聚合测量值
2. 实现干预前后对比 API：
   - 输入：care_plan_item_id + 干预日期
   - 输出：baseline（干预前 7 天均值）vs current（干预后 7/14/30 天均值）
3. 前端趋势图展示干预效果
4. 接入事件流：`care.action.performed` 事件触发测量开始

**关键文件**:
- `crates/erp-health/src/entity/care_plan_outcome.rs` — 预后测量实体
- `crates/erp-health/src/service/care_plan_service.rs` — 护理计划服务
- `crates/erp-health/src/service/vital_signs_daily_service.rs` — 日聚合服务
- `crates/erp-health/src/service/trend_service.rs` — 趋势分析服务

**验收标准**: 护士可在护理计划详情中查看干预前后的体征对比图表

---

### P2-6: 读副本 + 分区用于分析查询 — M

**目标**: PostgreSQL 按月分区 `device_readings`，添加读副本连接用于分析查询

**实施方向**:
1. `device_readings` 表按月分区（当前 ~100万行/年，BLE 部署后快速增长）
2. SeaORM 配置读副本连接（`DatabaseConnection` 支持多连接）
3. 分析查询（趋势/统计/FHIR）路由到读副本
4. 超过 2 年的读数归档冷存储

**关键文件**:
- `crates/erp-server/migration/src/` — 新增分区迁移
- `crates/erp-health/src/state.rs` — HealthState 可扩展为双连接
- `crates/erp-health/src/service/stats_service.rs` — 统计查询
- `crates/erp-health/src/service/trend_service.rs` — 趋势查询

---

### P2-7: 机构运营仪表盘 — L

**目标**: 管理层可查看关怀质量指标

**当前状态**: 已有基础统计端点（`/health/admin/statistics/dashboard`、`personal-stats`、`system-health`）

**实施方向**:
1. 扩展统计 API：
   - 关怀动作完成率（护士执行 / AI 建议）
   - 患者留存率（月度）
   - AI 建议准确率（护士采纳 / AI 总建议）
   - 平均关怀响应时间（AI 发现风险 → 护士执行关怀）
   - 北极星指标：每位患者每周收到的关怀动作数
2. 前端仪表盘页面（Ant Design Charts）
3. 数据来源：action_inbox + ai_suggestion + care_plan + 告警记录

**关键文件**:
- `crates/erp-health/src/service/stats_service.rs` — 已有统计服务
- `crates/erp-health/src/handler/stats_handler.rs` — 已有统计 Handler
- `apps/web/src/pages/` — 前端页面

---

## 实施建议

### 优先顺序

1. **P2-4 多 Provider AI**（M）— 降级能力是后续所有 AI 相关工作的基础
2. **P2-5 关怀结果测量**（M）— 需要积累数据，越早启动越好
3. **P2-2 透析教育内容**（M）— 后端改动小，可快速交付
4. **P2-3 BLE 网关试点**（L）— 需要硬件采购，后端已就绪
5. **P2-1 老年患者 UI**（XL）— 工作量最大，但依赖后端 API 已完成
6. **P2-6 读副本+分区**（M）— 数据量增长后才有必要
7. **P2-7 机构仪表盘**（L）— 需要前面各项数据积累

### 技术注意事项

1. **星型依赖架构不变** — 所有 crate 仅依赖 erp-core，跨模块走 EventBus
2. **迁移编号从 `m20260505_000116` 开始** — 当前最后迁移是 `000115_family_member_health_proxy`
3. **Handler 模式** — `State(state): State<HealthState>`, `Extension(ctx): Extension<TenantContext>`, `require_permission(&ctx, "health.xxx.list")?`, 返回 `Result<Json<ApiResponse<T>>, AppError>`
4. **ctx.user_id 是 Uuid 不是 Option** — 直接使用，不需要 `ok_or_else`
5. **前端小程序在 `apps/miniprogram/`** — Taro 4.2 + React 18
6. **前端 Web 在 `apps/web/`** — React 19 + Ant Design + Vite
7. **编译命令**: `cargo check`（编译检查）/ `cargo test -p erp-health`（单 crate 测试）/ `cargo test --workspace`（全量测试）
8. **数据库连接信息**: 见 `wiki/infrastructure.md` §2

### Phase 2 验收标准（总体）

| 指标 | 目标 |
|------|------|
| 10 位患者 BLE 网关试点 | 居家体征数据自动流入系统 |
| 老年患者 UI | 65+ 患者可无障碍使用（大字体、高对比度、≤3 步操作） |
| 关怀结果测量 | 干预后 7/14/30 天体征对比可量化 |
| 机构仪表盘 | 管理层可查看关怀运营指标 |