Shixun/API接口文档.md

# 智慧医院 API 接口文档

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

---

## 目录

1. [服务地址](#1-服务地址)
2. [通用约定](#2-通用约定)
3. [接口一览](#3-接口一览)
4. [业务后端详解](#4-业务后端详解)
5. [AI 微服务详解](#5-ai-微服务详解)
6. [数据模型](#6-数据模型)
7. [枚举与错误码](#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 管理 |

### 统一响应（业务后端）

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

### 分页（业务后端）

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

```json
{
  "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` 结构见 [数据模型](#6-数据模型)。

### 4.1 认证 `/api/auth`

#### POST `/api/auth/login`

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

**data：** `{ token, user }` → [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](#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`

```json
{ "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`

```json
{ "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 启用类接口（知识库 / 用户通用形态）

```json
{ "enabled": true }
```

#### YOLO 激活 / 模式

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

```json
{ "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 示例

```bash
# 登录
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
```

---

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