刘金宝
673 lines
14 KiB
Markdown
673 lines
14 KiB
Markdown
# 后端 API 对接文档
|
||
|
||
## 1. 通用约定
|
||
|
||
Base URL：
|
||
|
||
```text
|
||
http://127.0.0.1:8000/api/v1
|
||
```
|
||
|
||
必传 Header：
|
||
|
||
| Header | 说明 |
|
||
|---|---|
|
||
| `X-User-Id` | 宿主系统传入的用户 ID，所有业务隔离依据 |
|
||
| `X-Entry-Scene` | 入口场景，前端 Demo 默认 `vue_demo` |
|
||
|
||
可传 Header：
|
||
|
||
| Header | 说明 |
|
||
|---|---|
|
||
| `X-Tenant-Id` | 宿主系统租户/机构 ID |
|
||
| `X-Class-Id` | 教学班级 ID |
|
||
| `X-Role` | 用户角色 |
|
||
|
||
统一响应：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
常见错误码：
|
||
|
||
| code | 含义 |
|
||
|---|---|
|
||
| `USER_ID_REQUIRED` | 缺少 `X-User-Id` |
|
||
| `CASE_NOT_FOUND` | 病例不存在或未启用 |
|
||
| `SESSION_NOT_FOUND` | 会话不存在或不属于当前用户 |
|
||
| `SESSION_STATUS_INVALID` | 当前阶段不允许该操作 |
|
||
| `INQUIRY_REQUIRED` | 完成问诊前至少需要一轮医生提问 |
|
||
| `DIAGNOSIS_REQUIRED` | 提交治疗前需要先提交诊断 |
|
||
| `TREATMENT_REQUIRED` | 生成评价前需要先提交治疗 |
|
||
| `ORDER_ITEM_NOT_FOUND` | 检查项目不存在 |
|
||
| `LLM_CALL_TIMEOUT` | LLM 普通调用超时 |
|
||
| `LLM_STREAM_TIMEOUT` | LLM 流式调用超时 |
|
||
| `LLM_STREAM_FAILED` | LLM 流式调用失败 |
|
||
| `CASE_SQL_FILE_INVALID` | 上传文件不是 `.sql` |
|
||
| `CASE_SQL_FILE_EMPTY` | 上传 SQL 文件为空 |
|
||
| `CASE_SQL_FILE_TOO_LARGE` | 上传 SQL 文件超过 5MB |
|
||
| `CASE_SQL_IMPORT_INVALID` | SQL 解析或字段映射校验失败 |
|
||
|
||
## 2. Agent Hello
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `GET` |
|
||
| Path | `/agent/hello` |
|
||
| Router | `agent.hello` |
|
||
| 用途 | 校验后端连接，返回当前用户上下文和功能开关 |
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"user": {
|
||
"user_id": "demo_user_001",
|
||
"tenant_id": null,
|
||
"role": null
|
||
},
|
||
"features": {
|
||
"stream_chat": true,
|
||
"score_types": ["percentage", "five_point"],
|
||
"pdf_export": true,
|
||
"knowledge_search": true,
|
||
"llm_mock_enabled": false,
|
||
"llm_fallback_to_mock": false
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3. 病例列表
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `GET` |
|
||
| Path | `/cases` |
|
||
| Router | `cases.list_cases` |
|
||
| Service | `CaseService.list_cases` |
|
||
| 表 | `case_base` |
|
||
|
||
Query：
|
||
|
||
| 参数 | 说明 |
|
||
|---|---|
|
||
| `department_id` | 科室筛选 |
|
||
| `training_type` | 训练类型筛选 |
|
||
| `mode` | `practice` 或 `teaching` |
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"id": 1,
|
||
"title": "支气管肺炎 - 6岁男性患儿",
|
||
"department_id": 1,
|
||
"department_name": "儿科",
|
||
"difficulty": "medium",
|
||
"chief_complaint": "发热、咳嗽4天，喘息1天。",
|
||
"patient_age": 6,
|
||
"patient_gender": "male",
|
||
"training_type": "case_analysis",
|
||
"supported_modes": ["practice", "teaching"],
|
||
"has_teaching_video": false,
|
||
"has_knowledge_points": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 4. 病例详情
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `GET` |
|
||
| Path | `/cases/{case_id}` |
|
||
| Router | `cases.get_case_detail` |
|
||
| Service | `CaseService.get_case_detail` |
|
||
| 表 | `case_base`、`traditional_case`、`teaching_case`、`case_exam_item` |
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"title": "支气管肺炎 - 6岁男性患儿",
|
||
"department_name": "儿科",
|
||
"chief_complaint": "发热、咳嗽4天，喘息1天。",
|
||
"patient_age": 6,
|
||
"patient_gender": "male",
|
||
"supported_modes": ["practice", "teaching"],
|
||
"exam_item_count": 5,
|
||
"has_knowledge_points": true
|
||
}
|
||
```
|
||
|
||
病例详情不返回标准答案、隐藏病史和完整评分细则。
|
||
|
||
## 5. 创建训练会话
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `POST` |
|
||
| Path | `/sessions` |
|
||
| Router | `sessions.create_session` |
|
||
| Service | `SessionService.create_session` |
|
||
| 表 | `training_session` |
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"case_id": 1,
|
||
"training_type": "case_analysis",
|
||
"mode": "practice",
|
||
"score_type": "percentage"
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"session_id": 10,
|
||
"session_code": "sess_20260528100000_abcd1234",
|
||
"status": "inquiry",
|
||
"patient_opening": "家长：医生，孩子发烧咳嗽好几天了..."
|
||
}
|
||
```
|
||
|
||
校验：
|
||
|
||
- `case_id` 必须存在并启用。
|
||
- `mode` 当前使用 `practice` 或 `teaching`。
|
||
- 创建会话时初始化短期 memory。
|
||
|
||
## 6. 普通问诊
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `POST` |
|
||
| Path | `/sessions/{session_id}/chat` |
|
||
| Router | `sessions.chat` |
|
||
| Service | `SessionService.chat` |
|
||
| Agent | `PatientAgent.reply` |
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"message": "孩子发热几天了？最高体温多少？"
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"reply": "发热有4天了，最高烧到39度多。",
|
||
"latency_ms": 2500,
|
||
"model": "deepseek-v4-pro",
|
||
"fallback_used": false
|
||
}
|
||
```
|
||
|
||
校验：会话必须属于当前 `X-User-Id`，且状态为 `inquiry`。
|
||
|
||
## 7. 流式问诊
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `POST` |
|
||
| Path | `/sessions/{session_id}/chat/stream` |
|
||
| Router | `sessions.chat_stream` |
|
||
| Service | `SessionService.stream_chat` |
|
||
| Agent | `PatientAgent.stream_reply` |
|
||
|
||
Request 同普通问诊。
|
||
|
||
SSE 事件：
|
||
|
||
```text
|
||
event: message_delta
|
||
data: {"delta":"发热有"}
|
||
|
||
event: message_done
|
||
data: {"latency_ms":3200,"first_token_ms":800,"model":"deepseek-v4-pro","fallback_used":false}
|
||
|
||
event: error
|
||
data: {"code":"LLM_STREAM_TIMEOUT","message":"AI 病人回复超时，请重试"}
|
||
```
|
||
|
||
前端收到 `message_done` 或 `error` 后必须结束 pending。
|
||
|
||
## 8. 查看提示
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `POST` |
|
||
| Path | `/sessions/{session_id}/hints` |
|
||
| Router | `sessions.generate_hints` |
|
||
| Service | `SessionService.generate_hints` |
|
||
| Agent | `HintAgent.generate` |
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"last_user_message": "孩子发热几天了？",
|
||
"scope": "current_conversation"
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"hints": ["可以继续追问最高体温、热型和退热药反应。"],
|
||
"missing_dimensions": ["既往史", "严重程度评估"],
|
||
"next_questions": ["孩子以前有没有喘息或哮喘史？"],
|
||
"recommended_orders": [
|
||
{"item_code": "oxygen_saturation", "reason": "用于判断缺氧和病情严重程度"}
|
||
]
|
||
}
|
||
```
|
||
|
||
校验：当前仅允许 `practice` 模式且会话状态为 `inquiry`。
|
||
|
||
## 9. 检查项目列表
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `GET` |
|
||
| Path | `/sessions/{session_id}/order-items` |
|
||
| Router | `sessions.list_order_items` |
|
||
| Service | `OrderService.list_order_items` |
|
||
| 表 | `case_exam_item` |
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"item_code": "complete_blood_count",
|
||
"item_name": "血常规",
|
||
"item_type": "lab",
|
||
"category": "实验室检查",
|
||
"ordered": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 10. 申请检查
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `POST` |
|
||
| Path | `/sessions/{session_id}/orders` |
|
||
| Router | `sessions.create_order` |
|
||
| Service | `OrderService.create_order` |
|
||
| 表 | `training_order` |
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"item_code": "complete_blood_count"
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"order_id": 1,
|
||
"item_code": "complete_blood_count",
|
||
"item_name": "血常规",
|
||
"result_text": "WBC 12.4×10^9/L，中性粒细胞72%。",
|
||
"result_structured": {},
|
||
"already_ordered": false,
|
||
"context_written": true
|
||
}
|
||
```
|
||
|
||
同一 `session_id + item_code` 幂等，重复申请返回已有记录，不重复写入 memory。
|
||
|
||
## 11. 完成问诊
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `POST` |
|
||
| Path | `/sessions/{session_id}/complete-inquiry` |
|
||
| Router | `sessions.complete_inquiry` |
|
||
| Service | `SessionService.complete_inquiry` |
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"session_id": 10,
|
||
"status": "diagnosis"
|
||
}
|
||
```
|
||
|
||
校验：至少存在一轮医生提问。
|
||
|
||
## 12. 提交诊断
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `POST` |
|
||
| Path | `/sessions/{session_id}/diagnosis` |
|
||
| Router | `sessions.submit_diagnosis` |
|
||
| Service | `SessionService.submit_diagnosis` |
|
||
| 表 | `training_submission` |
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"primary_diagnosis": "支气管肺炎",
|
||
"differential_diagnoses": ["毛细支气管炎", "哮喘急性发作"],
|
||
"diagnosis_basis": "发热、咳嗽、喘息，结合肺部体征、炎症指标、胸片和血氧情况。"
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"status": "treatment"
|
||
}
|
||
```
|
||
|
||
## 13. 提交治疗
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `POST` |
|
||
| Path | `/sessions/{session_id}/treatment` |
|
||
| Router | `sessions.submit_treatment` |
|
||
| Service | `SessionService.submit_treatment` |
|
||
| 表 | `training_submission` |
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"treatment_principle": "抗感染、平喘、改善氧合、严密观察。",
|
||
"treatment_measures": "根据病情选择抗感染治疗，必要时雾化吸入，监测体温、呼吸和血氧。",
|
||
"risk_plan": "关注低氧、呼吸困难加重、持续高热、精神反应差。",
|
||
"communication": "向家属说明病情、用药注意事项和复诊/住院指征。",
|
||
"follow_up": "治疗后复查体温、呼吸、血氧和炎症指标。"
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"status": "evaluating"
|
||
}
|
||
```
|
||
|
||
## 14. 生成评价
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `POST` |
|
||
| Path | `/sessions/{session_id}/evaluation` |
|
||
| Router | `sessions.create_evaluation` |
|
||
| Service | `EvaluationService.create_evaluation` |
|
||
| Agent | `ScoringAgent.score`、`ReportAgent` |
|
||
| 表 | `scoring_rule`、`knowledge_chunks`、`training_record` |
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"score_type": "percentage"
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"evaluation_id": 1,
|
||
"score_type": "percentage",
|
||
"total_score": 82,
|
||
"dimension_scores": [],
|
||
"errors": [],
|
||
"improvement_plan": [],
|
||
"evidence_summary": [],
|
||
"guideline_refs": [],
|
||
"overall_comment": "完成了主要诊断链路，但检查利用和沟通细节仍需加强。"
|
||
}
|
||
```
|
||
|
||
评价完成后释放短期 memory，并写入 `training_record`。
|
||
|
||
## 15. 历史评价列表
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `GET` |
|
||
| Path | `/evaluations` |
|
||
| Router | `evaluations.list_evaluations` |
|
||
| Service | `EvaluationService.list_history` |
|
||
| 表 | `training_record` |
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"evaluation_id": 1,
|
||
"case_title": "支气管肺炎 - 6岁男性患儿",
|
||
"score_type": "percentage",
|
||
"total_score": 82,
|
||
"created_at": "2026-05-28T10:00:00",
|
||
"pdf_exported": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 16. 评价详情
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `GET` |
|
||
| Path | `/evaluations/{evaluation_id}` |
|
||
| Router | `evaluations.get_evaluation_detail` |
|
||
| Service | `EvaluationService.get_detail` |
|
||
| 表 | `training_record` |
|
||
|
||
Response `data` 为完整评价报告，并包含 `session_id`、`case_id`、`case_title`、`created_at`、`pdf_file_path`。
|
||
|
||
## 17. 导出 PDF
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `POST` |
|
||
| Path | `/evaluations/{evaluation_id}/export-pdf` |
|
||
| Router | `evaluations.export_pdf` |
|
||
| Service | `PdfExportService.export` |
|
||
| 表 | `training_record` |
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"export_id": 1,
|
||
"file_path": "storage/reports/training_record_1_percentage_xxx.pdf"
|
||
}
|
||
```
|
||
|
||
## 18. 知识检索
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `GET` |
|
||
| Path | `/knowledge/search` |
|
||
| Router | `knowledge.search_knowledge` |
|
||
| Service | `KnowledgeService.search_guidelines` |
|
||
| 表 | `knowledge_sources`、`knowledge_documents`、`knowledge_chunks` |
|
||
|
||
Query：
|
||
|
||
| 参数 | 说明 |
|
||
|---|---|
|
||
| `department_id` | 科室 ID |
|
||
| `training_type` | 训练类型 |
|
||
| `q` | 关键词，逗号分隔 |
|
||
|
||
用途：评价生成前检索科室/类型下的评分指南。前端第一版不需要主动调用。
|
||
|
||
## 19. 病例 SQL 导入预检
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `POST` |
|
||
| Path | `/imports/case-sql/preview` |
|
||
| Router | `imports.preview_case_sql` |
|
||
| Service | `CaseSqlImportService.preview` |
|
||
| 用途 | 前端上传接口解析后的 SQL 文件，后端只解析并校验，不写入数据库 |
|
||
|
||
Request：
|
||
|
||
```text
|
||
Content-Type: multipart/form-data
|
||
file: case.sql
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"file_name": "case.sql",
|
||
"encoding": "utf-8",
|
||
"tables": {
|
||
"case_base": 1,
|
||
"traditional_case": 1,
|
||
"teaching_case": 1,
|
||
"scoring_rule": 5
|
||
},
|
||
"can_import": true,
|
||
"warnings": [],
|
||
"errors": [],
|
||
"preview_cases": [
|
||
{
|
||
"id": 1001,
|
||
"title": "儿童支气管肺炎",
|
||
"case_type": "diagnosis_treatment",
|
||
"difficulty": "medium"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
校验逻辑：
|
||
- 必须携带 `X-User-Id`。
|
||
- 文件后缀必须为 `.sql`，大小不超过 5MB。
|
||
- 只解析源 SQL 中的 `case_base`、`traditional_case`、`teaching_case`、`scoring_rule`。
|
||
- 预检接口不执行源 SQL，不写入数据库。
|
||
- 源 SQL 中出现 `DROP TABLE`、`CREATE TABLE`、`ALTER TABLE` 等语句时只作为警告展示，导入器不会执行这些语句。
|
||
- 字段数量不匹配、非法字符串、JSON 字段非法时返回 `can_import=false` 和 `errors`。
|
||
|
||
## 20. 病例 SQL 确认导入
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `POST` |
|
||
| Path | `/imports/case-sql/apply` |
|
||
| Router | `imports.apply_case_sql` |
|
||
| Service | `CaseSqlImportService.apply` |
|
||
| 用途 | 预检通过后，将 SQL 中的病例源表数据映射写入当前数据库 |
|
||
| 表 | `case_base`、`traditional_case`、`teaching_case`、`scoring_rule`、`case_exam_item` |
|
||
|
||
Request：
|
||
|
||
```text
|
||
Content-Type: multipart/form-data
|
||
file: case.sql
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"imported": true,
|
||
"file_name": "case.sql",
|
||
"encoding": "utf-8",
|
||
"inserted_or_updated_cases": 1,
|
||
"imported_traditional_cases": 1,
|
||
"imported_teaching_cases": 1,
|
||
"imported_scoring_rules": 5,
|
||
"generated_exam_items": 4,
|
||
"warnings": []
|
||
}
|
||
```
|
||
|
||
校验逻辑：
|
||
- 必须携带 `X-User-Id`。
|
||
- 导入过程使用事务，任意表映射失败则整体回滚。
|
||
- `case_base` 按 `id` 更新或插入。
|
||
- `traditional_case` 和 `teaching_case` 按 `case_id` 更新或插入。
|
||
- `scoring_rule` 按 `case_id` 先删除旧规则再写入源规则。
|
||
- 源 SQL 缺少 `case_exam_item` 时，由后端根据病例文本生成基础检查项目，保障问诊训练链路可继续使用。
|
||
- 导入成功后前端刷新 `/cases`，新增病例即可进入训练。
|
||
|
||
## 21. LLM Fast 测试
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `POST` |
|
||
| Path | `/llm/test/deepseek-fast` |
|
||
| Router | `llm_test.test_deepseek_fast` |
|
||
| Service | `OpenAICompatibleLLMClient.chat` |
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"message": "请用一句话说明医疗问诊训练 Demo 的用途。"
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"model": "deepseek-v4-pro",
|
||
"first_token_ms": null,
|
||
"total_latency_ms": 3000,
|
||
"stream": false,
|
||
"mock_mode": false,
|
||
"fallback_used": false,
|
||
"thinking_enabled": false,
|
||
"reasoning_effort": null
|
||
}
|
||
```
|
||
|
||
## 22. LLM Reason 测试
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Method | `POST` |
|
||
| Path | `/llm/test/deepseek-reason` |
|
||
| Router | `llm_test.test_deepseek_reason` |
|
||
| Service | `OpenAICompatibleLLMClient.stream_chat`，流式不兼容时降级到 `chat` |
|
||
|
||
Request 同 Fast 测试。Response 字段同 Fast 测试。
|