46 KiB

Raw Blame History

就诊记录接口文档

通用说明

响应格式

所有接口返回 JSON，严格遵循以下格式：

{
  "code": 0,
  "message": "success",
  "data": {}
}

code：0 表示成功，非 0 表示失败
message：成功时为 "success"，失败时为错误描述
data：业务数据，失败时为 null

数据命名规则

data 中所有字段使用小驼峰命名法（如 visitDate、igG4Value）。

登录校验

所有接口需通过请求头 loginState 或请求参数 loginState 传递登录态，未登录返回 code=403。

错误码

code	说明
0	成功
1	参数缺失
2	记录不存在
3	操作失败
403	需要登录

一、患者端接口

模块路由前缀：igg4/medical-visit

1.1 保存草稿

路由：?r=igg4/medical-visit/save-draft
请求方式：POST
说明：创建或更新草稿记录。传入 id 时更新已有草稿，不传时新建草稿。图片列表支持新增、更新、逻辑删除的 diff 处理。使用数据库事务。

请求参数

参数	类型	必填	说明
id	int	否	已有草稿 ID，更新时必传
visitDate	string	是	本次就诊时间，格式 YYYY-MM-DD
nextVisitDate	string	否	下次就诊时间，格式 YYYY-MM-DD
oralHormoneDosage	float	否	口服激素每日用量（片）
manualIgG4Value	float	否	患者手动录入的IgG4数值（冗余字段，单位mg/dL）
medicationsUsed	array	否	本次就诊已使用的药物（多选），值为常量ID数组，如 [1,2,3]，见附录G
immunosuppressantName	array	否	正在使用的免疫抑制剂名称（多选），值为常量ID数组，如 [1,5]，见附录G
medicationsUsedOtherText	string	否	本次就诊已使用药物选择"其他"(99)时的补充文本
immunosuppressantNameOtherText	string	否	正在使用的免疫抑制剂名称选择"其他"(99)时的补充文本
images	array	否	图片列表

images 每项参数

参数	类型	必填	说明
imageUrl	string	是	图片 URL
imageType	string	是	图片类型标识，见枚举表

imageType 枚举

值	说明
outpatientRecord	门诊病历及处方
labReport	检验报告
imagingExam	影像学检查
pathology	病理诊断及活检
immuneFunction	外周血免疫功能评估

请求示例

{
  "id": 0,
  "visitDate": "2026-06-29",
  "nextVisitDate": "2026-09-29",
  "oralHormoneDosage": 4,
  "manualIgG4Value": 135.0,
  "medicationsUsed": [2, 3],
  "immunosuppressantName": [1, 7],
  "medicationsUsedOtherText": null,
  "immunosuppressantNameOtherText": null,
  "images": [
    {
      "imageUrl": "https://oss.example.com/img001.jpg",
      "imageType": "labReport"
    },
    {
      "imageUrl": "https://oss.example.com/img002.jpg",
      "imageType": "outpatientRecord"
    }
  ]
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "recordStatus": 1
  }
}

业务逻辑说明

若传入 id，校验记录存在、属于当前患者、为草稿状态（recordStatus=1），否则报错
若未传 id，新建主记录，设置 recordStatus=1（草稿）、status=1（有效）
保存 CreateWorkerId/CreateTime/UpdateWorkerId/UpdateTime
图片 diff 处理：通过 RecordId + ImageUrl 匹配已有图片记录
- 已存在 → 更新 ImageType，重置 OcrStatus 为待解析（0），清空 OcrText/OcrParsedData/指标字段
- 不存在 → 插入新图片记录（OcrStatus 默认为 0）
- 已有但本次未传入 → 逻辑删除（status=100）
最终将所有检验报告图片的指标值和门诊病历图片的病历文本聚合到主表（后出现的值覆盖先出现的值）
manualIgG4Value 参数写入主表 ManualIgG4Value 字段，作为冗余存储，不影响 OCR 解析产生的主数据 IgG4Value

1.1.0 保存图片记录

路由：?r=igg4/medical-visit/save-image
请求方式：POST
说明：仅保存单张图片记录到就诊记录图片表，不更新主记录字段，不触发指标聚合。前端需先创建草稿获取 RecordId 后再调用此接口。使用数据库事务。

请求参数

参数	类型	必填	说明
recordId	int	是	已有草稿记录 ID
imageUrl	string	是	图片 URL
imageType	string	是	图片类型标识，见枚举表

imageType 枚举

同 1.1 images.imageType

请求示例

{
  "recordId": 1,
  "imageUrl": "https://oss.example.com/img001.jpg",
  "imageType": "labReport"
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "imageId": 102,
    "recordId": 1,
    "imageUrl": "https://oss.example.com/img001.jpg",
    "imageType": "labReport",
    "ocrStatus": 0
  }
}

业务逻辑说明

校验 recordId 对应的记录存在且属于当前患者，否则报错"就诊记录不存在"或"就诊记录不属于当前患者"
校验记录状态为草稿（recordStatus=1），否则报错"仅草稿状态的记录可添加图片"
将 imageType 字符串转为数据库整型值，无效则报错"无效的图片类型"
根据 RecordId + ImageUrl 判断图片是否已存在：
- 已存在：更新 ImageType，重置 OcrStatus 为待解析（0），清空 OcrText、OcrParsedData 及对应指标/文本字段
- 不存在：新建图片记录（含 CreateWorkerId/CreateTime），OcrStatus 默认为待解析（0）
不触发主表指标聚合（与 saveDraft 不同），聚合在调用 saveDraft 或 submit 时发生
小程序端仅存储原始图片，OCR 解析由后台管理员涂抹图片后触发，返回 ocrStatus 表示当前解析状态

1.1.1 删除单个图片

路由：?r=igg4/medical-visit/delete-image
请求方式：POST
说明：逻辑删除指定图片记录，设置 Status=100，记录操作人和操作时间。使用数据库事务。

请求参数

参数	类型	必填	说明
imageId	int	是	图片记录 ID

请求示例

{
  "imageId": 102
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": true
}

业务逻辑说明

