# HMS 三端一致性检查报告

> 日期: 2026-05-08 | 审查范围: 后端 API / Web 前端 / 微信小程序

## 一、审查概要

| 维度 | 状态 | 说明 |
|------|------|------|
| 功能设计一致性 | ⚠️ 基本一致 | 三端定位不同（管理端/患者端/医护端），功能差异多为设计意图 |
| 数据接口一致性 | ✅ 高度一致 | 小程序 91 个端点 / Web 270+ 端点，路径/参数/响应格式统一 |
| 业务流程链路一致性 | ⚠️ 存在差异 | 透析管理、积分商城、AI 分析存在端间覆盖不完整 |

**总体评分**: **一致性 82%** — 不一致项多为设计意图（端定位不同），少量为遗漏需修复。

---

## 二、三端功能覆盖矩阵

### 2.1 完整覆盖（三端一致）✅

| 业务模块 | 后端 | Web | 小程序 | 说明 |
|----------|------|-----|--------|------|
| 患者管理 CRUD | ✅ | ✅ | ✅（患者端） | Web 管理端 + MP 患者端 |
| 预约管理 | ✅ | ✅ | ✅ | 完整覆盖 |
| 咨询管理 | ✅ | ✅ | ✅ | 含医生端会话处理 |
| 随访管理 | ✅ | ✅ | ✅ | Web 管理 + MP 医生端 + 患者端 |
| 化验报告 | ✅ | ✅ | ✅ | 含医生端审阅 |
| 告警管理 | ✅ | ✅ | ✅ | 确认/忽略/解除三端一致 |
| 健康记录 | ✅ | ✅ | ✅ | CRUD 完整 |
| 知情同意 | ✅ | ✅ | ✅ | 授权/撤回 |
| 诊断记录 | ✅ | ✅ | ✅ | CRUD 完整 |
| 消息通知 | ✅ | ✅ | ✅ | 列表/已读/未读（MP 不支持 SSE） |
| 日常监测 | ✅ | ✅ | ✅ | 创建/查看 |
| 设备读数 | ✅ | ✅ | ✅ | BLE 上传 + 查询 |

### 2.2 部分覆盖（存在差异）⚠️

| 业务模块 | 后端 | Web | 小程序 | 差异说明 |
|----------|------|-----|--------|----------|
| 透析管理 | ✅ 46 端点 | ⚠️ 冻结 | ✅ 完整 | **Web 端路由标记 frozen**，小程序医生端完整可用 |
| 透析处方 | ✅ | ❌ | ✅ | **Web 端无处方管理页面**，小程序医生端有 |
| 积分商城（患者） | ✅ | ❌ | ✅ | 签到/兑换/商品浏览仅小程序 |
| 积分商城（管理） | ✅ | ✅ | ❌ | 规则/商品/订单管理仅 Web |
| AI 分析（SSE） | ✅ | ✅ | ❌ | 小程序不支持 SSE 流式，仅查看历史 |
| AI 建议审批 | ✅ | ✅ | ❌ | 仅 Web 端可审批 |
| 文章审核流程 | ✅ | ✅ | ❌ | submit/approve/reject 仅 Web |
| 班次管理 | ✅ | ✅ | ❌ | 管理功能仅 Web |
| 护理计划 | ✅ | ⚠️ 冻结 | ❌ | Web 冻结，小程序无 |
| 排班管理 | ✅ | ✅ | ❌ | 创建/管理仅 Web，小程序仅查看 |
| 设备管理 | ✅ | ✅ | ❌ | 解绑/管理仅 Web，小程序仅 BLE 同步 |
| BLE 网关管理 | ✅ | ✅ | ❌ | 注册/绑定/管理仅 Web |
| 危急值阈值 | ✅ | ✅ | ⚠️ | Web 可管理，MP 仅查看 public 端点 |
| OAuth 客户端 | ✅ | ✅ | ❌ | FHIR 合作方管理仅 Web |
| 用药提醒 | ✅ | ❌ | ✅ | **Web 端无用药提醒页面**，小程序有 CRUD |

### 2.3 单端独有（设计意图，非遗漏）

| 独有功能 | 端 | 说明 |
|----------|-----|------|
| 用户/角色/权限管理 | Web | 管理后台职责 |
| 组织/部门/岗位 | Web | 管理后台职责 |
| 工作流引擎 | Web | 管理后台职责 |
| 插件系统 | Web | 管理后台职责 |
| 系统设置/字典/编号规则 | Web | 管理后台职责 |
| 微信登录+手机号绑定 | MP | 小程序专属 |
| 每日签到 | MP | 小程序用户粘性功能 |
| 线下活动报名 | MP | 患者端功能 |
| 法律文件（用户协议/隐私） | MP | 小程序合规要求 |
| BLE 设备蓝牙连接 | MP | 小程序蓝牙能力 |
| 埋点数据上报 | MP | 小程序分析功能 |
| FHIR R4 接口 | 后端 | 标准互操作，无前端页面 |

---

## 三、API 接口一致性分析

### 3.1 请求格式一致性 ✅

