Shixun/API接口文档.md

智慧医院 API 接口文档

基于当前源码整理。前端开发走 Vite 代理；联调可直接请求业务后端。

---

目录

1. 服务地址
2. 通用约定
3. 接口一览
4. 业务后端详解
5. AI 微服务详解
6. 数据模型
7. 枚举与错误码

---

1. 服务地址

服务	地址	说明
前端	http://localhost:5173	/api 代理到后端
业务后端	http://localhost:8080	前缀 /api/**，JWT 鉴权
AI 微服务	http://127.0.0.1:8001	后端内网调用；Swagger：/docs

前端 :5173  →  后端 :8080/api  →  AI :8001（影像 / 决策 / YOLO）

演示账号

用户名	密码	角色
admin	admin123	ADMIN
doctor1	pass123	DOCTOR
radio1	radio123	RADIOLOGIST

---

2. 通用约定

鉴权

项	说明
Header	Authorization: Bearer <token>
获取 Token	POST /api/auth/login
有效期	24 小时
公开	/api/auth/login、/api/auth/logout、/uploads/**
需登录	其余 /api/**
仅 ADMIN	/api/users/**；AI 配置写操作；知识库写操作；YOLO 管理

统一响应（业务后端）

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

分页（业务后端）

参数	默认	说明
page	0	页码，从 0 开始
size	10	每页条数

{
  "content": [],
  "number": 0,
  "size": 10,
  "totalElements": 100,
  "totalPages": 10
}

Content-Type

类型	场景
application/json	普通接口
multipart/form-data	文件上传

---

3. 接口一览

3.1 业务后端 http://localhost:8080

认证

方法	路径	权限	说明
POST	/api/auth/login	公开	登录，返回 token
POST	/api/auth/logout	公开	登出
GET	/api/auth/me	登录	当前用户
POST	/api/auth/change-password	登录	修改密码
POST	/api/auth/avatar	登录	上传头像

统计

方法	路径	权限	说明
GET	/api/stats/overview	登录	仪表盘总览

患者

方法	路径	权限	说明
GET	/api/patients	登录	分页列表
GET	/api/patients/{id}	登录	详情
GET	/api/patients/{id}/profile	登录	360° 档案
POST	/api/patients	登录	新建
PUT	/api/patients/{id}	登录	更新
DELETE	/api/patients/{id}	登录	删除

影像

方法	路径	权限	说明
GET	/api/imaging	登录	分页列表
GET	/api/imaging/{id}	登录	详情
POST	/api/imaging	登录	新建记录
PUT	/api/imaging/{id}	登录	更新
DELETE	/api/imaging/{id}	登录	删除
POST	/api/imaging/upload	登录	上传影像文件
POST	/api/ai-diagnosis/analyze/{recordId}	登录	提交 AI 诊断
GET	/api/ai-diagnosis/result/{recordId}	登录	查询诊断结果

电子病历

方法	路径	权限	说明
GET	/api/emrs	登录	分页列表
GET	/api/emrs/{id}	登录	详情
POST	/api/emrs	登录	新建（含 AI 决策）
PUT	/api/emrs/{id}	登录	更新
DELETE	/api/emrs/{id}	登录	删除
GET	/api/emrs/{id}/ai-suggestions	登录	AI 辅助决策

预约

方法	路径	权限	说明
GET	/api/appointments	登录	分页列表
GET	/api/appointments/stats	登录	统计
GET	/api/appointments/doctors	登录	医生列表
GET	/api/appointments/{id}	登录	详情
POST	/api/appointments	登录	新建
PUT	/api/appointments/{id}	登录	更新
PATCH	/api/appointments/{id}/status	登录	变更状态
DELETE	/api/appointments/{id}	登录	删除

用户管理

方法	路径	权限	说明
GET	/api/users	ADMIN	分页列表
GET	/api/users/stats	ADMIN	统计
GET	/api/users/{id}	ADMIN	详情
POST	/api/users	ADMIN	新建
PUT	/api/users/{id}	ADMIN	更新
POST	/api/users/{id}/avatar	ADMIN	上传头像
PATCH	/api/users/{id}/enabled	ADMIN	启用/停用
DELETE	/api/users/{id}	ADMIN	删除

AI 对话

方法	路径	权限	说明
POST	/api/ai/chat	登录	对话（CHAT / RAG）
GET	/api/ai/chat/history	登录	历史记录
DELETE	/api/ai/chat/history	登录	清空历史

AI 管理

方法	路径	权限	说明
GET	/api/admin/ai-settings	ADMIN	大模型配置
PUT	/api/admin/ai-settings	ADMIN	保存配置
POST	/api/admin/ai-settings/test	ADMIN	连通测试
GET	/api/admin/ai-service/status	登录	AI 服务状态
GET	/api/admin/ai-knowledge	登录	知识库列表
GET	/api/admin/ai-knowledge/{id}	登录	知识库详情
POST	/api/admin/ai-knowledge	ADMIN	新建文档
PUT	/api/admin/ai-knowledge/{id}	ADMIN	更新文档
PATCH	/api/admin/ai-knowledge/{id}/enabled	ADMIN	启用/停用
DELETE	/api/admin/ai-knowledge/{id}	ADMIN	删除文档

YOLO 管理（代理 AI 服务）

方法	路径	权限	说明
GET	/api/admin/yolo/status	ADMIN	状态
GET	/api/admin/yolo/weights	ADMIN	权重列表
POST	/api/admin/yolo/weights/upload	ADMIN	上传权重
POST	/api/admin/yolo/weights/activate	ADMIN	激活权重
POST	/api/admin/yolo/weights/deactivate	ADMIN	取消激活
DELETE	/api/admin/yolo/weights/{name}	ADMIN	逻辑删除
POST	/api/admin/yolo/mode	ADMIN	设置模式
GET	/api/admin/yolo/visualization	ADMIN	可视化数据
POST	/api/admin/yolo/stats/reset	ADMIN	重置统计
GET	/api/admin/yolo/capability	ADMIN	能力探测

---

3.2 AI 微服务 http://127.0.0.1:8001

无 JWT，建议仅内网访问。

方法	路径	说明
GET	/health	健康检查
POST	/imaging/analyze	影像 YOLO 分析
POST	/report/imaging	生成影像报告
POST	/report/decision	EMR 辅助决策
POST	/rag/query	知识库问答
POST	/rag/ingest	追加知识文档
GET	/rag/stats	知识片段数
GET	/llm/config	LLM 配置
POST	/llm/config	更新 LLM 配置
GET	/llm/status	LLM 状态
GET	/yolo/status	YOLO 状态
GET	/yolo/weights	权重列表
POST	/yolo/weights/upload	上传权重
POST	/yolo/weights/activate	激活权重
POST	/yolo/weights/deactivate	取消激活
DELETE	/yolo/weights/{name}	逻辑删除
POST	/yolo/weights/restore	恢复权重
POST	/yolo/mode	设置模式
GET	/yolo/visualization	可视化
POST	/yolo/stats/reset	重置统计
GET	/yolo/capability	能力探测

---

4. 业务后端详解

以下仅列查询参数与请求体。响应外层均为 { code, message, data }，data 结构见 数据模型。

4.1 认证 /api/auth

POST /api/auth/login

字段	类型	必填	说明
username	string	是	用户名
password	string	是	密码

data： { token, user } → User

POST /api/auth/change-password

字段	类型	必填	说明
oldPassword	string	是	旧密码
newPassword	string	是	新密码，6–64 位

POST /api/auth/avatar

表单字段	类型	必填
file	file	是

---

4.2 患者 /api/patients

GET /api/patients

参数	类型	说明
page	int	页码
size	int	每页条数
keyword	string	姓名/电话关键字

POST/PUT 请求体

字段	类型	必填	说明
name	string	是	姓名
gender	string	是	MALE / FEMALE / OTHER
age	int	是	年龄
idCard	string	否	身份证
phone	string	否	电话
address	string	否	地址
medicalHistory	string	否	病史

GET /api/patients/{id}/profile

data： 患者 + 关联影像 / 病历 / 预约列表及计数。

---

4.3 影像 /api/imaging

GET /api/imaging

参数	类型	说明
page / size	int	分页
keyword	string	关键字
status	string	PENDING / ANALYZING / COMPLETED / ERROR
studyType	string	X_RAY / CT / MRI / ULTRASOUND

POST/PUT 请求体

字段	类型	必填	说明
patientId	long	是	患者 ID
doctorId	long	否	空则用当前用户
studyType	string	是	检查类型
bodyPart	string	是	部位
imageUrl	string	是	先调 upload 得到

POST /api/imaging/upload

表单字段	类型	必填
file	file	是

data： 路径字符串，如 /uploads/images/...

AI 诊断流程

1. POST /api/imaging/upload          → imageUrl
2. POST /api/imaging                 → recordId
3. POST /api/ai-diagnosis/analyze/{id}
4. GET  /api/ai-diagnosis/result/{id}  （轮询至 COMPLETED / ERROR）

GET /api/ai-diagnosis/result/{recordId} 的 data

字段	说明
status	影像状态
diagnosisText	诊断结论
confidenceScore	置信度
findings	所见
recommendations	建议
modelVersion	模型版本
processingTimeMs	耗时
detections	检测框列表
annotatedImageUrl	标注图
fullReport	完整报告
engine	引擎
fallback	是否降级

---

4.4 电子病历 /api/emrs

GET /api/emrs

参数	说明
page / size	分页
keyword	关键字

POST/PUT 请求体

字段	类型	必填	说明
patientId	long	是	患者
doctorId	long	否	空则当前用户
visitDate	date	是	yyyy-MM-dd
diagnosis	string	是	诊断
chiefComplaint	string	否	主诉
presentIllness	string	否	现病史
physicalExamination	string	否	体格检查
treatmentPlan	string	否	治疗方案
medications	string	否	用药
followUpNotes	string	否	随访

POST /api/emrs 的 data

字段	说明
emr	病历对象
aiSupport	AI 决策 → DecisionSupport

---

4.5 预约 /api/appointments

GET /api/appointments

参数	说明
page / size	分页
keyword	关键字
status	预约状态
date	yyyy-MM-dd

POST/PUT 请求体

字段	类型	必填	说明
patientId	long	是	患者
doctorId	long	否	医生
department	string	是	科室
appointmentDate	date	是	预约日期
appointmentTime	time	否	预约时间
reason	string	否	事由
notes	string	否	备注
status	string	否	默认 SCHEDULED

PATCH /api/appointments/{id}/status

{ "status": "CONFIRMED" }

状态流转：SCHEDULED → CONFIRMED → COMPLETED，或 CANCELLED / NO_SHOW。

---

4.6 用户 /api/users（ADMIN）

GET /api/users

参数	说明
page / size	分页
keyword	关键字
role	角色筛选
enabled	true / false

POST/PUT 请求体

字段	类型	必填	说明
username	string	是	用户名
password	string	新建必填	更新可空
realName	string	是	真实姓名
role	string	是	DOCTOR / RADIOLOGIST / ADMIN
department	string	否	科室
phone	string	否	电话
email	string	否	邮箱
enabled	boolean	否	默认 true

PATCH /api/users/{id}/enabled

{ "enabled": false }

---

4.7 AI 对话 /api/ai

POST /api/ai/chat

字段	类型	必填	说明
mode	string	是	CHAT 或 RAG
question	string	是	问题

GET /api/ai/chat/history

参数	默认	说明
limit	30	条数上限

---

4.8 AI 管理 /api/admin

PUT /api/admin/ai-settings

字段	类型	说明
apiBaseUrl	string	OpenAI 兼容地址
apiKey	string	null 表示不改密钥
model	string	模型名
enabled	boolean	是否启用
temperature	double	温度
systemPrompt	string	系统提示词

POST/PUT 知识库请求体

字段	类型	必填
title	string	是
content	string	是
category	string	否
enabled	boolean	否

PATCH 启用类接口（知识库 / 用户通用形态）

{ "enabled": true }

YOLO 激活 / 模式

{ "name": "best.pt", "demo_mode": "auto" }

{ "demo_mode": "real" }

demo_mode：demo | real | auto

---

5. AI 微服务详解

响应不包 {code, message, data}，直接返回业务 JSON。

5.1 GET /health

字段	说明
status	固定 ok
yolo_available	YOLO 是否可用
monai_available	MONAI 是否可用
langchain_available	LangChain 是否可用
llm_configured	是否配置 LLM
demo_mode	当前模式
knowledge_docs	知识片段数

5.2 POST /imaging/analyze

multipart/form-data

字段	类型	必填	说明
file	file	二选一	上传文件
image_path	string	二选一	服务端路径
study_type	string	否	默认 CT
body_part	string	否	部位
patient_summary	string	否	摘要

响应字段： detections、annotated_image_base64、preliminary_diagnosis、findings、recommendations、confidence、model_version、mode、full_report、disclaimer

5.3 POST /report/decision

字段	类型	说明
chief_complaint	string	主诉
history	string	病史
exam_findings	string	检查
diagnosis	string	诊断
medications	string	用药
imaging_summary	string	影像摘要
patient	object	{ age, gender, name }

5.4 POST /rag/query

字段	类型	默认	说明
query	string	—	问题
top_k	int	4	返回条数
context	string	""	附加上下文

实现为文档切分 + 内存关键词检索，未使用向量数据库。

5.5 POST /rag/ingest

字段	类型	必填
title	string	是
content	string	是
category	string	否，默认「自定义」

5.6 POST /llm/config

兼容 api_base_url / apiBaseUrl、api_key / apiKey。

字段	说明
enabled	是否启用
api_base_url	接口地址
api_key	null 不改；"" 清空
model	模型名
temperature	温度

---

6. 数据模型

User

字段	类型	说明
id	long	ID
username	string	用户名
realName	string	真实姓名
role	string	角色
department	string	科室
phone	string	电话
email	string	邮箱
avatar	string	头像 URL
enabled	boolean	是否启用

Patient

字段	类型	说明
id	long	ID
name	string	姓名
gender	string	性别
age	int	年龄
idCard	string	身份证
phone	string	电话
address	string	地址
medicalHistory	string	病史
createdAt	datetime	创建时间

ImagingRecord

字段	类型	说明
id	long	ID
patientId	long	患者
patientName	string	患者姓名
doctorId	long	医生
doctorRealName	string	医生姓名
studyType	string	检查类型
bodyPart	string	部位
imageUrl	string	影像路径
status	string	状态
aiDiagnosis	string	AI 诊断
aiConfidence	double	置信度
createdAt	datetime	创建时间

Emr

字段	类型	说明
id	long	ID
patientId / patientName	—	患者
doctorId / doctorRealName	—	医生
visitDate	date	就诊日
chiefComplaint	string	主诉
presentIllness	string	现病史
physicalExamination	string	体格检查
diagnosis	string	诊断
treatmentPlan	string	治疗
medications	string	用药
followUpNotes	string	随访
aiSuggestions	string	AI 建议文本
createdAt	datetime	创建时间

Appointment

字段	类型	说明
id	long	ID
patientId / patientName / patientPhone	—	患者
doctorId / doctorName	—	医生
department	string	科室
appointmentDate	date	日期
appointmentTime	time	时间
reason / notes	string	事由 / 备注
status	string	状态
createdAt	datetime	创建时间

DecisionSupport

字段	说明
suggestions	治疗建议
medicationSuggestions	用药建议
riskAssessments	风险评估
nursingAdvice	护理建议
followUpPlan	随访计划
conflicts	冲突提示
sources	RAG 来源
fullText	全文
engine	引擎标识
fallback	是否降级
disclaimer	免责声明

AiChatResponse

字段	说明
mode	CHAT / RAG
question	问题
answer	回答
usedLlm	是否调用大模型
fallback	是否降级
sources	引用来源列表

Detection（AI 检测框）

字段	说明
label	标签
label_zh	中文标签
confidence	置信度
bbox	[x1, y1, x2, y2]

---

7. 枚举与错误码

枚举

名称	取值
角色	ADMIN, DOCTOR, RADIOLOGIST
性别	MALE, FEMALE, OTHER
检查类型	X_RAY, CT, MRI, ULTRASOUND
影像状态	PENDING, ANALYZING, COMPLETED, ERROR
预约状态	SCHEDULED, CONFIRMED, COMPLETED, CANCELLED, NO_SHOW
对话模式	CHAT, RAG
YOLO 模式	demo, real, auto

业务后端 code

code	含义
0	成功
400	参数错误
401	未登录 / token 过期
403	无权限
404	不存在
409	冲突
1000	业务异常
500	服务器错误

降级说明

场景	行为
AI 服务离线	影像诊断、病历决策走本地规则，fallback=true
未配置 LLM Key	返回检索摘要或模板文本
YOLO 不可用	进入 demo 模式

---

附录：curl 示例

# 登录
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"doctor1","password":"pass123"}'

# 带 Token 请求
curl http://localhost:8080/api/patients?page=0&size=10 \
  -H "Authorization: Bearer <token>"

# AI 健康检查
curl http://127.0.0.1:8001/health

---

输出仅供教学实训，不能替代执业医师诊断。 )