校验 imageId 必传，否则报错"图片记录ID不能为空"
校验管理员已登录，获取当前操作人 workerId
校验图片记录存在且有效（Status=1），否则报错"图片记录不存在"
逻辑删除：设置 Status=100（已删除），记录 UpdateWorkerId/UpdateTime
返回 true

1.2 提交就诊记录

路由：?r=igg4/medical-visit/submit
请求方式：POST
说明：将草稿状态的记录提交，提交后不可再编辑。使用数据库事务。

请求参数

参数	类型	必填	说明
id	int	是	草稿记录 ID

请求示例

{
  "id": 1
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": true
}

业务逻辑说明

校验记录存在、属于当前患者
校验记录状态为草稿（recordStatus=1），否则报错"仅草稿状态的记录可提交"
更新 recordStatus=2（已提交），记录 UpdateWorkerId/UpdateTime

1.3 获取就诊记录详情

路由：?r=igg4/medical-visit/detail
请求方式：GET
说明：获取单条就诊记录详情，包含主记录所有指标数据和按类型分组的图片列表。

请求参数

参数	类型	必填	说明
id	int	是	就诊记录 ID

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "visitDate": "2026-06-29",
    "nextVisitDate": "2026-09-29",
    "recordStatus": 2,
    "igG4Value": 135.0,
    "manualIgG4Value": 135.0,
    "displayIgG4Value": 135.0,
    "totalIgGValue": 1200.0,
    "igEValue": 50.0,
    "eosCount": 0.3,
    "esrValue": 20.0,
    "crpValue": 5.0,
    "oralHormoneDosage": 4.0,
    "medicationsUsed": [2, 3],
    "immunosuppressantName": [1, 7],
    "medicationsUsedOtherText": null,
    "immunosuppressantNameOtherText": null,
    "medicalRecordTime": "2026-06-29 09:30:00",
    "prescriptionTime": "2026-06-29 10:15:00",
    "reportTime": "2026-06-28 14:20:00",
    "chiefComplaint": "反复腹痛3月",
    "medicalHistory": "现病史：患者3月前无明显诱因出现腹痛...",
    "diagnosis": "IgG4相关性疾病",
    "treatmentPlan": "激素治疗，定期复查",
    "prescription": "甲泼尼龙片 4mg 每日1次 口服 30片",
    "clinicalDiagnosis": "IgG4相关性疾病",
    "images": {
      "outpatientRecord": [
        {
          "id": 101,
          "imageUrl": "https://...",
          "maskedImageUrl": "https://...masked.jpg",
          "ocrStatus": 2,
          "ocrParsedData": "门诊病历文本...",
          "medicalRecordTime": "2026-06-29 09:30:00",
          "prescriptionTime": "2026-06-29 10:15:00",
          "reportTime": null
        }
      ],
      "labReport": [
        {
          "id": 102,
          "imageUrl": "https://...",
          "maskedImageUrl": "https://...masked.jpg",
          "ocrStatus": 2,
          "ocrParsedData": {
            "reportTime": "2026-06-28",
            "indicators": {
              "igG4": {"value": 135.0, "unit": "mg/dL"},
              "totalIgG": {"value": 1200.0, "unit": "mg/dL"},
              "igE": {"value": 50.0, "unit": "IU/mL"},
              "eos": {"value": 0.3, "unit": "10^9/L"},
              "esr": {"value": 20.0, "unit": "mm/h"},
              "crp": {"value": 5.0, "unit": "mg/L"}
            }
          },
          "medicalRecordTime": null,
          "prescriptionTime": null,
          "reportTime": "2026-06-28 14:20:00"
        }
      ],
      "imagingExam": [
        {
          "id": 103,
          "imageUrl": "https://...",
          "maskedImageUrl": null,
          "ocrStatus": 0,
          "ocrParsedData": null
        }
      ],
      "pathology": [],
      "immuneFunction": []
    }
  }
}

images 字段说明

固定返回 5 种图片类型的分组，无数据时为空数组
每张图片包含 id、imageUrl、maskedImageUrl、ocrStatus、ocrParsedData、medicalRecordTime、prescriptionTime、reportTime
maskedImageUrl：涂抹后图片 URL，后台管理员未涂抹时为 null
ocrStatus：OCR 解析状态，0-待解析，1-解析中，2-解析完成，3-解析失败
ocrParsedData：检验报告类型为包含 reportTime 和 indicators 的结构化 JSON 对象，门诊病历类型为包含 medicalRecordTime 和 prescriptionTime 的结构化 JSON 对象，其他类型为拼接文本字符串，无 OCR 数据时为 null
medicalRecordTime：病历时间（图片类型=门诊病历且识别为门诊病历时有值），格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss
prescriptionTime：处方时间（图片类型=门诊病历且识别为处方时有值），格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss
reportTime：检查报告时间（图片类型=检验报告时有值），格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss

主记录字段说明

displayIgG4Value：展示用 IgG4 数值，优先取 manualIgG4Value，为空则取 igG4Value；均为空时为 null
medicalRecordTime：病历时间（从门诊病历图片聚合），格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss，无数据时为 null
prescriptionTime：处方时间（从处方图片聚合），格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss，无数据时为 null
reportTime：检查报告时间（从检验报告图片聚合），格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss，无数据时为 null

1.4 就诊记录列表

路由：?r=igg4/medical-visit/list
请求方式：GET
说明：获取当前患者的就诊记录列表，支持分页和年份/次数筛选。

请求参数

参数	类型	必填	说明
page	int	否	页码，默认 1
pageSize	int	否	每页条数，默认 10
year	int	否	按就诊年份筛选
count	int	否	取最近 N 次就诊记录

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "page": 1,
    "pages": 5,
    "totalCount": 50,
    "list": [
      {
        "id": 1,
        "visitDate": "2026-06-29",
        "nextVisitDate": "2026-09-29",
        "recordStatus": 2,
        "igG4Value": 135.0,
        "manualIgG4Value": 135.0,
        "displayIgG4Value": 135.0,
        "medicationsUsed": [2, 3],
        "immunosuppressantName": [1, 7],
        "medicationsUsedOtherText": null,
        "immunosuppressantNameOtherText": null,
        "lastIgG4Value": 120.0,
        "change": 15.0,
        "medicalRecordTime": "2026-06-29 09:30:00",
        "prescriptionTime": "2026-06-29 10:15:00",
        "reportTime": "2026-06-28 14:20:00"
      }
    ]
  }
}

