ChronicDisease_SpringBoot/docs/Dev/modules/用户绑定功能设计文档.md

用户绑定功能设计文档

概述: 描述患者与医生/家属之间绑定关系的管理与查询能力。对应实现：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），以方便前端友好提示。

示例

• 创建绑定请求示例:

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

• 检查绑定请求示例:

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

• 检查绑定响应示例:

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

扩展建议

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