改后端端口

2026-08-18 11:26:14 +08:00
parent 9b8b8b57b3
commit 7d8004a7ba
2 changed files with 759 additions and 2 deletions
@@ -0,0 +1,757 @@
+# 智慧医院 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
+```
+
+---
+
+*输出仅供教学实训，不能替代执业医师诊断。*
+)