ChronicDisease_SpringBoot/docs/DevDesign/HealthData/ImplementationDifferences.md

健康数据模块 — 实现与设计功能差异清单

说明：本文件记录代码实现相对于设计稿（见同目录下的设计文档）在功能层面的差异。每项包括：差异描述、实际影响、建议修正、优先级，以及预留的“解决状态”字段（供后续对话中逐项标记）。

---

使用说明

• 状态字段：[status]，可取值 not-started / in-progress / resolved。
• 负责人/备注：在项下方 owner 与 notes 字段中填写负责人的姓名与处理备注。
• 当项被解决时，请把 status 改为 resolved 并在 notes 中写明修改文件或提交说明（例如：修改了 X 文件，commit 123abc）。

---

概览

总体结论：项目已实现四个子模块（体格/血压/血糖/心率）的核心 CRUD、PO/VO/Mapper/Service/Controller、分页与字段校验。但在权限/角色、接口命名与方法、血糖枚举与录入模式、异常/响应语义、数据库迁移等方面存在功能性差异或未完全实现的设计要求。

下列条目按建议优先级排序（高 -> 低）。

---

Item A — 权限与多角色访问（高）

• id: A
• description: 设计稿要求患者只能访问自己的数据；医生可访问指定患者的数据；管理员可访问所有数据。当前实现仅基于 currentUserId 过滤，未实现医生/管理员的授权与跨患者访问策略。
• impact: 医生/管理员无法按设计查看或代查患者数据，权限模型不完整，存在功能缺失。
• recommendation:
  1. 在用户模型或 TokenService 中提供用户角色信息（patient/doctor/admin）。
  2. 在需要支持医生访问的接口中加入 patientId 参数，并在 Service 层校验当前用户角色是否有访问该 patientId 的权限（如医生会诊名单、授权表等）。
  3. 提供统一的权限工具（例如 SecurityUtils.getCurrentUser() 返回包含 id 与 role 的对象）。
• priority: high
• status: not-started
• owner:
• notes:

---

Item B — API 路径与请求方法不一致（中）

