刘金宝
810 lines
20 KiB
Markdown
810 lines
20 KiB
Markdown
# 前端 API 对接文档
|
||
|
||
本文档面向 Vue 前端与后续正式前端开发，描述当前第一版 Demo 已实现的后端接口、请求头、状态流转、字段结构和错误处理规则。
|
||
|
||
## 1. 通用约定
|
||
|
||
### 1.1 Base URL
|
||
|
||
本地开发默认地址：
|
||
|
||
```text
|
||
http://127.0.0.1:8000/api/v1
|
||
```
|
||
|
||
前端默认配置：
|
||
|
||
```text
|
||
Vite dev server: http://127.0.0.1:5173
|
||
API base: http://127.0.0.1:8000/api/v1
|
||
```
|
||
|
||
### 1.2 必传 Header
|
||
|
||
所有业务接口都必须携带以下 Header：
|
||
|
||
| Header | 类型 | 说明 |
|
||
|---|---:|---|
|
||
| `X-User-Id` | string | 宿主系统传入的用户标识。后端按该字段隔离会话、提交、评价和历史记录。 |
|
||
| `X-Entry-Scene` | string | 入口场景。Demo 前端默认 `vue_demo`。 |
|
||
|
||
可选 Header：
|
||
|
||
| Header | 类型 | 说明 |
|
||
|---|---:|---|
|
||
| `X-Tenant-Id` | string | 租户、机构或项目 ID。第一版只透传和审计。 |
|
||
| `X-User-Role` | string | 用户角色。第一版只透传和审计。 |
|
||
| `X-Class-Id` | string | 班级或课程 ID。第一版只透传和审计。 |
|
||
| `X-Request-Id` | string | 请求链路 ID。前端有链路追踪需求时传入。 |
|
||
|
||
### 1.3 统一响应结构
|
||
|
||
除 SSE 流式接口外，后端统一返回：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
前端处理规则：
|
||
|
||
- `code === "OK"`：读取 `data`。
|
||
- `code !== "OK"`：展示 `message`，不要直接展示底层异常。
|
||
- HTTP 401 通常表示缺少 `X-User-Id`。
|
||
- HTTP 404 通常表示资源不存在或不属于当前 `user_id`。
|
||
- HTTP 400 通常表示当前状态不允许操作或入参不合法。
|
||
|
||
### 1.4 常见错误码
|
||
|
||
| code | 场景 | 前端处理 |
|
||
|---|---|---|
|
||
| `USER_ID_REQUIRED` | 缺少 `X-User-Id` | 回到入口设置页，提示填写 user_id。 |
|
||
| `CASE_NOT_FOUND` | 病例不存在、未启用或已删除 | 刷新病例列表。 |
|
||
| `CASE_DELETE_CONFIRM_REQUIRED` | 删除病例未传 `confirm=true` | 保持确认弹窗，不执行删除。 |
|
||
| `CASE_DELETE_TRAINING_DATA_EXISTS` | 病例存在训练数据但未允许删除训练数据 | 当前前端固定传 `delete_training_data=true`。 |
|
||
| `SESSION_NOT_FOUND` | 会话不存在或不属于当前用户 | 回到病例页重新创建会话。 |
|
||
| `SESSION_STATUS_INVALID` | 当前阶段不允许执行该操作 | 根据 `status` 禁用按钮并提示原因。 |
|
||
| `INQUIRY_REQUIRED` | 完成问诊前没有医生提问 | 提示至少完成一轮问诊。 |
|
||
| `DIAGNOSIS_REQUIRED` | 提交治疗前未提交诊断 | 引导到诊断表单。 |
|
||
| `TREATMENT_REQUIRED` | 生成评价前未提交治疗 | 引导到治疗表单。 |
|
||
| `ORDER_ITEM_NOT_FOUND` | 检查项不存在 | 刷新检查项列表。 |
|
||
| `LLM_CALL_TIMEOUT` | 非流式模型调用超时 | 提示重试。 |
|
||
| `LLM_STREAM_TIMEOUT` | 流式模型调用超时 | 结束 pending，提示重试或关闭流式。 |
|
||
| `LLM_STREAM_FAILED` | 流式模型调用失败 | 结束 pending，提示模型服务异常。 |
|
||
| `CASE_SQL_FILE_INVALID` | 上传文件不是 `.sql` | 提示选择 SQL 文件。 |
|
||
| `CASE_SQL_FILE_EMPTY` | SQL 文件为空 | 提示重新导出文件。 |
|
||
| `CASE_SQL_FILE_TOO_LARGE` | 文件超过 5MB | 提示压缩或拆分。 |
|
||
| `CASE_SQL_IMPORT_INVALID` | SQL 解析或字段映射失败 | 展示 `errors`，不允许确认导入。 |
|
||
|
||
## 2. 前端主流程
|
||
|
||
```text
|
||
入口页
|
||
-> GET /agent/hello
|
||
病例页
|
||
-> GET /cases
|
||
-> GET /cases/{case_id}
|
||
-> GET /cases/{case_id}/delete-preview
|
||
-> DELETE /cases/{case_id}
|
||
训练配置页
|
||
-> POST /sessions
|
||
Chat 页
|
||
-> POST /sessions/{session_id}/chat 或 /chat/stream
|
||
-> POST /sessions/{session_id}/hints
|
||
-> GET /sessions/{session_id}/order-items
|
||
-> POST /sessions/{session_id}/orders
|
||
提交页
|
||
-> POST /sessions/{session_id}/complete-inquiry
|
||
-> POST /sessions/{session_id}/diagnosis
|
||
-> POST /sessions/{session_id}/treatment
|
||
报告页
|
||
-> POST /sessions/{session_id}/evaluation
|
||
-> POST /evaluations/{evaluation_id}/export-pdf
|
||
历史页
|
||
-> GET /evaluations
|
||
-> GET /evaluations/{evaluation_id}
|
||
导入页
|
||
-> POST /imports/case-sql/preview
|
||
-> POST /imports/case-sql/apply
|
||
LLM 测试页
|
||
-> POST /llm/test/deepseek-fast
|
||
-> POST /llm/test/deepseek-reason
|
||
```
|
||
|
||
训练会话状态流转：
|
||
|
||
```text
|
||
inquiry -> diagnosis -> treatment -> evaluating -> evaluated
|
||
```
|
||
|
||
前端按钮启用规则：
|
||
|
||
| 阶段 | 允许操作 |
|
||
---|---|
|
||
| `inquiry` | 问诊、查看提示、申请检查、完成问诊 |
|
||
| `diagnosis` | 提交诊断 |
|
||
| `treatment` | 提交治疗方案 |
|
||
| `evaluating` | 生成评价报告 |
|
||
| `evaluated` | 查看报告、导出 PDF、查看历史 |
|
||
|
||
## 3. Agent Hello
|
||
|
||
### `GET /agent/hello`
|
||
|
||
用途：检查后端连接，返回当前用户上下文和 Demo 能力开关。
|
||
|
||
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_mode": "real",
|
||
"llm_fallback_to_mock": false,
|
||
"llm_fast_model": "deepseek-v4-pro",
|
||
"llm_reason_model": "deepseek-v4-pro",
|
||
"runtime_memory_backend": "redis"
|
||
}
|
||
}
|
||
```
|
||
|
||
前端展示说明：
|
||
|
||
- `stream_chat`：是否支持 SSE 流式问诊。
|
||
- `score_types`：评分输出类型，`percentage` 为百分制，`five_point` 为五分制。
|
||
- `pdf_export`：是否支持 PDF 导出。
|
||
- `knowledge_search`：是否已接入评分参考指南检索。
|
||
- `llm_mock_enabled`：是否强制使用 mock 模型。
|
||
- `llm_fallback_to_mock`：真实模型失败时是否回退 mock。
|
||
- `runtime_memory_backend`：短期记忆后端，通常为 `redis` 或 `memory`。
|
||
|
||
## 4. 病例接口
|
||
|
||
### `GET /cases`
|
||
|
||
用途：获取病例列表。不会返回标准答案、隐藏病史、评分细则。
|
||
|
||
Query：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---:|---:|---|
|
||
| `department_id` | number | 否 | 科室筛选。 |
|
||
| `training_type` | string | 否 | 训练类别筛选：`case_analysis`、`diagnosis_treatment`、`consultation`。 |
|
||
| `mode` | string | 否 | 模式筛选：`practice`、`teaching`。 |
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"id": 2,
|
||
"case_code": "SRC_2",
|
||
"department_id": 1,
|
||
"title": "支气管肺炎 - 6岁男性患儿",
|
||
"difficulty": "medium",
|
||
"chief_complaint": "发热、咳嗽4天，喘息1天。",
|
||
"supported_training_type": "diagnosis_treatment",
|
||
"supported_mode": "free_chat",
|
||
"has_teaching_video": false,
|
||
"has_knowledge_points": true,
|
||
"has_quiz": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### `GET /cases/{case_id}`
|
||
|
||
用途：获取病例训练入口详情。不会返回标准诊断、标准治疗、隐藏病史。
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"id": 2,
|
||
"case_code": "SRC_2",
|
||
"title": "支气管肺炎 - 6岁男性患儿",
|
||
"department": "儿科",
|
||
"difficulty": "medium",
|
||
"patient": {
|
||
"name": null,
|
||
"age": 6,
|
||
"gender": "male",
|
||
"occupation": null
|
||
},
|
||
"chief_complaint": "发热、咳嗽4天，喘息1天。",
|
||
"supported_training_type": "diagnosis_treatment",
|
||
"supported_mode": "free_chat",
|
||
"has_teaching_video": false,
|
||
"has_knowledge_points": true,
|
||
"has_quiz": false,
|
||
"order_item_types": ["lab", "imaging", "vital_sign"]
|
||
}
|
||
```
|
||
|
||
### `GET /cases/{case_id}/delete-preview`
|
||
|
||
用途：删除病例前统计影响范围。前端删除弹窗先调用该接口。
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"case_id": 2,
|
||
"case_title": "支气管肺炎 - 6岁男性患儿",
|
||
"can_delete": true,
|
||
"affected": {
|
||
"case_base": 1,
|
||
"traditional_case": 1,
|
||
"teaching_case": 0,
|
||
"scoring_rule": 1,
|
||
"case_exam_item": 6,
|
||
"training_session": 1,
|
||
"training_order": 6,
|
||
"training_submission": 1,
|
||
"training_record": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### `DELETE /cases/{case_id}`
|
||
|
||
用途：确认后删除病例及关联业务数据。审计日志只记录删除行为，不反删。
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"confirm": true,
|
||
"delete_training_data": true
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"deleted": true,
|
||
"case_id": 2,
|
||
"deleted_counts": {
|
||
"training_order": 6,
|
||
"training_submission": 1,
|
||
"training_record": 1,
|
||
"training_session": 1,
|
||
"case_exam_item": 6,
|
||
"scoring_rule": 1,
|
||
"traditional_case": 1,
|
||
"teaching_case": 0,
|
||
"case_base": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
前端交互规则：
|
||
|
||
- 删除按钮只放在病例详情区，不放在病例卡片上。
|
||
- 点击删除后先调用 `delete-preview`。
|
||
- 弹窗展示 `affected`。
|
||
- 用户输入固定确认文案后再调用 `DELETE`。
|
||
- 删除成功后清空当前病例、会话、检查结果、报告缓存，并刷新 `/cases`。
|
||
|
||
## 5. 会话与问诊接口
|
||
|
||
### `POST /sessions`
|
||
|
||
用途：创建训练会话，初始化短期 memory。
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"case_id": 2,
|
||
"training_type": "diagnosis_treatment",
|
||
"mode": "practice",
|
||
"score_type": "percentage"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 允许值 | 说明 |
|
||
|---|---|---|
|
||
| `training_type` | `case_analysis`、`diagnosis_treatment`、`consultation` | 训练类别。 |
|
||
| `mode` | `practice`、`teaching` | 训练模式。后端兼容旧值 `novice`，会归一为 `practice`。 |
|
||
| `score_type` | `percentage`、`five_point` | 评分输出类型。 |
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"session_id": 10,
|
||
"session_code": "sess_20260528100000_abcd1234",
|
||
"status": "inquiry",
|
||
"patient_opening": "家长：医生，孩子发热咳嗽好几天了，昨天开始喘得厉害，精神也不太好。"
|
||
}
|
||
```
|
||
|
||
### `POST /sessions/{session_id}/chat`
|
||
|
||
用途：普通非流式问诊。
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"message": "孩子发热几天了？最高体温多少？"
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"reply": "发热有4天了，最高烧到39度多，吃了退烧药能降下来，但过几个小时又会烧。",
|
||
"latency_ms": 2500,
|
||
"model": "deepseek-v4-pro",
|
||
"fallback_used": false
|
||
}
|
||
```
|
||
|
||
校验：
|
||
|
||
- 会话必须属于当前 `X-User-Id`。
|
||
- 当前状态必须为 `inquiry`。
|
||
- `message` 长度 1 到 2000。
|
||
|
||
### `POST /sessions/{session_id}/chat/stream`
|
||
|
||
用途：SSE 流式问诊。当前 Chat 页面优先使用该接口。
|
||
|
||
Request 同普通问诊。
|
||
|
||
SSE 事件：
|
||
|
||
```text
|
||
event: message_delta
|
||
data: {"delta":"发热有4天了，"}
|
||
|
||
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_delta`：追加到当前 AI 病人气泡。
|
||
- 收到 `message_done`：结束 pending，启用发送按钮。
|
||
- 收到 `error`：结束 pending，展示错误。
|
||
- fetch abort 或 reader done 但未收到 `message_done`：结束 pending，提示“AI 病人回复超时或失败，请重试”。
|
||
|
||
### `POST /sessions/{session_id}/hints`
|
||
|
||
用途：练习模式下手动生成提示。提示基于病例、当前对话和已申请检查动态生成。
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"last_user_message": "孩子发热几天了？最高体温多少？",
|
||
"scope": "current_conversation"
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"hints": [
|
||
"可以继续追问最高体温、热型和退热药反应。"
|
||
],
|
||
"missing_dimensions": [
|
||
"既往史",
|
||
"严重程度评估"
|
||
],
|
||
"next_questions": [
|
||
"孩子以前有没有喘息、哮喘或过敏史？",
|
||
"现在血氧是多少？有没有呼吸困难？"
|
||
],
|
||
"recommended_orders": [
|
||
{
|
||
"item_code": "oxygen_saturation",
|
||
"reason": "用于判断低氧和病情严重程度"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
前端处理规则：
|
||
|
||
- 提示不自动弹出。
|
||
- 只在练习模式中显示“查看提示”按钮。
|
||
- 练习模式中是否点击提示不影响评分链路。
|
||
- 教学互动模式当前不显示提示入口。
|
||
|
||
## 6. 检查/检验接口
|
||
|
||
### `GET /sessions/{session_id}/order-items`
|
||
|
||
用途：获取当前病例可申请的检查项目。只返回名称和类型，不返回检查结果。
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"item_code": "complete_blood_count",
|
||
"item_name": "血常规",
|
||
"item_type": "lab"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### `POST /sessions/{session_id}/orders`
|
||
|
||
用途：申请检查/检验，结果必须来自数据库 `case_exam_item`，不允许 LLM 编造。
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"item_code": "complete_blood_count"
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"item_code": "complete_blood_count",
|
||
"item_name": "血常规",
|
||
"item_type": "lab",
|
||
"result_text": "WBC 12.4×10^9/L，中性粒细胞72%。",
|
||
"result_structured": {},
|
||
"is_key": true,
|
||
"is_abnormal": true,
|
||
"context_written": true,
|
||
"already_ordered": false
|
||
}
|
||
```
|
||
|
||
幂等规则：
|
||
|
||
- 同一 `session_id + item_code` 只写入一次。
|
||
- 重复申请返回已有结果，`already_ordered=true`。
|
||
- 重复申请不重复写入 runtime memory。
|
||
- 前端按 `item_code` 去重展示。
|
||
|
||
## 7. 阶段提交接口
|
||
|
||
### `POST /sessions/{session_id}/complete-inquiry`
|
||
|
||
用途：完成问诊，进入诊断阶段。
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"session_id": 10,
|
||
"status": "diagnosis"
|
||
}
|
||
```
|
||
|
||
校验：至少存在一轮医生提问。
|
||
|
||
### `POST /sessions/{session_id}/diagnosis`
|
||
|
||
用途：提交诊断。
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"primary_diagnosis": "支气管肺炎",
|
||
"differential_diagnoses": ["毛细支气管炎", "支气管哮喘急性发作", "上呼吸道感染"],
|
||
"diagnosis_basis": "结合发热、咳嗽、喘息、肺部体征、炎症指标升高、胸片异常和血氧情况，符合儿童支气管肺炎表现。"
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"status": "treatment"
|
||
}
|
||
```
|
||
|
||
### `POST /sessions/{session_id}/treatment`
|
||
|
||
用途：提交治疗方案。
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"treatment_principle": "抗感染、止咳平喘、改善氧合、严密观察病情变化。",
|
||
"treatment_measures": "根据病情选择抗感染治疗，必要时雾化吸入缓解喘息，监测体温、呼吸、血氧和精神反应。",
|
||
"risk_plan": "关注低氧、呼吸困难加重、持续高热、精神反应差、脱水等情况。",
|
||
"communication": "向家属说明肺炎病情、用药注意事项、观察指标和复诊/住院指征。",
|
||
"follow_up": "治疗后复查体温、呼吸、血氧和必要炎症指标，症状加重时及时就诊。"
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"status": "evaluating"
|
||
}
|
||
```
|
||
|
||
## 8. 评价与报告接口
|
||
|
||
### `POST /sessions/{session_id}/evaluation`
|
||
|
||
用途：生成 AI 评价报告。后端读取评分规则、知识检索结果、检查申请、问诊过程和提交内容后调用 Scoring Agent。
|
||
|
||
Request：
|
||
|
||
```json
|
||
{
|
||
"score_type": "percentage"
|
||
}
|
||
```
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"evaluation_id": 1,
|
||
"score_type": "percentage",
|
||
"total_score": 82,
|
||
"dimension_scores": [
|
||
{
|
||
"dimension": "信息采集",
|
||
"score": 18,
|
||
"max_score": 25,
|
||
"comment": "已覆盖发热和咳嗽，但既往喘息史和家族过敏史追问不足。",
|
||
"evidence": ["询问发热天数和最高体温", "申请血常规和CRP"],
|
||
"deductions": ["未充分询问既往喘息史"],
|
||
"improvement": "补充既往史、过敏史、严重程度评估相关问题。"
|
||
}
|
||
],
|
||
"errors": [],
|
||
"improvement_plan": ["加强儿童肺炎严重程度评估训练。"],
|
||
"evidence_summary": ["检查结果已写入评分依据。"],
|
||
"guideline_refs": [],
|
||
"overall_comment": "诊断方向正确，检查利用和沟通细节仍需加强。"
|
||
}
|
||
```
|
||
|
||
评价完成后：
|
||
|
||
- 写入 `training_record`。
|
||
- 释放当前会话短期 memory。
|
||
- 历史记录只保存评价报告，不长期保存完整聊天记录。
|
||
|
||
### `GET /evaluations`
|
||
|
||
用途：按当前 `X-User-Id` 查询历史评价。
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"evaluation_id": 1,
|
||
"case_title": "支气管肺炎 - 6岁男性患儿",
|
||
"score_type": "percentage",
|
||
"total_score": 82,
|
||
"created_at": "2026-05-29T10:00:00",
|
||
"pdf_exported": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### `GET /evaluations/{evaluation_id}`
|
||
|
||
用途：获取评价详情。只能读取当前用户自己的评价。
|
||
|
||
Response `data`：继承评价报告字段，并额外包含：
|
||
|
||
```json
|
||
{
|
||
"session_id": 10,
|
||
"case_id": 2,
|
||
"case_title": "支气管肺炎 - 6岁男性患儿",
|
||
"created_at": "2026-05-29T10:00:00",
|
||
"pdf_file_path": "storage/reports/training_record_1_percentage_xxx.pdf"
|
||
}
|
||
```
|
||
|
||
### `POST /evaluations/{evaluation_id}/export-pdf`
|
||
|
||
用途：生成本地 PDF 报告并保存文件路径。
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"export_id": 1,
|
||
"file_path": "storage/reports/training_record_1_percentage_xxx.pdf"
|
||
}
|
||
```
|
||
|
||
## 9. 病例 SQL 导入接口
|
||
|
||
### `POST /imports/case-sql/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": 0,
|
||
"scoring_rule": 1
|
||
},
|
||
"can_import": true,
|
||
"warnings": [
|
||
"源 SQL 未包含 case_exam_item，导入器会按当前业务规则处理。"
|
||
],
|
||
"errors": [],
|
||
"preview_cases": [
|
||
{
|
||
"id": 2,
|
||
"title": "支气管肺炎 - 6岁男性患儿",
|
||
"case_type": "traditional",
|
||
"difficulty": "medium"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
规则：
|
||
|
||
- 只识别 `case_base`、`traditional_case`、`teaching_case`、`scoring_rule`。
|
||
- 不执行源 SQL 中的 `DROP TABLE`、`CREATE TABLE`、`ALTER TABLE`、`LOCK TABLES`。
|
||
- 字段数量不匹配、JSON 损坏、字符串未闭合时返回 `can_import=false`。
|
||
- `preview` 不写库。
|
||
|
||
### `POST /imports/case-sql/apply`
|
||
|
||
用途：确认导入，将 SQL 中的病例源表数据映射写入当前数据库。
|
||
|
||
Request 同预检接口。
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"imported": true,
|
||
"file_name": "case.sql",
|
||
"encoding": "utf-8",
|
||
"inserted_or_updated_cases": 1,
|
||
"imported_traditional_cases": 1,
|
||
"imported_teaching_cases": 0,
|
||
"imported_scoring_rules": 1,
|
||
"generated_exam_items": 6,
|
||
"warnings": []
|
||
}
|
||
```
|
||
|
||
前端处理：
|
||
|
||
- 先调用 `preview`，只有 `can_import=true` 才允许点击“确认导入”。
|
||
- 导入成功后刷新病例列表。
|
||
- 如果源 SQL 缺少 `case_exam_item`，后端会生成基础检查项，保证新病例可训练。
|
||
|
||
## 10. 知识检索接口
|
||
|
||
### `GET /knowledge/search`
|
||
|
||
用途：按科室、训练类别和关键词检索评分参考指南。第一版主要供评价链路和调试使用。
|
||
|
||
Query：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---:|---:|---|
|
||
| `department_id` | number | 是 | 科室 ID。 |
|
||
| `training_type` | string | 是 | 训练类别。 |
|
||
| `q` | string | 否 | 关键词，多个关键词用英文逗号分隔。 |
|
||
|
||
Response `data`：
|
||
|
||
```json
|
||
{
|
||
"matched_chunks": [],
|
||
"source_refs": [],
|
||
"no_match": true
|
||
}
|
||
```
|
||
|
||
## 11. LLM 测试接口
|
||
|
||
### `POST /llm/test/deepseek-fast`
|
||
|
||
用途：测试快速模型耗时。
|
||
|
||
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
|
||
}
|
||
```
|
||
|
||
### `POST /llm/test/deepseek-reason`
|
||
|
||
用途：测试 reason 模型耗时。接口内部会优先按配置执行，流式不兼容时降级为非流式，不影响问诊主链路。
|
||
|
||
Request 同 Fast 测试。
|
||
|
||
Response 字段同 Fast 测试。
|
||
|
||
## 12. 前端字段枚举
|
||
|
||
| 字段 | 允许值 |
|
||
|---|---|
|
||
| `score_type` | `percentage`、`five_point` |
|
||
| `mode` | `practice`、`teaching` |
|
||
| `training_type` | `case_analysis`、`diagnosis_treatment`、`consultation` |
|
||
| `session.status` | `inquiry`、`diagnosis`、`treatment`、`evaluating`、`evaluated` |
|
||
| `patient.gender` | `male`、`female`、`null` |
|
||
|
||
## 13. 前端联调注意事项
|
||
|
||
1. 所有请求必须带 `X-User-Id`，否则后端返回 `USER_ID_REQUIRED`。
|
||
2. 当前 Demo 不做登录注册，`user_id` 由宿主系统或测试页传入。
|
||
3. 病例详情不返回标准答案，避免前端泄露训练答案。
|
||
4. 检查结果只来自数据库，不来自 LLM。
|
||
5. 聊天记录只在 runtime memory 中短期保存，评价完成后释放。
|
||
6. 历史页读取的是 `training_record`，只展示完整训练结束后的评价。
|
||
7. 删除病例会级联删除该病例训练数据，前端必须保留二次确认。
|
||
8. `.env` 不进入 Git，前端不能写死 API Key。
|