说明

列表按 VisitDate 降序排列
同时传入 year 和 count 时，先按年份筛选再取最近 N 条
lastIgG4Value：上一次就诊的 IgG4 值，float 类型；无上一次记录时为 null
change：本次与上一次 IgG4 值的差值（本次 - 上次），float 类型；任一值为 null 时为 null
manualIgG4Value：患者手动录入的 IgG4 数值（冗余字段），未录入时为 null
displayIgG4Value：展示用 IgG4 数值，优先取 manualIgG4Value，为空则取 igG4Value；均为空时为 null
medicalRecordTime：病历时间（从门诊病历图片聚合），格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss，无数据时为 null
prescriptionTime：处方时间（从处方图片聚合），格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss，无数据时为 null
reportTime：检查报告时间（从检验报告图片聚合），格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss，无数据时为 null
medicationsUsed：本次就诊已使用的药物（多选），值为常量ID数组，见附录G；未选择时为 null
immunosuppressantName：正在使用的免疫抑制剂名称（多选），值为常量ID数组，见附录G；未选择时为 null
medicationsUsedOtherText：本次就诊已使用药物选择"其他"(99)时的补充文本，未选择"其他"时为 null
immunosuppressantNameOtherText：正在使用的免疫抑制剂名称选择"其他"(99)时的补充文本，未选择"其他"时为 null

1.5 删除就诊记录

路由：?r=igg4/medical-visit/delete
请求方式：POST
说明：逻辑删除就诊记录及其所有图片。使用数据库事务。

请求参数

参数	类型	必填	说明
id	int	是	就诊记录 ID

响应示例

{
  "code": 0,
  "message": "success",
  "data": true
}

业务逻辑说明

校验记录存在、属于当前患者
将主记录 status 设为 100（删除），记录 UpdateWorkerId/UpdateTime
将该记录下所有图片 status 设为 100（删除）

1.6 图片字段历史列表

路由：?r=igg4/medical-visit/image-history
请求方式：GET
说明：查询指定图片类型的历史列表，返回每次就诊中该类型图片的 URL，按就诊日期降序排列。仅返回已提交的记录。

请求参数

参数	类型	必填	说明
imageField	string	是	图片类型标识
year	int	否	按就诊年份筛选
count	int	否	取最近 N 次就诊记录

imageField 枚举

值	说明
outpatientRecord	门诊病历及处方
labReport	检验报告
imagingExam	影像学检查
pathology	病理诊断及活检
immuneFunction	外周血免疫功能评估

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "visitDate": "2026-06-29",
        "imageUrl": "https://...",
        "ocrStatus": 2
      },
      {
        "visitDate": "2026-03-15",
        "imageUrl": "https://...",
        "ocrStatus": 0
      }
    ]
  }
}

1.7 指标字段历史列表

路由：?r=igg4/medical-visit/indicator-history
请求方式：GET
说明：查询指定指标字段的历史数据列表，返回每次就诊中该指标的值，按就诊日期降序排列。仅返回已提交的记录。

请求参数

参数	类型	必填	说明
indicatorField	string	是	指标字段标识
year	int	否	按就诊年份筛选
count	int	否	取最近 N 次就诊记录

indicatorField 枚举

值	说明	单位
igG4	IgG4（免疫球蛋白G4亚类）	mg/dL
totalIgG	总IgG（免疫球蛋白G）	mg/dL
igE	IgE（免疫球蛋白E）	IU/mL
eos	EOS#（嗜酸细胞绝对计数）	10^9/L
esr	ESR（红细胞沉降率/血沉）	mm/h
crp	CRP（C-反应蛋白）	mg/L

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "unit": "mg/dL",
    "list": [
      {
        "visitDate": "2026-06-29",
        "value": 135.0
      },
      {
        "visitDate": "2026-03-15",
        "value": 260.0
      }
    ]
  }
}

1.8 OCR 图片解析

路由：?r=igg4/medical-visit/ocr-parse
请求方式：POST
说明：对图片进行阿里云 OCR 文字识别。检验报告类型自动提取指标数值并做单位换算，其他类型仅返回拼接文本。

请求参数

参数	类型	必填	说明
imageUrl	string	是	图片 URL（需为阿里云上海 OSS 地址）
imageType	string	是	图片类型标识

imageType 枚举

同 1.1 images.imageType

响应示例 — 检验报告类型（imageType=labReport）

{
  "code": 0,
  "message": "success",
  "data": {
    "ocrText": "IgG4 1.35 g/L\n总IgG 12.0 g/L\nIgE 50 IU/mL\nESR 20 mm/h\nCRP 5 mg/L",
    "ocrParsedData": {
      "reportTime": "2026-06-28 14:20:00",
      "indicators": {
        "igG4": {"value": 135.0, "unit": "mg/dL"},
        "totalIgG": {"value": 1200.0, "unit": "mg/dL"},
        "igE": {"value": 50.0, "unit": "IU/mL"},
        "eos": {"value": null, "unit": "10^9/L"},
        "esr": {"value": 20.0, "unit": "mm/h"},
        "crp": {"value": 5.0, "unit": "mg/L"}
      }
    }
  }
}

响应示例 — 门诊病历类型（imageType=outpatientRecord）

{
  "code": 0,
  "message": "success",
  "data": {
    "ocrText": "患者XXX，男，45岁\n主诉：反复腹痛3月\n现病史：患者3月前无明显诱因出现腹痛\n诊断：IgG4相关性疾病\n处理意见：激素治疗，定期复查",
    "ocrParsedData": {
      "chiefComplaint": "反复腹痛3月",
      "medicalHistory": "患者3月前无明显诱因出现腹痛",
      "diagnosis": "IgG4相关性疾病",
      "treatmentPlan": "激素治疗，定期复查",
      "prescription": "甲泼尼龙片 4mg 每日1次 口服 30片",
      "clinicalDiagnosis": "IgG4相关性疾病"
    }
  }
}

