ChronicDisease_SpringBoot/docs/Dev/modules/血糖数据功能设计文档.md

血糖数据功能设计文档

概述: 本文档描述系统中血糖（Blood Glucose）数据的接入、查询、删除能力及相关权限、审计和存储设计。对应代码位置：src/main/java/.../controller/BloodGlucoseDataController.java、service/BloodGlucoseDataService、数据库表 t_blood_glucose_data。

目标: 为移动端（患者）和绑定方（医生/家属）提供血糖测量记录的上报与查询能力，同时确保基于绑定关系的访问控制与审计记录。

接口清单:

• 添加血糖数据

  • 路径: POST /blood-glucose/add
  • 描述: 患者上报一条血糖测量记录。
  • 请求体: AddBloodGlucoseDataRequest (application/json)
  • type: String，测量类型（例如：fasting、postprandial 等），必填
  • value: BigDecimal，血糖值（mmol/L），必填，范围 [1.0, 30.0]
  • measureTime: LocalDateTime，测量时间，必填
  • 响应: 标准 R 成功/失败返回。成功返回 200 OK 与 message ok。
  • 校验: 请求字段使用注解验证（@NotNull, @DecimalMin, @DecimalMax）。

• 分页查询血糖数据（本人）

  • 路径: POST /blood-glucose/list
  • 描述: 当前用户根据时间范围和分页参数查询自己的血糖记录。
  • 请求体: BaseQueryRequest (application/json)
  • pageNum: 页码，默认 1
  • pageSize: 每页大小，默认 10
  • startTime, endTime: 可选时间范围
  • 响应: BloodGlucoseDataPageResponse，包含分页 metadata 与 BloodGlucoseDataResponse 列表。

• 绑定方分页查询患者血糖数据

  • 路径: POST /blood-glucose/list-by-bound-user
  • 描述: 医生或家属等绑定方查询目标患者的血糖记录，前提为存在绑定关系。
  • 参数: patientUserId (Long, 必填)，bindingType (String, 可选)，请求体 BaseQueryRequest
  • 权限检查流程:
  • 获取当前发起查询的用户 boundUserId（从 token / SecurityUtils）
  • 调用 UserBindingService.checkUserBinding 验证 boundUserId 与 patientUserId 的绑定关系
  • 若不存在绑定关系，返回错误 DATA_ACCESS_DENIED（无权访问）
  • 若存在且 bindingType 为空，则从检查结果中使用绑定类型
  • 审计: 在 Controller 中写入访问日志（logger.info），记录访问方、患者、时间范围与数据类型（type=blood_glucose）。
  • 响应: 同 list，返回 BloodGlucoseDataPageResponse。

• 删除血糖数据

  • 路径: POST /blood-glucose/delete
  • 描述: 根据记录 ID 删除血糖数据（通常仅允许记录创建者或有权限的管理方删除，具体权限在 service 层实现）。
  • 请求体: DeleteBloodGlucoseDataRequest，包含 id (String，必填)
  • 响应: 标准 R 成功/失败返回。

数据模型 (VO / PO)

• 请求/响应 VO:

  • AddBloodGlucoseDataRequest:
  • type : String
  • value : BigDecimal
  • measureTime : LocalDateTime
  • BloodGlucoseDataResponse:
  • id : String
  • measureTime : LocalDateTime
  • type : String
  • value : BigDecimal
  • createTime : LocalDateTime

• 持久化表: t_blood_glucose_data（参见 docs/DB/t_blood_glucose_data.txt）

  • 建议字段: id, user_id, type, value, measure_time, create_time, update_time, deleted_flag 等

校验规则

• type 非空。
• value 在 1.0 至 30.0 mmol/L 之间。
• measureTime 非空且不晚于当前时间（可在 service 层严格校验）。

权限与访问控制

• 上报数据: 需要登录（Token 校验），默认记录写入当前用户（user_id 从 token 中获取）。
• 个人查询: 仅返回当前登录用户的数据。
• 绑定方查询: 必须存在绑定关系（通过 UserBindingService.checkUserBinding），否则返回 DATA_ACCESS_DENIED。
• 删除操作: service 层应校验调用者是否为记录所有者或拥有管理权限（未在 Controller 中显式强制，需在 service 实现）。

审计与日志

• 在 list-by-bound-user 接口中记录访问日志：记录访问方 ID、患者 ID、数据类型（blood_glucose）、查询时间范围。
• 在重要数据变更点（新增、删除）建议写入操作日志，用于追溯。

错误码

• 常见错误码参考 ErrorCode 枚举：
  • PARAMETER_ERROR (1001)：请求参数缺失或校验失败
  • SYSTEM_ERROR (1000)：服务器内部错误
  • UNAUTHORIZED (1002)：未授权（token 无效）
  • DATA_ACCESS_DENIED (4001)：绑定方访问时无权限
  • DATA_NOT_FOUND (4000)：删除/查询的记录不存在

服务与 Mapper 关系

• Controller -> BloodGlucoseDataService（负责业务校验、权限判断、持久化调用、分页查询实现）
• Service -> Mapper (BloodGlucoseDataMapper) 直接与 t_blood_glucose_data 表交互

兼容性与注意事项

• list-by-bound-user 的参数 bindingType 可由前端传入，也可在后端根据绑定关系重用检查结果中的绑定类型，保证行为向后兼容。
• 时间字段使用 LocalDateTime，前端需按照约定时区/格式发送（建议 ISO-8601）。
• 分页返回使用 MyBatis-Plus Page，Controller 将其转换为页面友好格式 BloodGlucoseDataPageResponse。

示例

• 添加请求示例:

  {
  "type": "fasting",
  "value": 5.6,
  "measureTime": "2025-11-20T07:30:00"
  }
  

• 查询（分页）请求示例:

  {
  "pageNum": 1,
  "pageSize": 20,
  "startTime": "2025-11-01T00:00:00",
  "endTime": "2025-11-21T23:59:59"
  }
  

• 响应示例 (分页 records 片段):

  {
  "records": [
  {
    "id": "abc123",
    "measureTime": "2025-11-20T07:30:00",
    "type": "fasting",
    "value": 5.6,
    "createTime": "2025-11-20T07:35:00"
  }
  ],
  "total": 1,
  "size": 20,
  "current": 1
  }
  

后续建议

• 在 Service 层补充：
  • 更完整的权限检查（删除仅允许记录所有者或管理员）
  • measureTime 的合理性检查（不应晚于服务器当前时间、时间窗口限制等）
  • 异常分类与更细粒度错误码（如 DATA_SAVE_FAILED）