tyt-api-nest/docs/patients.md

患者模块说明（src/patients）

1. 目标

• B 端：按组织与角色范围查询患者，并维护患者基础档案。
• B 端：支持患者首术录入、二次手术追加、旧设备弃用标记。
• 数据关系升级为 Patient -> PatientSurgery -> Device -> TaskItem -> Task。
• C 端：按 phone + idCard 做跨院生命周期聚合，返回手术事件与调压事件。

2. 患者基础档案

患者表新增以下字段：

• inpatientNo：住院号
• projectName：项目名称
• phone：联系电话
• idCard：身份证号原文
• doctorId：患者归属人员（医生/主任/组长）

说明：

• name 仍然保留为患者姓名必填字段。
• doctorId + hospitalId 仍然是患者的组织归属来源，不直接绑定小组/科室。
• 手术表单中的 原发病 / 脑积水类型 / 分流方式 / 近端穿刺区域 / 阀门植入部位 / 远端分流方向 改为读取系统字典，不再前端硬编码。

3. 手术档案

新增 PatientSurgery 表，每次手术保存：

• surgeryDate：手术日期
• surgeryName：手术名称
• surgeonName：主刀医生
• preOpPressure：术前测压，可为空
• primaryDisease：原发病
• hydrocephalusTypes：脑积水类型，多选
• previousShuntSurgeryDate：上次分流手术时间，可为空
• preOpMaterials：术前 CT 影像/资料，保存为附件元数据数组
• notes：手术备注，可为空

返回时会自动补充：

• shuntSurgeryCount：当前这台手术是该患者第几次分流手术
• activeDeviceCount：本次手术仍在用设备数
• abandonedDeviceCount：本次手术已弃用设备数

4. 植入设备

设备表仍沿用 Device，但语义改为“患者手术下植入的设备实例”。

新增/使用字段：

• implantCatalogId：植入物型号字典 ID
• implantModel / implantManufacturer / implantName：型号快照
• isPressureAdjustable：是否可调压
• isAbandoned：是否已弃用
• shuntMode：分流方式
• proximalPunctureAreas：近端穿刺区域，最多 2 个
• valvePlacementSites：阀门植入部位，最多 2 个
• distalShuntDirection：远端分流方向
• initialPressure：初始压力，可为空
• implantNotes：植入物备注，可为空
• labelImageUrl：植入物标签图片地址，可为空

说明：

• 患者手术里选择的是“全局植入物目录”，不是按医院单独维护的设备库。
• 同一个植入物目录可被多个患者手术重复绑定，患者侧保存的是目录快照。
• 旧设备弃用后，TaskItem 历史不会删除。
• 任务发布只允许选择 ACTIVE + isPressureAdjustable=true + isAbandoned=false 的设备。
• 同一患者一次手术可录入多个设备，因此支持“两个可调压仪器同时佩戴”。
• 如果植入物目录配置了挡位，initialPressure 必须取挡位中的值。
• 手术创建时不允许手工录入 currentPressure，设备当前压力默认继承 initialPressure，后续仅能由调压任务完成后更新。

5. B 端可见性

• DOCTOR：仅可查自己名下患者
• LEADER：可查本组医生名下患者
• DIRECTOR：可查本科室医生名下患者
• HOSPITAL_ADMIN：可查本院全部患者
• SYSTEM_ADMIN：需显式传入目标 hospitalId

6. B 端接口

• GET /b/patients：按角色查询可见患者列表
• GET /b/patients/doctors：查询当前角色可见的归属人员候选
• POST /b/patients：创建患者，可选带 initialSurgery
• POST /b/patients/:id/surgeries：为患者新增手术
• GET /b/patients/:id：查询患者详情
• PATCH /b/patients/:id：更新患者基础信息
• DELETE /b/patients/:id：删除患者

约束：

• PATCH /b/patients/:id 不直接修改手术，手术必须走新增手术接口。
• 新增二次手术时可传 abandonedDeviceIds，后端会将这些旧设备标记为 INACTIVE + isAbandoned=true。

7. C 端生命周期聚合

接口：GET /c/patients/lifecycle?phone=...&idCard=...

查询策略：

1. 不做医院隔离（跨租户）
2. 先将 idCard 做轻量标准化，再做双字段精确匹配
3. 聚合 Patient -> PatientSurgery -> Device 的手术事件
4. 聚合 Patient -> Device -> TaskItem -> Task 的调压事件
5. 全部事件按 occurredAt DESC 返回

事件类型：

• SURGERY
• TASK_PRESSURE_ADJUSTMENT

8. 响应结构

全部接口统一返回：

• 成功：{ code: 0, msg: "成功", data: ... }
• 失败：{ code: x, msg: "中文错误", data: null }