响应示例 — 其他类型（如 imageType=imagingExam）

{
  "code": 0,
  "message": "success",
  "data": {
    "ocrText": "影像学检查报告文本...",
    "ocrParsedData": "影像学检查报告文本..."
  }
}

OCR 指标识别规则

指标	关键词匹配	单位换算
IgG4	`IgG4`、`免疫球蛋白G4`、`免疫球蛋白G4亚类`	若为 g/L 则 ×100 → mg/dL
总IgG	`IgG`（独立，非IgG1-5/IgG4/IgE）、`免疫球蛋白G`	若为 g/L 则 ×100 → mg/dL
IgE	`IgE`、`免疫球蛋白E`	不换算，保持 IU/mL
EOS#	`EOS#`、`嗜酸细胞绝对计数`、`嗜酸性粒细胞绝对值`	不换算，保持 10^9/L
ESR	`ESR`、`红细胞沉降率`、`血沉`	不换算，保持 mm/h
CRP	`CRP`、`C-反应蛋白`、`C反应蛋白`	不换算，保持 mg/L

门诊病历 OCR 识别规则

字段	关键词匹配
主诉	`主诉`
病史	`现病史`、`既往史`、`病史`
诊断	`诊断`、`Imp`、`印象`
处理意见	`处理意见`、`医嘱`、`处理`、`治疗方案`

1.9 保存复诊提醒配置

路由：?r=igg4/medical-visit/save-reminder-config
请求方式：POST
说明：患者配置是否开启复诊提醒。开启后，定时任务将在复诊日期前7天发送微信Push通知。使用数据库事务。

请求参数

参数	类型	必填	说明
reminderEnabled	int	是	是否开启复诊提醒：1-开启，2-关闭

请求示例

{
  "reminderEnabled": 1
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": true
}

业务逻辑说明

校验 reminderEnabled 参数必填，值只能为1（开启）或2（关闭），否则报错"reminderEnabled参数无效"
查询当前患者是否已有配置记录
已有配置：更新 ReminderEnabled，记录 UpdateWorkerId/UpdateTime
无配置：新建配置记录，设置 PatientId、ReminderEnabled、Status=1，记录 CreateWorkerId/CreateTime/UpdateWorkerId/UpdateTime
每个患者只保留一条有效配置记录（通过 PatientId 唯一约束保证）

1.10 获取复诊提醒配置

路由：?r=igg4/medical-visit/get-reminder-config
请求方式：GET
说明：获取当前患者的复诊提醒配置。未配置过时返回默认值（关闭）。

请求参数

无

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "reminderEnabled": 2
  }
}

说明

reminderEnabled：1-开启，2-关闭。患者未配置过时默认返回2（关闭）
配置数据来源于 t_medical_visit_reminder_config 表

1.11 获取最近就诊记录

路由：?r=igg4/medical-visit/get-latest-record
请求方式：GET
说明：获取当前患者按就诊日期最近的一条就诊记录详情，包含草稿和已提交记录。无记录时 data 为 null。

请求参数

无

响应示例 — 有记录时

同 1.3 获取就诊记录详情的 data 格式。

响应示例 — 无记录时

{
  "code": 0,
  "message": "success",
  "data": null
}

说明

返回当前患者按就诊日期（VisitDate）降序最近的一条就诊记录详情
不限制记录状态，草稿（recordStatus=1）和已提交（recordStatus=2）均可能返回
同一天多条记录时，返回 ID 最大的那条
返回格式与详情接口完全一致，包含图片分组等完整信息

二、医生端接口

模块路由前缀：igg4/doctor/medical-visit

医生端所有接口均为只读，且只能查看已提交（recordStatus=2）的记录，草稿对医生不可见。所有接口需额外传入 patientId 参数指定查看的患者。

2.1 就诊记录列表

路由：?r=igg4/doctor/medical-visit/list
请求方式：GET
说明：医生查看指定患者的已提交就诊记录列表。

请求参数

参数	类型	必填	说明
patientId	int	是	患者 ID
page	int	否	页码，默认 1
pageSize	int	否	每页条数，默认 10
year	int	否	按就诊年份筛选
count	int	否	取最近 N 次就诊记录

响应示例

同 1.4 就诊记录列表，但仅返回已提交的记录。

2.2 就诊记录详情

路由：?r=igg4/doctor/medical-visit/detail
请求方式：GET
说明：医生查看指定患者的某条就诊记录详情。

请求参数

参数	类型	必填	说明
id	int	是	就诊记录 ID
patientId	int	是	患者 ID

响应示例

同 1.3 获取就诊记录详情。

2.3 图片字段历史列表

路由：?r=igg4/doctor/medical-visit/image-history
请求方式：GET
说明：医生查看指定患者的某种图片类型历史列表。

请求参数

参数	类型	必填	说明
patientId	int	是	患者 ID
imageField	string	是	图片类型标识
year	int	否	按就诊年份筛选
count	int	否	取最近 N 次就诊记录

imageField 枚举

同 1.6 imageField 枚举

响应示例

同 1.6 图片字段历史列表，仅返回已提交记录的数据。

2.4 指标字段历史列表

路由：?r=igg4/doctor/medical-visit/indicator-history
请求方式：GET
说明：医生查看指定患者的某个指标字段历史数据趋势。

请求参数

参数	类型	必填	说明
patientId	int	是	患者 ID
indicatorField	string	是	指标字段标识
year	int	否	按就诊年份筛选
count	int	否	取最近 N 次就诊记录

indicatorField 枚举

同 1.7 indicatorField 枚举

响应示例

同 1.7 指标字段历史列表，仅返回已提交记录的数据。

2.5 导出就诊记录PPT

路由：?r=igg4/doctor/medical-visit/export-ppt
请求方式：POST
说明：医生导出指定患者的就诊记录PPT文件，包含5个模块：患者基本信息、主诉与诊断、检验报告指标趋势、就诊记录处方、激素用量。仅包含已提交的记录。