| 维度 | 状态 | 说明 |
|------|------|------|
| URL 路径前缀 | ✅ 一致 | 三端统一 `/api/v1/` |
| 分页参数 | ✅ 一致 | `page`, `page_size`, 响应 `PaginatedResponse<T>` |
| 乐观锁参数 | ✅ 一致 | 更新/删除均带 `version` 字段 |
| 认证方式 | ✅ 一致 | Bearer JWT Token |
| 多租户 | ✅ 一致 | 中间件自动注入 `tenant_id` |

### 3.2 接口覆盖统计

| 指标 | 后端 | Web 前端 | 小程序 |
|------|------|----------|--------|
| API 端点总数 | ~300+ | ~270 | ~91 |
| Health 端点 | ~200 | ~140 | ~70 |
| AI 端点 | ~18 | ~18 | ~3 |
| Auth 端点 | ~8 | ~4 | ~4 |
| Config/基础端点 | ~74 | ~108 | ~4 |
| 消息端点 | ~7 | ~9 | ~4 |

### 3.3 发现的接口不一致

| # | 不一致项 | 后端 | Web | 小程序 | 严重度 |
|---|----------|------|-----|--------|--------|
| 1 | **透析处方 CRUD** | ✅ 完整端点 | ❌ 无 API 调用 | ✅ 完整调用 | **HIGH** |
| 2 | **用药提醒 CRUD** | ✅ 完整端点 | ❌ 无 API 调用 | ✅ 完整调用 | **MEDIUM** |
| 3 | **小程序趋势查询** `GET /health/vital-signs/trend` | ✅ 专属端点 | ❌ 使用患者级趋势 | ✅ 专属调用 | LOW（设计意图） |
| 4 | **小程序今日体征** `GET /health/vital-signs/today` | ✅ 专属端点 | ❌ 不需要 | ✅ 专属调用 | LOW（设计意图） |
| 5 | **公开阈值** `GET /health/critical-value-thresholds/public` | ✅ 专属端点 | ❌ 使用管理端点 | ✅ 专属调用 | LOW（设计意图） |
| 6 | **小程序未调用透析审阅** `PUT /health/dialysis-records/:id/review` | ✅ | ❌ 冻结 | ✅ 医生端调用 | LOW |
| 7 | **AI SSE 端点** | ✅ 4 个 SSE | ✅ 调用 | ❌ 不支持 SSE | LOW（平台限制） |

---

## 四、业务流程链路一致性

### 4.1 用户认证流程

| 步骤 | Web | 小程序 | 一致性 |
|------|-----|--------|--------|
| 登录方式 | 账号密码 `POST /auth/login` | 微信授权 `POST /auth/wechat/login` | ⚠️ 设计意图不同 |
| Token 管理 | 自动刷新（过期前 30s） | 自动刷新（401 触发） | ✅ 机制一致 |
| 登出 | `POST /auth/logout` | 清除本地 token | ✅ |
| 手机号绑定 | N/A | `POST /auth/wechat/bind-phone` | ⚠️ MP 独有 |

**结论**: 认证流程符合各端定位，设计合理。

### 4.2 预约流程

| 步骤 | Web | 小程序 | 一致性 |
|------|-----|--------|--------|
| 选择医生 | ✅ 医生列表 | ✅ 医生列表 | ✅ |
| 查看排班 | ✅ 日历视图 | ✅ 日历视图 | ✅ |
| 创建预约 | ✅ `POST /health/appointments` | ✅ 相同 | ✅ |
| 查看预约 | ✅ 列表+详情 | ✅ 列表+详情 | ✅ |
| 取消预约 | ✅ `PUT /appointments/:id/status` | ✅ 相同 | ✅ |

**结论**: 预约流程三端完全一致。

### 4.3 健康数据录入流程

| 步骤 | Web | 小程序 | 一致性 |
|------|-----|--------|--------|
| 体征录入 | ✅ `POST /patients/:id/vital-signs` | ✅ 相同 | ✅ |
| 查看趋势 | ✅ `GET /patients/:id/trends` | ✅ `GET /vital-signs/trend` | ⚠️ 路径不同 |
| 今日概览 | ❌ 无此功能 | ✅ `GET /vital-signs/today` | ⚠️ MP 独有 |
| 日常监测 | ✅ | ✅ | ✅ |
| 化验报告上传 | ✅ 含文件上传 | ✅ 仅查看 | ⚠️ MP 无上传 |

**结论**: 核心录入一致，查看路径有差异（患者自服务 vs 管理端视角）。

### 4.4 咨询流程

| 步骤 | Web | 小程序 | 一致性 |
|------|-----|--------|--------|
| 创建会话 | ✅ | ✅ | ✅ |
| 发送消息 | ✅ `POST /consultation-messages` | ✅ 相同 | ✅ |
| 接收消息 | ✅ SSE 实时 | ⚠️ 8s 轮询 | ⚠️ 实时性差异 |
| 标记已读 | ✅ | ✅ | ✅ |
| 关闭会话 | ✅ | ✅（仅医生端） | ✅ |

**结论**: 核心流程一致，消息接收机制因平台限制不同。

### 4.5 透析管理流程 ⚠️

