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

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

---

## 使用说明
- 状态字段：`[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`