请求参数

参数	类型	必填	说明
patientId	int	是	患者 ID

响应

直接返回PPT文件流（Content-Type: application/vnd.openxmlformats-officedocument.presentationml.presentation），浏览器触发下载。文件名格式：就诊记录_{patientId}_{timestamp}.pptx。

PPT内容结构

页码	模块	说明
1	01. 患者基本信息	姓名（脱敏）、性别、年龄段、首次发病时间、首次发病部位、是否确诊IgG4
2+	02. 就诊记录病历：主诉与诊断	每页5条，展示就诊时间/主诉/病史/诊断/处理意见
N+	03. 检验报告（实验室核心血清学指标趋势追踪）	每页10条，表格展示6项指标
N+	04. 就诊记录处方	每页3条，展示处方信息
N+	05. 激素用量	每页10条，表格展示日期+用量

数据脱敏规则

患者姓名：2字显示"张*"，3字及以上显示"张*丰"（保留首尾字符）
年龄：转换为年龄段（18-44岁/45-59岁/60-74岁/75岁以上）

业务逻辑说明

校验 patientId 必传
查询患者基本信息（TZdPatientInfo + 健康问卷最新答案）
查询已提交就诊记录列表（RecordStatus=2, Status=1）
查询用药记录（TZdPatientMedicationRecord）
生成PPT临时文件并返回文件流
返回后自动删除临时文件

三、后台管理员接口

模块路由前缀：medical-visit-record

后台管理员负责对小程序用户上传的图片进行涂抹处理，涂抹后上传涂抹图片并同步触发 OCR 解析。所有 POST 接口使用数据库事务。

3.1 就诊记录列表

路由：?r=medical-visit-record/list
请求方式：GET
说明：后台管理就诊记录列表，以图片为主表（一张图一条数据），支持按提交人姓名和图片类型筛选，仅展示已提交的记录。

请求参数

参数	类型	必填	说明
submitterName	string	否	提交人姓名（患者姓名模糊搜索）
imageType	string	否	图片类型标识，不传则返回全部，见枚举表
page	int	否	页码，默认 1
pageSize	int	否	每页条数，默认 10

imageType 枚举

同 1.1 images.imageType

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "page": 1,
    "pages": 5,
    "totalCount": 50,
    "list": [
      {
        "id": 102,
        "submitterName": "张三",
        "recordTime": "2026-06-29 14:20:00",
        "visitDate": "2026-06-29",
        "nextVisitDate": "2026-09-29",
        "imageType": "labReport",
        "imageUrl": "https://oss.example.com/img001.jpg",
        "maskedImageUrl": "https://oss.example.com/img001_masked.jpg",
        "igG4Value": 135.0,
        "manualIgG4Value": 135.0,
        "displayIgG4Value": 135.0,
        "chiefComplaint": null,
        "medicalHistory": null,
        "diagnosis": null,
        "treatmentPlan": null,
        "medicalRecordTime": null,
        "prescriptionTime": null,
        "reportTime": "2026-06-28 14:20:00",
        "prescription": null,
        "clinicalDiagnosis": null,
        "oralHormoneDosage": 4.0,
        "medicationsUsed": [2, 3],
        "immunosuppressantName": [1, 7],
        "medicationsUsedOtherText": null,
        "immunosuppressantNameOtherText": null
      },
      {
        "id": 103,
        "submitTime": "2026-06-29 10:30:00",
        "submitterName": "张三",
        "recordTime": "2026-06-29 15:00:00",
        "visitDate": "2026-06-29",
        "nextVisitDate": "2026-09-29",
        "imageType": "outpatientRecord",
        "imageUrl": "https://oss.example.com/img002.jpg",
        "maskedImageUrl": "https://oss.example.com/img002_masked.jpg",
        "igG4Value": null,
        "manualIgG4Value": 135.0,
        "displayIgG4Value": 135.0,
        "chiefComplaint": "反复腹痛3月",
        "medicalHistory": "患者3月前无明显诱因出现腹痛",
        "diagnosis": "IgG4相关性疾病",
        "treatmentPlan": "激素治疗，定期复查",
        "medicalRecordTime": "2026-06-29 09:30:00",
        "prescriptionTime": "2026-06-29 10:15:00",
        "reportTime": null,
        "prescription": "甲泼尼龙片 4mg 每日1次 口服 30片",
        "clinicalDiagnosis": "IgG4相关性疾病",
        "oralHormoneDosage": 4.0,
        "medicationsUsed": [2, 3],
        "immunosuppressantName": [1, 7],
        "medicationsUsedOtherText": null,
        "immunosuppressantNameOtherText": null
      }
    ]
  }
}

字段说明

字段	类型	说明
id	int	图片记录 ID
submitterName	string	提交人姓名（患者姓名）
recordTime	string	记录时间（图片创建时间）
visitDate	string	就诊时间
nextVisitDate	string	复诊时间
imageType	string	图片类型标识（camelCase）
imageUrl	string	患者提交的图片 URL
maskedImageUrl	string	后台处理后的图片 URL，未涂抹时为 null
igG4Value	float	IgG4 数值（mg/dL），仅检验报告类型有值
manualIgG4Value	float	患者手动录入的 IgG4 数值（冗余字段，mg/dL），未录入时为 null
displayIgG4Value	float	展示用 IgG4 数值，优先取 manualIgG4Value，为空则取 igG4Value；均为空时为 null
chiefComplaint	string	主诉内容，仅门诊病历类型有值
medicalHistory	string	现病史/既往史/病史，仅门诊病历类型有值
diagnosis	string	诊断，仅门诊病历类型有值
treatmentPlan	string	处理意见/医嘱/治疗方案，仅门诊病历类型有值
medicalRecordTime	string	病历时间（图片类型=门诊病历时有值），格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss
prescriptionTime	string	处方时间（图片类型=门诊病历时有值），格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss
reportTime	string	检查报告时间（图片类型=检验报告时有值），格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss
prescription	string	处方内容，仅门诊病历类型有值
clinicalDiagnosis	string	临床诊断，仅处方类型图片有值；未解析到时为 null
oralHormoneDosage	float	激素用量（片/天）
medicationsUsed	array	本次就诊已使用的药物（多选），值为常量ID数组，见附录G；未选择时为 null
immunosuppressantName	array	正在使用的免疫抑制剂名称（多选），值为常量ID数组，见附录G；未选择时为 null
medicationsUsedOtherText	string	本次就诊已使用药物选择"其他"(99)时的补充文本，未选择"其他"时为 null
immunosuppressantNameOtherText	string	正在使用的免疫抑制剂名称选择"其他"(99)时的补充文本，未选择"其他"时为 null