| 步骤 | Web | 小程序 | 一致性 |
|------|-----|--------|--------|
| 透析记录列表 | ⚠️ 冻结 | ✅ | ❌ |
| 创建透析记录 | ⚠️ 冻结 | ✅（医生端） | ❌ |
| 审阅透析记录 | ⚠️ 冻结 | ✅（医生端） | ❌ |
| 透析处方管理 | ❌ 无页面 | ✅（医生端） | ❌ |
| 透析统计 | ✅ | ✅（医生端） | ✅ |

**结论**: Web 端透析模块冻结，小程序端完整可用。这是最大的不一致项。

### 4.6 积分商城流程

| 步骤 | Web（管理） | 小程序（患者） | 一致性 |
|------|------------|----------------|--------|
| 每日签到 | ❌ | ✅ | ⚠️ MP 独有 |
| 积分查询 | ✅ | ✅ | ✅ |
| 商品浏览 | ✅（管理） | ✅（浏览） | ✅ |
| 积分兑换 | ❌ | ✅ | ⚠️ MP 独有 |
| 订单核销 | ✅ | ❌ | ⚠️ Web 独有 |

**结论**: 管理端与患者端分工明确，无遗漏。

---

## 五、权限码一致性

### 5.1 权限覆盖

| 模块 | 后端权限码 | Web 路由守卫 | 小程序角色检查 |
|------|-----------|-------------|---------------|
| health.patient | .list / .manage | ✅ 路由守卫 | ✅ isMedicalStaff |
| health.health-data | .list / .manage | ✅ | ✅ |
| health.appointment | .list / .manage | ✅ | ✅ |
| health.follow-up | .list / .manage | ✅ | ✅ |
| health.consultation | .list / .manage | ✅ | ✅ |
| health.alerts | .list / .manage | ✅ | ✅ |
| health.dialysis | .list / .manage | ⚠️ 冻结路由 | ✅ 医生角色 |
| health.points | .list / .manage | ✅ | ✅ |
| ai.analysis | .list / .manage | ✅ | ✅（仅查看） |
| ai.suggestion | .list / .manage | ✅ | ⚠️ 仅 list |

**结论**: 权限码体系完整，Web 路由守卫与后端权限一一对应。

---

## 六、需要修复的不一致项

### CRITICAL — 无

### HIGH — 1 项

| # | 问题 | 影响 | 状态 |
|---|------|------|------|
| H1 | **小程序咨询消息为 8s 轮询，Web 为 SSE 实时** | 小程序消息延迟，体验不一致 | 🔧 待实现 |

### 已关闭（产品决策冻结）

| # | 问题 | 决策 |
|---|------|------|
| ~~H1~~ | Web 端透析管理路由冻结 | ✅ 保持冻结，当前版本不涉及医疗业务 |
| ~~H2~~ | Web 端无透析处方管理页面 | ✅ 冻结，与透析管理同步 |
| ~~M1~~ | Web 端无用药提醒功能 | ✅ 三端冻结 |
| ~~M2~~ | 小程序 AI 分析仅查看历史 | ✅ 设计意图，小程序仅展示结果 |

### LOW — 5 项（多为设计意图）

| # | 问题 | 说明 |
|---|------|------|
| L1 | 小程序趋势查询使用专属端点 | 患者自服务视角 vs 管理端视角，设计意图 |
| L2 | 小程序今日体征为独有功能 | 患者端需求，管理端不需要 |
| L3 | 小程序不支持 SSE 流式分析 | 平台限制，非遗漏 |
| L4 | 积分签到仅小程序 | 用户粘性功能，管理端不需要 |
| L5 | 法律文件仅小程序 | 小程序上架合规要求 |

---

## 七、统计数据

| 指标 | 值 |
|------|-----|
| 后端 API 端点 | ~300+ |
| Web 前端 API 调用 | ~270 |
| 小程序 API 调用 | ~91 |
| 三端完全一致的业务流程 | 8/11 (73%) |
| 需要修复的不一致项 | HIGH ×2 + MEDIUM ×3 + LOW ×5 |
| 设计意图导致的差异 | 13 项（非遗漏） |
| 总体一致性评分 | **82%** |

---

## 八、结论与建议

### 8.1 总体评价

HMS 三端在 API 接口层面保持了高度一致性（统一前缀、统一响应格式、统一分页、统一乐观锁），差异主要集中在：

1. **端定位不同导致的功能差异** — 这是设计意图，不需要修复
2. **Web 端透析模块冻结** — 这是最大的不一致项，需要产品决策
3. **个别功能仅在单端实现** — 用药提醒、透析处方等需评估是否补齐

### 8.2 优先行动建议

1. **产品决策**: 确认透析管理模块是否在 Web 端解冻。如果血透中心是首发场景，Web 管理端的透析能力不应缺失
2. **功能补齐**: Web 端补充透析处方管理页面（后端 API 已就绪）
3. **功能补齐**: Web 端患者详情增加用药提醒管理（后端 API 已就绪）
4. **体验优化**: 评估小程序咨询消息是否需要更实时的方案
5. **能力对齐**: 评估小程序是否需要 AI 分析触发入口