Liu_JB/fastapi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: finalize backend feature scope

Browse Source
This commit is contained in:
刘金宝
2026-06-11 16:19:07 +08:00
parent d855ecab82
commit ec515d5453
43 changed files with 680 additions and 712 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/03_api_design.md
+57 -11
View File
@@ -1,6 +1,6 @@
# 医疗问诊 Agent API 文档
本文档面向前端联调，描述当前 FastAPI 后端可调用接口。训练模式和教学互动模式按页面模块分开书写；即使底层复用同一路由，文档中也在对应模块下分别列出，便于前端按页面开发。
本文档面向前端开发调用，描述当前 FastAPI 后端可调用接口。训练模式和教学互动模式按页面模块分开书写；即使底层复用同一路由，文档中也在对应模块下分别列出，便于前端按页面开发。
公网基础地址：
@@ -91,14 +91,11 @@ curl -X GET "http://8.160.178.88/fastapi/api/v1/auth/me" \
}
```
## 3. 病例基础接口
## 3. 病例 ID 说明
| 接口名称 | url | api | methods | params（入参） | response（返回参数） |
|---|---|---|---|---|---|
| 病例列表 | `http://8.160.178.88/fastapi/api/v1/cases` | `/api/v1/cases` | `GET` | Query：`department_id` 选填，科室 ID；`training_type` 选填，训练类型；`mode` 选填，交互模式 | `data.items[]` 病例列表，包含 `case_id`、`title`、`department_name`、`difficulty`、`chief_complaint` 等 |
| 病例详情 | `http://8.160.178.88/fastapi/api/v1/cases/{case_id}` | `/api/v1/cases/{case_id}` | `GET` | Path：`case_id` 必填，病例 ID | `data.case_id` 病例 ID；`data.title` 病例标题；`data.chief_complaint` 主诉；`data.supported_modes` 支持模式；`data.exam_item_types` 可用检查类型 |
当前 FastAPI 后端不提供病例公开查询接口。训练页面和教学互动页面需要使用的 `case_id` 由页面上下文传入，后端在各业务接口内部读取 `case_base`、`traditional_case`、`teaching_case` 和 `case_exam_item` 完成校验和业务处理。
说明：病例接口只读平台数据库中的已发布病例，不提供病例新增、删除、PDF 解析接口。
病例、教学题、检查项和评分规则由平台数据库维护。FastAPI 不提供病例新增、删除、PDF 解析入库接口。
## 4. 训练模式 API
@@ -124,7 +121,7 @@ curl -X GET "http://8.160.178.88/fastapi/api/v1/auth/me" \
| 接口名称 | url | api | methods | params（入参） | response（返回参数） |
|---|---|---|---|---|---|
| 新建会话 | `http://8.160.178.88/fastapi/api/v1/sessions` | `/api/v1/sessions` | `POST` | Body：`case_id` 必填，病例 ID；`training_type` 必填，当前使用 `diagnosis_treatment`；`mode` 必填，当前训练模式使用 `practice`，兼容旧值 `novice`；`score_type` 必填，`percentage` 或 `five_point`；`patient_config` 选填，病人初始化配置 | `data.session_id` 会话 ID；`data.session_code` 会话编码；`data.status` 当前阶段；`data.patient_opening` AI 病人开场白；`data.patient_config` 实际使用配置 |
| 新建会话 | `http://8.160.178.88/fastapi/api/v1/sessions` | `/api/v1/sessions` | `POST` | Body：`case_id` 必填，病例 ID；`training_type` 必填，当前使用 `diagnosis_treatment`；`mode` 必填，当前训练模式使用 `practice`；`score_type` 必填，`percentage` 或 `five_point`；`patient_config` 选填，病人初始化配置 | `data.session_id` 会话 ID；`data.session_code` 会话编码；`data.status` 当前阶段；`data.patient_opening` AI 病人开场白；`data.patient_config` 实际使用配置 |
请求示例：
@@ -367,13 +364,44 @@ async function downloadTeachingPdf(baseUrl: string, token: string, evaluationId:
## 7. AI 学习助手 API
该接口用于普通用户医学知识问答。后端优先检索本机构知识库；如果机构知识库未初始化、Milvus / embedding 暂不可用或未命中来源，接口仍会继续调用 LLM，回答开头会声明“未检索到本机构知识库参考，以下为大模型通用学习回答”。
该模块用于普通用户医学知识问答。前端点击 AI 学习助手入口后，先创建短期会话，再使用会话式 SSE 接口问答。后端优先检索本机构知识库；如果机构知识库未初始化、Milvus / embedding 暂不可用或未命中来源，接口仍会继续调用 LLM，回答开头会声明“未检索到本机构知识库参考，以下为大模型通用学习回答”。
学习助手会话保存在 Redis 短期缓存中，默认 TTL 为 `7200` 秒；该会话只用于当前学习问答上下文，不写入训练记录。
| 接口名称 | url | api | methods | params（入参） | response（返回参数） |
|---|---|---|---|---|---|
| AI 学习助手流式问答 | `http://8.160.178.88/fastapi/api/v1/learning-assistant/chat/stream` | `/api/v1/learning-assistant/chat/stream` | `POST` | Body：`question` 必填，1-1000 字；`top_k` 选填，1-10；`score_threshold` 选填，0-1 | SSE：`retrieval_done` 检索状态；`answer_delta` 回答增量；`answer_done` 完成事件；`error` 错误事件 |
| AI 学习助手新建会话 | `http://8.160.178.88/fastapi/api/v1/learning-assistant/sessions` | `/api/v1/learning-assistant/sessions` | `POST` | Header：`Authorization` 必填，`Bearer <access_token>`；`X-Entry-Scene` 建议填。Body：`title` 选填，会话标题，最大 100 字 | `data.assistant_session_id` 学习助手会话 ID；`data.user_id` 当前用户 ID；`data.institution_id` 当前机构 ID；`data.institution_name` 当前机构名称；`data.title` 会话标题；`data.status` 会话状态；`data.expires_in_seconds` 会话过期时间 |
| AI 学习助手会话式流式问答 | `http://8.160.178.88/fastapi/api/v1/learning-assistant/sessions/{assistant_session_id}/chat/stream` | `/api/v1/learning-assistant/sessions/{assistant_session_id}/chat/stream` | `POST` | Path：`assistant_session_id` 必填，新建会话接口返回。Body：`question` 必填，1-1000 字；`top_k` 选填，1-10，默认使用后端配置；`score_threshold` 选填，0-1，默认使用后端配置 | SSE：`session_ready` 会话就绪；`retrieval_done` 检索状态和来源；`answer_delta` 回答增量；`answer_done` 完成事件；`error` 错误事件 |
请求示例：
新建会话请求示例：
```json
{
"title": "儿科肺炎知识复习"
}
```
新建会话返回示例：
```json
{
"code": "OK",
"message": "success",
"data": {
"assistant_session_id": "las_2e2f4a6b8d4b4f0ba31731a814c1c5b8",
"user_id": "37",
"institution_id": 1,
"institution_name": "某医院",
"title": "儿科肺炎知识复习",
"status": "active",
"created_at": "2026-06-11T12:00:00Z",
"updated_at": "2026-06-11T12:00:00Z",
"expires_in_seconds": 7200
}
}
```
会话式流式问答请求示例：
```json
{
@@ -383,6 +411,22 @@ async function downloadTeachingPdf(baseUrl: string, token: string, evaluationId:
}
```
会话式 SSE 返回示例：
```text
event: session_ready
data: {"assistant_session_id":"las_xxx","status":"active","history_count":0}
event: retrieval_done
data: {"assistant_session_id":"las_xxx","retrieval_hit":true,"sources":[{"document_id":1,"document_title":"诊断学","file_name":"诊断学.pdf","page_start":12,"page_end":12,"chunk_uid":"chunk_001","score":0.82,"quote":"..."}],"retrieval_error":null}
event: answer_delta
data: {"assistant_session_id":"las_xxx","delta":"支气管肺炎常见表现包括..."}
event: answer_done
data: {"assistant_session_id":"las_xxx","model":"deepseek-chat","total_latency_ms":1800,"llm_latency_ms":1600}
```
## 8. 内容管理员知识库 API
该组接口是后台内容管理员能力，学生端不展示上传入口。当前阶段保留接口和数据结构，后续生产环境接入完整 PDF 解析、分片、embedding、Milvus 构建和异步任务。
@@ -414,5 +458,7 @@ async function downloadTeachingPdf(baseUrl: string, token: string, evaluationId:
| 404 | `ORDER_ITEM_NOT_FOUND` | 当前病例不存在该检查项 |
| 400 | `ORDER_ITEM_TYPE_MISMATCH` | 体格检查 / 辅助检查接口与检查项类型不匹配 |
| 404 | `EVALUATION_NOT_FOUND` | 评价不存在或不属于当前用户 |
| 404 | `LEARNING_ASSISTANT_SESSION_NOT_FOUND` | AI 学习助手会话不存在、已过期或不属于当前用户 |
| 400 | `LEARNING_ASSISTANT_SESSION_INVALID` | AI 学习助手会话状态不可用 |
| 502 | `LLM_STREAM_FAILED` | LLM 流式调用失败 |
| 503 | `AUTH_USER_CENTER_UNAVAILABLE` | Django 用户中心超时或不可达 |