业务逻辑说明

以图片表（t_iggfour_medical_visit_record_image）为主表，一张图一条数据
JOIN 就诊记录表获取 VisitDate、NextVisitDate、OralHormoneDosage，且约束 RecordStatus=2（已提交）
JOIN 患者表获取患者姓名（submitterName）
提交人姓名筛选：患者姓名模糊匹配（LIKE）
图片类型筛选：imageType 参数传入 camelCase 标识，内部转为整型后 WHERE 匹配
仅展示已提交记录（RecordStatus=2），草稿不在列表中显示
按图片创建时间（CreateTime）降序排列

3.2 上传涂抹图片并解析

路由：?r=medical-visit-record/upload-masked-image
请求方式：POST
说明：管理员上传涂抹后的图片 URL，保存后同步触发 OCR 解析。涂抹后立即执行 OCR，无需异步任务。使用数据库事务。

请求参数

参数	类型	必填	说明
imageId	int	是	图片记录 ID
maskedImageUrl	string	是	涂抹后图片 URL

请求示例

{
  "imageId": 102,
  "maskedImageUrl": "https://oss.example.com/img001_masked.jpg"
}

响应示例 — 检验报告类型（imageType=labReport）

{
  "code": 0,
  "message": "success",
  "data": {
    "imageId": 102,
    "maskedImageUrl": "https://oss.example.com/img001_masked.jpg",
    "ocrStatus": 2,
    "ocrText": "IgG4 1.35 g/L\n总IgG 12.0 g/L\nIgE 50 IU/mL\nESR 20 mm/h\nCRP 5 mg/L",
    "ocrParsedData": {
      "reportTime": "2026-06-28 14:20:00",
      "indicators": {
        "igG4": {"value": 135.0, "unit": "mg/dL"},
        "totalIgG": {"value": 1200.0, "unit": "mg/dL"},
        "igE": {"value": 50.0, "unit": "IU/mL"},
        "eos": {"value": null, "unit": "10^9/L"},
        "esr": {"value": 20.0, "unit": "mm/h"},
        "crp": {"value": 5.0, "unit": "mg/L"}
      }
    },
		"igG4Value": 322,
		"totalIgGValue": 1370,
		"igEValue": null,
		"eosCount": null,
		"esrValue": null,
		"crpValue": null,
		"chiefComplaint": null,
		"medicalHistory": null,
		"diagnosis": null,
		"treatmentPlan": null,
		"prescription": null,
		"clinicalDiagnosis": null,
		"medicalRecordTime": null,
		"prescriptionTime": null,
		"reportTime": "2026-06-28 14:20:00"
  }
}

响应示例 — 门诊病历类型（imageType=outpatientRecord）

{
  "code": 0,
  "message": "success",
  "data": {
    "imageId": 103,
    "maskedImageUrl": "https://oss.example.com/img002_masked.jpg",
    "ocrStatus": 2,
    "ocrText": "患者XXX，男，45岁\n主诉：反复腹痛3月\n诊断：IgG4相关性疾病\n处理意见：激素治疗，定期复查",
    "ocrParsedData": {
      "medicalRecordTime": "2026-06-29 09:30:00",
      "prescriptionTime": "2026-06-29 10:15:00",
      "chiefComplaint": "反复腹痛3月",
      "medicalHistory": "患者3月前无明显诱因出现腹痛",
      "diagnosis": "IgG4相关性疾病",
      "treatmentPlan": "激素治疗，定期复查",
      "prescription": "甲泼尼龙片 4mg 每日1次 口服 30片",
      "clinicalDiagnosis": "IgG4相关性疾病"
    },
		"igG4Value": null,
		"totalIgGValue": null,
		"igEValue": null,
		"eosCount": null,
		"esrValue": null,
		"crpValue": null,
		"chiefComplaint": "反复腹痛3月",
    "medicalHistory": "患者3月前无明显诱因出现腹痛",
    "diagnosis": "IgG4相关性疾病",
    "treatmentPlan": "激素治疗，定期复查",
    "prescription": "甲泼尼龙片 4mg 每日1次 口服 30片",
    "clinicalDiagnosis": "IgG4相关性疾病",
    "medicalRecordTime": "2026-06-29 09:30:00",
    "prescriptionTime": "2026-06-29 10:15:00",
    "reportTime": null
  }
}

响应示例 — OCR 解析失败

{
  "code": 0,
  "message": "success",
  "data": {
    "imageId": 104,
    "maskedImageUrl": "https://oss.example.com/img003_masked.jpg",
    "ocrStatus": 3,
    "ocrText": null,
    "ocrParsedData": null,
    "igG4Value": null,
		"totalIgGValue": null,
		"igEValue": null,
		"eosCount": null,
		"esrValue": null,
		"crpValue": null,
    "chiefComplaint": null,
		"medicalHistory": null,
		"diagnosis": null,
		"treatmentPlan": null,
		"prescription": null,
		"clinicalDiagnosis": null,
		"medicalRecordTime": null,
		"prescriptionTime": null,
		"reportTime": null
  }
}

业务逻辑说明

