**血糖数据功能设计文档**

**概述**: 本文档描述系统中血糖（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`。

**示例**
- 添加请求示例:

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

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

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

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

```json
{
  "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`）