• id: B
• description: 设计文档定义了接口路径如 /physical-data/*, /blood-glucose-data/*, /heart-rate-data/* 等；实现中为 /physical, /blood-glucose, /heart-rate 等短路径。BMI 在文档为 GET /physical-data/bmi，实现为 POST /physical/bmi。
• impact: 前端与文档将无法直接对接，GET/POST 差异会影响缓存/语义。
• recommendation: 选取一种统一策略：
  • 方案 1（推荐）：让代码遵循设计文档的路径与方法（修改 Controller 的 RequestMapping 与方法）；
  • 方案 2：如果更倾向于保持当前实现，则把 API 文档更新为与代码一致。
• priority: medium
• status: not-started
• owner:
• notes:

---

Item C — 血糖枚举与录入模型差异（中）

• id: C
• description: 设计稿里 BloodGlucoseType 包含 integer code、unit、normalRange、显示顺序等元数据，并且设计示例支持一次提交多时间点（多个字段）；实现中枚举使用 String code，且 API 以每条记录一个 type+value 的方式接收数据。
• impact: 前端无法直接从后端获得参考范围/单位/显示顺序信息；若业务需要一次性提交多时间点数据（按天表单），当前接口不支持。
• recommendation:
  • 如果按当前单条记录模型继续：扩展枚举 BloodGlucoseType 增加 unit、normalRange、getOrderedTypes() 等方法，并提供一个枚举元数据的 API 端点供前端获取显示信息；
  • 如果需要支持批量提交：新增 batch API（例如 POST /blood-glucose-data/batch）和相应 VO，在服务端做批量插入与校验。
• priority: medium
• status: not-started
• owner:
• notes:

---

Item D — 返回/错误语义与异常处理不统一（中）

• id: D
• description: 设计文档期望返回格式使用语义化字符串 code（例如 SUCCESS, PARAM_ERROR），而代码中 R 主要使用数值（如 200、500）。Controller 中部分地方使用局部 try/catch 导致全局异常处理器不一致地被绕过。同时 CustomException 在代码中被修改为 RuntimeException。
• impact: 前端/集成方可能无法根据文档预期解析 code。局部 try/catch 会导致错误响应格式不统一。
• recommendation:
  • 统一响应格式（两选一）：
  • 让 R 返回设计稿中语义化 code（修改 R & CustomExceptionHandler）；或
  • 在文档中确认并改为 numeric-style code，然后统一文档与实现；
  • 移除不必要的 Controller 层 try/catch（或仅保留用于捕获同步业务错误），让异常通过全局 CustomExceptionHandler 处理以保证统一格式。
  • 审核并确认 CustomException 是否应为 checked 或 unchecked（团队约定）。
• priority: medium
• status: not-started
• owner:
• notes:

---

Item E — AuthInterceptor 与 SecurityUtils 的对齐（高/已实现）

• id: E
• description: 设计中拦截器会把用户 ID 放入 request attribute（currentUserId）。我已实现 SecurityUtils.getCurrentUserId() 并替换了分散实现，AuthInterceptor 代码确认了写入 currentUserId。
• impact: 基础用户 ID 获取机制已统一，但仍需确认拦截器在所有部署环境中都启用并写入该 attribute；若拦截器改动需同步 SecurityUtils。
• recommendation:
  • 将属性 key currentUserId 作为常量（例如 SecurityConstants.CURRENT_USER_ID）并在拦截器与工具类中引用；
  • 为 SecurityUtils 增加回退策略（如从 Authorization header 解 token）以增强健壮性。
• priority: high
• status: resolved
• owner: (已实现)
• notes: SecurityUtils 新增并已替换四处 service impl 与 WeChatController 的读取点；请确认是否需要常量化 key 或增加回退策略。

---

Item F — 数据库建表脚本与迁移（中）

• id: F
• description: 设计稿提供了 CREATE TABLE 语句，但仓库内未发现 Flyway/Liquibase 等自动迁移脚本。
• impact: 部署时需要手动建表或外部脚本，降低自动化与可重复部署能力。
• recommendation: 添加 Flyway 或 Liquibase 的迁移脚本（db/migration）并将建表 SQL 列入迁移历史；在 CI/CD 中执行迁移以保证环境一致。
• priority: medium
• status: not-started
• owner:
• notes:

---

Item G — 枚举元数据/显示顺序缺失（低）

• id: G
• description: 设计里建议提供 getOrderedTypes()、单位、参考范围等；实现的枚举未包含这些额外元数据。
• impact: 前端无法自动获得显示顺序或参考范围，需要在多个地方硬编码，降低一致性。
• recommendation: 扩展 BloodGlucoseType 枚举以包含 unit、normalRange、getOrderedTypes()，并暴露一个元数据 API（例如 GET /meta/blood-glucose-types）。
• priority: low
• status: not-started
• owner:
• notes:

---

Item H — 关键业务校验缺失（低-中）

• id: H
• description: 设计提到若干业务校验（如血压高低压关系、重复记录策略、异常预警等），但实现仅包含基础字段范围校验，缺少业务层面规则。
• impact: 可能导致错误数据被录入（例如收缩压 < 舒张压未校验），或未对重复/异常进行预警/处理。
• recommendation: 在 Service 层补充以下校验：
  • 血压：收缩压 >= 舒张压；
  • 重复提交：同一用户、同一类型、同一测量时间窗内的去重或提示策略；
  • 异常值预警：当值超出临床阈值时触发告警或返回明确业务码。
• priority: low-to-medium
• status: not-started
• owner:
• notes:

---

Item I — 文档与代码不同步（低）

• id: I
• description: 多处代码与设计文档在路径、方法、响应格式上存在不一致（汇总见上）。
• impact: 影响前后端协作和 API 测试；造成审查/维护成本。
• recommendation: 决定以代码为准还是以文档为准并执行一次一致性同步（我可按选择自动生成更新的文档或批量修改 Controller 路径）。
• priority: low
• status: not-started
• owner:
• notes:

---

后续流程建议

1. 先解决高优先级项（A、E），确保权限/认证/用户上下文准确；
2. 再统一异常/响应语义（C）与 API 路径（B）；
3. 然后补充枚举元数据/批量录入（G、C）与业务校验（H）；
4. 最后完善迁移脚本与文档（F、I）。

如果你确认这个清单，我会把它放入版本库（已保存到本文件），并可以在你选定的条目上逐一开始实现 —— 请回复你想先解决的项（例如 先做 A 或 先做 C 和 B）。

---

文件生成：docs/DevDesign/HealthData/ImplementationDifferences.md