校验 imageId 对应的图片记录存在，否则报错"图片记录不存在"
校验管理员已登录，获取当前操作人 workerId
事务1：保存 MaskedImageUrl，设置 OcrStatus=1（解析中），清空旧的 OcrText/OcrParsedData/指标字段/时间字段（MedicalRecordTime/PrescriptionTime/ReportTime），记录 UpdateWorkerId/UpdateTime
事务1提交后，同步调用 OCR 服务：LabReportOcrService::recognizeByType($maskedImageUrl, $imageTypeKey)
根据 imageType 类型处理 OCR 结果：
- 检验报告（labReport）：解析指标值写入图片记录的独立指标字段（IgG4Value/TotalIgGValue 等），时间字段写入 ReportTime
- 门诊病历（outpatientRecord）：解析文本写入图片记录的病历文本字段（ChiefComplaint/MedicalHistory 等），时间字段写入 MedicalRecordTime/PrescriptionTime
- 其他类型：原始文本写入 OcrText，OcrParsedData 存原文
事务2：写入 OCR 解析结果，设置 OcrStatus=2（解析完成），记录 UpdateWorkerId/UpdateTime
若 OCR 调用抛异常，事务2回退：设置 OcrStatus=3（解析失败），记录 UpdateWorkerId/UpdateTime
返回包含 maskedImageUrl、ocrStatus、ocrText、ocrParsedData、指标字段的结果数据
igG4Value - IgG4 指标值（单位：mg/dL）
totalIgGValue - 总 IgG 指标值（单位：mg/dL）
igEValue - IgE 指标值（单位：IU/mL）
eosCount - eos 指标值（单位：10^9/L）
esrValue - ESR 指标值（单位：mm/h）
crpValue - CRP 指标值（单位：mg/L）
chiefComplaint - 主诉
medicalHistory - 病史
diagnosis - 诊断
treatmentPlan - 处理意见
prescription - 处方
medicalRecordTime - 病历时间（门诊病历图片识别为门诊病历时，从OCR解析获取）
prescriptionTime - 处方时间（门诊病历图片识别为处方时，从OCR解析获取）
reportTime - 检查报告时间（检验报告图片，从OCR解析获取）
ocrParsedData 结构说明：检验报告返回 {reportTime, indicators: {...}}，门诊病历返回 {medicalRecordTime, prescriptionTime, chiefComplaint, ...}

ocrStatus 枚举

值	说明
0	待解析（小程序用户已上传原图，后台尚未涂抹）
1	解析中（后台已上传涂抹图片，OCR 正在执行）
2	解析完成
3	解析失败

附录

A. 记录状态枚举

值	常量名	说明
1	RECORD_STATUS_DRAFT	草稿
2	RECORD_STATUS_SUBMITTED	已提交

B. 数据状态枚举

值	常量名	说明
1	STATUS_ACTIVE	有效
100	STATUS_DELETED	已删除

C. 口服激素用量预设选项（片/天）

值	说明
1	1片/天
2	2片/天
4	4片/天
6	6片/天
8	8片/天

D. 检验指标单位换算

指标	原始单位	目标单位	换算公式
IgG4	g/L	mg/dL	值 × 100
总IgG	g/L	mg/dL	值 × 100
IgE	—	IU/mL	不换算
EOS#	—	10^9/L	不换算
ESR	—	mm/h	不换算
CRP	—	mg/L	不换算

E. 数据库表结构

t_iggfour_medical_visit_record 就诊记录主表

字段名	类型	说明
Id	int AUTO_INCREMENT PK	主键
UserId	varchar(40) NOT NULL	用户 ID
PatientId	int NOT NULL	患者 ID
VisitDate	date NOT NULL	就诊日期
NextVisitDate	date DEFAULT NULL	下次复诊日期
IgG4Value	decimal(10,2) DEFAULT NULL	IgG4 数值（OCR 解析）
ManualIgG4Value	decimal(10,2) DEFAULT NULL	IgG4 数值（患者手动录入，冗余字段）
TotalIgGValue	decimal(10,2) DEFAULT NULL	总 IgG 数值
IgEValue	decimal(10,2) DEFAULT NULL	IgE 数值
EosCount	decimal(10,2) DEFAULT NULL	EOS# 计数
ESRValue	decimal(10,2) DEFAULT NULL	ESR 数值
CRPValue	decimal(10,2) DEFAULT NULL	CRP 数值
OralHormoneDosage	decimal(10,2) DEFAULT NULL	口服激素每日用量（片）
MedicationsUsed	varchar(255) DEFAULT NULL	本次就诊已使用的药物（JSON数组，多选），见附录G
ImmunosuppressantName	varchar(255) DEFAULT NULL	正在使用的免疫抑制剂名称（JSON数组，多选），见附录G
MedicationsUsedOtherText	varchar(500) DEFAULT NULL	本次就诊已使用药物-其他-补充文本
ImmunosuppressantNameOtherText	varchar(500) DEFAULT NULL	正在使用的免疫抑制剂名称-其他-补充文本
MedicalRecordTime	varchar(30) DEFAULT NULL	门诊病历时间
PrescriptionTime	varchar(30) DEFAULT NULL	处方时间
ReportTime	varchar(30) DEFAULT NULL	检查报告时间
ChiefComplaint	text DEFAULT NULL	主诉
MedicalHistory	text DEFAULT NULL	病史
Diagnosis	text DEFAULT NULL	诊断
TreatmentPlan	text DEFAULT NULL	处理意见
Prescription	text DEFAULT NULL	处方内容
ClinicalDiagnosis	varchar(500) DEFAULT NULL	临床诊断（从处方图片解析）
RecordStatus	tinyint NOT NULL DEFAULT 1	记录状态：1-草稿，2-已提交
LastRecordId	int DEFAULT NULL	上一条记录 ID
Status	tinyint NOT NULL DEFAULT 1	数据状态：1-有效，100-删除
CreateWorkerId	int NOT NULL DEFAULT 0	创建人
CreateTime	datetime NOT NULL	创建时间
UpdateWorkerId	int NOT NULL DEFAULT 0	更新人
UpdateTime	datetime NOT NULL	更新时间

t_iggfour_medical_visit_record_image 就诊记录图片表

