**用户绑定功能设计文档**

**概述**: 描述患者与医生/家属之间绑定关系的管理与查询能力。对应实现：`src/main/java/.../controller/UserBindingController.java` 与 `service/UserBindingService`，持久化表建议为 `t_user_binding`。

**目标**: 提供创建/删除绑定关系、按患者或被绑定用户分页查询绑定列表、以及检测两者是否存在绑定关系的能力；并明确权限、审计与字段语义，支持业务侧基于绑定关系的授权决策（如健康数据访问）。

**接口清单**:
- **创建用户绑定关系**
  - 路径: `POST /user-binding/create`
  - 描述: 为患者创建与医生或家属的绑定关系。
  - 请求体: `CreateUserBindingRequest` (application/json)
    - `patientUserId` (Long) - 患者用户ID，必填
    - `boundUserId` (Long) - 被绑定用户ID（医生或家属），必填
    - `bindingType` (String) - 绑定类型（`DOCTOR` 或 `FAMILY`），必填
  - 响应: 标准 `R` 成功/失败。创建时应避免重复绑定记录（可在 service 层做幂等处理）。

- **删除用户绑定关系**
  - 路径: `POST /user-binding/delete`
  - 描述: 解除患者与被绑定用户之间的绑定关系。
  - 请求体: `DeleteUserBindingRequest` (application/json)
    - `patientUserId` (Long) - 患者用户ID，必填
    - `boundUserId` (Long) - 被绑定用户ID，必填
  - 响应: 标准 `R` 成功/失败。删除操作应校验调用者权限（患者本人或平台管理员/被绑定方在某些场景下也可）。

- **分页查询患者的绑定关系列表**
  - 路径: `POST /user-binding/list-by-patient`
  - 描述: 根据患者 ID 和可选绑定类型查询该患者的绑定关系列表（医生/家属）。
  - 参数: `patientUserId` (Long, 必填), `bindingType` (String, 可选), 请求体 `BaseQueryRequest`
  - 响应: `UserBindingPageResponse`（内部包含 `UserBindingResponse` 列表，含被绑定用户的昵称/手机号等便捷信息）。

- **分页查询用户被绑定的关系列表**
  - 路径: `POST /user-binding/list-by-bound-user`
  - 描述: 查询某个被绑定用户（如医生）被哪些患者绑定。
  - 参数: `boundUserId` (Long, 必填), `bindingType` (String, 可选), 请求体 `BaseQueryRequest`
  - 响应: 同 `list-by-patient`。

- **检查用户绑定关系**
  - 路径: `POST /user-binding/check`
  - 描述: 检查两用户之间是否存在绑定关系，返回 `exists` 与 `bindingType`。
  - 请求体: `CheckUserBindingRequest` (application/json)
    - `patientUserId` (Long), `boundUserId` (Long)
  - 响应: `CheckUserBindingResponse`:
    - `exists` (Boolean) - 是否存在绑定关系
    - `bindingType` (String) - 若存在，返回绑定类型（`DOCTOR`/`FAMILY`）

**数据模型 (VO / PO)**
- `CreateUserBindingRequest`:
  - `patientUserId`: Long
  - `boundUserId`: Long
  - `bindingType`: String (`DOCTOR` | `FAMILY`)
- `DeleteUserBindingRequest`:
  - `patientUserId`: Long
  - `boundUserId`: Long
- `UserBindingResponse`:
  - `id`: String
  - `patientUserId`: String
  - `boundUserId`: String
  - `bindingType`: String
  - `status`: Integer (1 有效, 0 无效)
  - `createTime`: LocalDateTime
  - `boundUserNickname`, `boundUserPhone` 等为附加展示字段
- `CheckUserBindingRequest` / `CheckUserBindingResponse`：见接口

**持久化建议（表 t_user_binding）**
- 建议字段: `id`, `patient_user_id`, `bound_user_id`, `binding_type`, `status`, `created_by`, `created_at`, `updated_at`, `deleted_flag`。
- 索引建议: `(patient_user_id)`, `(bound_user_id)`, 复合索引 `(patient_user_id, bound_user_id)` 以加速检查/删除操作。

**业务规则与校验**
- 创建绑定时：
  - 校验 `patientUserId` 与 `boundUserId` 不为空，且二者不同。
  - 校验 `patientUserId` 对应的用户必须存在，且其角色必须为 **患者(PATIENT)**。
  - 校验 `boundUserId` 对应的用户必须存在；若 `bindingType=DOCTOR` 则其角色必须为 **医生(DOCTOR)**，若 `bindingType=FAMILY` 则其角色必须为 **患者家属(PATIENT_FAMILY)**。
  - 不允许重复生效的绑定记录；如已存在有效绑定则返回幂等成功或说明已存在。
  - 可能需要目标用户同意（可扩展为双向确认流程），当前实现为直接创建（具体流程参照 `UserBindingService`）。
- 删除绑定时：
  - 仅允许有权限的主体发起（患者本人、平台管理员或被绑定方在特殊策略下）。
  - 推荐使用软删除（设置 `status=0` 或 `deleted_flag`）以保留历史审计。

**权限与访问控制**
- 创建/删除绑定：
  - 需要登录；操作权限详见业务规则。创建可由患者或后台操作触发；删除需校验发起者身份。
- 查询绑定列表：
  - 查询患者的绑定关系通常允许患者本人或有管理权限的用户访问；查询被绑定用户的列表通常允许被绑定用户本人或管理员访问。
- 检查绑定关系：
  - 常用于其他数据访问接口（如 `list-by-bound-user` 的数据授权判断），通常不对外开放敏感信息，仅返回是否存在与绑定类型。

**审计与日志**
- 对绑定关系的创建、删除、状态变更事件写入审计日志，记录 `operatorId`、`patientUserId`、`boundUserId`、`bindingType`、`timestamp`、`ip` 等。
- 对于通过绑定关系访问患者数据的操作（例如查看体征数据），在访问日志中记录 `accessorId`、`patientUserId`、`bindingType` 与被访问的数据类型。

**错误码**
- 常见错误码参考 `ErrorCode`：`PARAMETER_ERROR`、`SYSTEM_ERROR`、`DATA_NOT_FOUND`、`DATA_ACCESS_DENIED` 等。建议为绑定流程补充特定错误码（如 `BINDING_ALREADY_EXISTS`, `BINDING_NOT_FOUND`），以方便前端友好提示。

**示例**
- 创建绑定请求示例:

```json
{
  "patientUserId": 1001,
  "boundUserId": 2001,
  "bindingType": "DOCTOR"
}
```

- 检查绑定请求示例:

```json
{
  "patientUserId": 1001,
  "boundUserId": 2001
}
```

- 检查绑定响应示例:

```json
{
  "exists": true,
  "bindingType": "DOCTOR"
}
```

**扩展建议**
- 支持绑定审批流程：发起方请求绑定 -> 目标方同意/拒绝 -> 完成绑定，适用于敏感场景。
- 提供绑定通知：在绑定建立或解除时通知患者或绑定方（短信/模板消息/站内信）。
- 支持绑定时限或权限粒度：例如只允许查看体征数据但不允许修改提醒等。