df1d85bfde
- T40 UI 审计计划和结果文档（docs/qa/） - wiki 更新：miniprogram 设计系统合规审计记录 + index 关键数字更新 - 审计 V2 完整报告（docs/audits/v2/） - 讨论记录文档（docs/discussions/） - 设计规格和实施计划（docs/superpowers/） - 角色测试计划和结果（docs/qa/role-test-*） - Docker 生产部署配置
270 lines
12 KiB
Markdown
270 lines
12 KiB
Markdown
# 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 分析触发入口
|