字段名	类型	说明
Id	int AUTO_INCREMENT PK	主键
RecordId	int NOT NULL	关联就诊记录 ID
ImageType	tinyint NOT NULL	图片类型：1-门诊病历，2-检验报告，3-影像检查，4-其他
ImageUrl	varchar(500) NOT NULL	原始图片 URL
MaskedImageUrl	varchar(500) DEFAULT NULL	涂抹后图片 URL
OcrStatus	tinyint NOT NULL DEFAULT 0	OCR 状态：0-未解析，1-解析中，2-解析完成，3-解析失败
OcrText	text DEFAULT NULL	OCR 原始文本
OcrParsedData	text DEFAULT NULL	OCR 解析结果（JSON）
IgG4Value	decimal(10,2) DEFAULT NULL	IgG4 数值
TotalIgGValue	decimal(10,2) DEFAULT NULL	总 IgG 数值
IgEValue	decimal(10,2) DEFAULT NULL	IgE 数值
EosCount	decimal(10,2) DEFAULT NULL	EOS# 计数
ESRValue	decimal(10,2) DEFAULT NULL	ESR 数值
CRPValue	decimal(10,2) DEFAULT NULL	CRP 数值
ChiefComplaint	text DEFAULT NULL	主诉（从门诊病历图片解析）
MedicalHistory	text DEFAULT NULL	病史（从门诊病历图片解析）
Diagnosis	text DEFAULT NULL	诊断（从门诊病历图片解析）
TreatmentPlan	text DEFAULT NULL	处理意见（从门诊病历图片解析）
Prescription	text DEFAULT NULL	从本图OCR解析的处方内容，仅图片类型=1时有值
ClinicalDiagnosis	varchar(500) DEFAULT NULL	临床诊断（从处方图片解析）
MedicalRecordTime	varchar(30) DEFAULT NULL	门诊病历时间
PrescriptionTime	varchar(30) DEFAULT NULL	处方时间
ReportTime	varchar(30) DEFAULT NULL	检查报告时间
SortOrder	int NOT NULL DEFAULT 0	排序序号
Status	tinyint NOT NULL DEFAULT 1	数据状态：1-有效，100-删除
CreateWorkerId	int NOT NULL DEFAULT 0	创建人
CreateTime	datetime NOT NULL	创建时间
UpdateWorkerId	int NOT NULL DEFAULT 0	更新人
UpdateTime	datetime NOT NULL	更新时间

t_medical_visit_reminder_config 复诊提醒配置表

字段名	类型	说明
Id	int AUTO_INCREMENT PK	主键
PatientId	int NOT NULL	患者 ID（唯一索引）
ReminderEnabled	tinyint NOT NULL DEFAULT 2	是否开启复诊提醒：1-开启，2-关闭
Status	tinyint NOT NULL DEFAULT 1	数据状态：1-有效，100-删除
CreateWorkerId	int DEFAULT NULL	创建人
CreateTime	datetime DEFAULT NULL	创建时间
UpdateWorkerId	int DEFAULT NULL	更新人
UpdateTime	datetime DEFAULT NULL	更新时间

G. 药物选项枚举

MedicationsUsed 本次就诊已使用的药物（多选）

值	常量名	说明
1	MED_USED_NO_HORMONE	没有使用激素
2	MED_USED_HORMONE	激素
3	MED_USED_IMMUNOSUPPRESSANT	免疫抑制剂
4	MED_USED_CD19	靶向CD19生物制剂（伊奈利珠单抗）
5	MED_USED_CD20	靶向CD20生物制剂（利妥昔单抗等）
99	MED_USED_OTHER	其他

ImmunosuppressantName 正在使用的免疫抑制剂名称（多选）

值	常量名	说明
1	IMMUNOSUPPRESSANT_MMF	吗替麦考酚酯（骁悉、麦考芬）
2	IMMUNOSUPPRESSANT_AZA	替唑嘌呤
3	IMMUNOSUPPRESSANT_CYC	环磷酰胺
4	IMMUNOSUPPRESSANT_LEF	来氟米特
5	IMMUNOSUPPRESSANT_MTX	甲氨蝶呤
6	IMMUNOSUPPRESSANT_CYC_A	环孢素 A
7	IMMUNOSUPPRESSANT_TAC	他克莫司
8	IMMUNOSUPPRESSANT_IGU	艾拉莫德
99	IMMUNOSUPPRESSANT_OTHER	其他

复诊提醒配置枚举

值	常量名	说明
1	REMINDER_ENABLED	开启复诊提醒
2	REMINDER_DISABLED	关闭复诊提醒
7	REMINDER_DAYS_BEFORE	提前提醒天数（天）

46 KiB Raw Blame History

就诊记录接口文档

通用说明

响应格式

数据命名规则

登录校验

错误码

一、患者端接口

1.1 保存草稿

请求参数

images 每项参数

imageType 枚举

请求示例

响应示例

业务逻辑说明

1.1.0 保存图片记录

请求参数

imageType 枚举

请求示例

响应示例

业务逻辑说明

1.1.1 删除单个图片

请求参数

请求示例

响应示例

业务逻辑说明

1.2 提交就诊记录

请求参数

请求示例

响应示例

业务逻辑说明

1.3 获取就诊记录详情

请求参数

响应示例

images 字段说明

主记录字段说明

1.4 就诊记录列表

请求参数

响应示例

说明

1.5 删除就诊记录

请求参数

响应示例

业务逻辑说明

1.6 图片字段历史列表

请求参数

imageField 枚举

响应示例

1.7 指标字段历史列表

请求参数

indicatorField 枚举

响应示例

1.8 OCR 图片解析

请求参数

imageType 枚举

响应示例 — 检验报告类型（imageType=labReport）

响应示例 — 门诊病历类型（imageType=outpatientRecord）

响应示例 — 其他类型（如 imageType=imagingExam）

OCR 指标识别规则

门诊病历 OCR 识别规则

1.9 保存复诊提醒配置

请求参数

请求示例

响应示例

业务逻辑说明

1.10 获取复诊提醒配置

请求参数

响应示例

说明

1.11 获取最近就诊记录

请求参数

响应示例 — 有记录时

响应示例 — 无记录时

说明

二、医生端接口

2.1 就诊记录列表

请求参数

响应示例

2.2 就诊记录详情

请求参数

46 KiB

Raw Blame History