刘金宝
100 lines
12 KiB
Markdown
100 lines
12 KiB
Markdown
# 功能-接口-代码-数据表映射表
|
|
|
|
本文档说明每个功能对应的 API、Router、Service、Repository、Model/数据表和关键逻辑。开发人员排查问题时优先从本表定位代码入口。
|
|
|
|
## 1. 通用调用规则
|
|
|
|
除健康检查外，业务接口都需要携带：
|
|
|
|
```http
|
|
Authorization: Bearer <access_token>
|
|
X-Entry-Scene: vue_frontend
|
|
X-Request-Id: <可选>
|
|
```
|
|
|
|
普通 JSON 接口统一返回：
|
|
|
|
```json
|
|
{
|
|
"code": "OK",
|
|
"message": "success",
|
|
"data": {}
|
|
}
|
|
```
|
|
|
|
SSE 流式接口返回 `event + data`，不包裹上述 JSON 结构。
|
|
|
|
## 2. 功能映射总表
|
|
|
|
| 功能模块 | 功能点 | API | Router | Service | Repository | Model/表 | 关键说明 |
|
|
|---|---|---|---|---|---|---|---|
|
|
| 用户鉴权 | 当前用户信息 | `GET /api/v1/auth/me` | `app/api/auth.py::auth_me` | `app/services/external_auth_service.py::authenticate` | 无本地仓储 | Django `user`、`institution`、`department` | FastAPI 转发 token 到 Django `/api/user/users/me/`，使用 Django `id` 作为统一 `user_id` |
|
|
| Agent 状态 | Hello / 功能开关 | `GET /api/v1/agent/hello` | `app/api/agent.py::agent_hello` | `app/core/config.py::as_public_dict` | `app/services/audit_service.py` | `audit_logs` | 给前端展示当前模型、PDF、知识库等能力开关 |
|
|
| 病例读取 | 病例列表 | `GET /api/v1/cases` | `app/api/cases.py::list_cases` | `app/services/case_service.py::list_cases` | `app/repositories/case_repository.py` | `case_base`、`traditional_case`、`teaching_case` | 只读已发布启用病例，不做病例新增/删除 |
|
|
| 病例读取 | 病例详情 | `GET /api/v1/cases/{case_id}` | `app/api/cases.py::get_case_detail` | `app/services/case_service.py::get_case_detail` | `app/repositories/case_repository.py` | `case_base`、`traditional_case`、`teaching_case` | 前端展示病例基础信息，不作为病例管理后台 |
|
|
| 训练配置 | 推荐配置信息 | `GET /api/v1/training-config/recommended?case_id=1` | `app/api/training_config.py::get_recommended_training_config` | `app/services/training_config_service.py::get_recommended` | `app/repositories/case_repository.py` | `case_base`、`traditional_case` | 返回默认就诊环境、年龄段、文化程度、性格等病人初始化信息 |
|
|
| 训练配置 | 可选配置信息 | `GET /api/v1/training-config/options?case_id=1` | `app/api/training_config.py::get_training_config_options` | `app/services/training_config_service.py::get_options` | `app/repositories/case_repository.py` | `case_base` | 返回前端可选配置项，用于自定义病人信息 |
|
|
| 训练页面 | 新建会话 | `POST /api/v1/sessions` | `app/api/sessions.py::create_session` | `app/services/session_service.py::create_session` | `app/repositories/session_repository.py`、`case_repository.py` | `training_session`、Redis memory | 创建会话、写入 user_id、初始化短期 memory 和病人开场白 |
|
|
| 训练页面 | 流式问诊 | `POST /api/v1/sessions/{session_id}/chat/stream` | `app/api/sessions.py::chat_stream` | `app/services/session_service.py::stream_chat` | `session_repository.py`、`case_repository.py` | `training_session`、Redis memory | Patient Agent SSE 输出 `message_delta`、`message_done`、`error` |
|
|
| 训练页面 | 王主任练习提示 | `POST /api/v1/sessions/{session_id}/hints/stream` | `app/api/sessions.py::stream_hints` | `app/services/session_service.py::stream_hints` | `session_repository.py`、`case_repository.py` | `training_session`、Redis memory | 根据病例和当前会话生成一句话练习提示 |
|
|
| 训练页面 | 结构化提示 | `POST /api/v1/sessions/{session_id}/hints` | `app/api/sessions.py::generate_hints` | `app/services/session_service.py::generate_hints` | `session_repository.py`、`case_repository.py` | `training_session`、Redis memory | 返回缺失维度、下一步问题、推荐检查；当前前端主用流式提示 |
|
|
| 训练页面 | 检查项列表 | `GET /api/v1/sessions/{session_id}/order-items` | `app/api/sessions.py::list_order_items` | `app/services/order_service.py::list_order_items` | `case_repository.py`、`session_repository.py` | `case_exam_item` | 返回当前病例全部可申请检查项，不返回结果 |
|
|
| 训练页面 | 体格检查列表 | `GET /api/v1/sessions/{session_id}/physical-exams` | `app/api/sessions.py::list_physical_exam_items` | `app/services/order_service.py::list_physical_exam_items` | `case_repository.py`、`session_repository.py` | `case_exam_item` | 过滤 `item_type=physical_exam` |
|
|
| 训练页面 | 辅助检查列表 | `GET /api/v1/sessions/{session_id}/auxiliary-exams` | `app/api/sessions.py::list_auxiliary_exam_items` | `app/services/order_service.py::list_auxiliary_exam_items` | `case_repository.py`、`session_repository.py` | `case_exam_item` | 过滤非体格检查项 |
|
|
| 训练页面 | 体格检查结果 | `POST /api/v1/sessions/{session_id}/physical-exams/{item_code}` | `app/api/sessions.py::create_physical_exam_order` | `app/services/order_service.py::create_physical_exam_order` | `case_repository.py`、`session_repository.py` | `case_exam_item`、`training_order`、Redis memory | 检查结果只来自数据库；同一会话同一 `item_code` 幂等 |
|
|
| 训练页面 | 辅助检查结果 | `POST /api/v1/sessions/{session_id}/auxiliary-exams/{item_code}` | `app/api/sessions.py::create_auxiliary_exam_order` | `app/services/order_service.py::create_auxiliary_exam_order` | `case_repository.py`、`session_repository.py` | `case_exam_item`、`training_order`、Redis memory | 检查结果写入短期 memory，供后续评价使用 |
|
|
| 训练页面 | 完成问诊 | `POST /api/v1/sessions/{session_id}/complete-inquiry` | `app/api/sessions.py::complete_inquiry` | `app/services/session_service.py::complete_inquiry` | `session_repository.py` | `training_session`、Redis memory | 校验至少有医生问诊后进入诊断阶段 |
|
|
| 训练页面 | 提交诊断 | `POST /api/v1/sessions/{session_id}/diagnosis` | `app/api/sessions.py::submit_diagnosis` | `app/services/session_service.py::submit_diagnosis` | `session_repository.py` | `training_submission`、`training_session` | 保存主诊断、鉴别诊断、诊断依据 |
|
|
| 训练页面 | 提交治疗 | `POST /api/v1/sessions/{session_id}/treatment` | `app/api/sessions.py::submit_treatment` | `app/services/session_service.py::submit_treatment` | `session_repository.py` | `training_submission`、`training_session` | 保存治疗原则、措施、风险预案、沟通和随访 |
|
|
| 训练页面 | 生成评价 | `POST /api/v1/sessions/{session_id}/evaluation` | `app/api/sessions.py::create_evaluation` | `app/services/evaluation_service.py::create_evaluation` | `evaluation_repository.py`、`source_case_repository.py`、`session_repository.py` | `training_record`、`training_score_detail`、`scoring_rule` | 读取评分规则、短期 memory、诊断治疗提交内容，调用 Scoring Agent |
|
|
| 个人中心 | 训练记录列表 | `GET /api/v1/evaluations?page=1&page_size=10` | `app/api/evaluations.py::list_evaluations` | `app/services/evaluation_service.py::list_history` | `app/repositories/evaluation_repository.py` | `training_record` | 按 Django user_id 隔离，支持分页 |
|
|
| 个人中心 | 评价详情 | `GET /api/v1/evaluations/{evaluation_id}` | `app/api/evaluations.py::get_evaluation_detail` | `app/services/evaluation_service.py::get_detail` | `evaluation_repository.py` | `training_record`、`training_score_detail` | 训练评价和教学互动评价共用详情接口 |
|
|
| 个人中心 | 导出 PDF | `POST /api/v1/evaluations/{evaluation_id}/export-pdf` | `app/api/evaluations.py::export_pdf` | `app/services/pdf_export_service.py::export` | `evaluation_repository.py` | `training_record` | 生成本地 PDF 并写入 `pdf_file_path` |
|
|
| 个人中心 | 下载 PDF | `GET /api/v1/evaluations/{evaluation_id}/download-pdf` | `app/api/evaluations.py::download_pdf` | `app/services/pdf_export_service.py::export` | `evaluation_repository.py` | `training_record` | 校验 user_id 后返回 `application/pdf` 文件流 |
|
|
| 教学互动 | 获取教学列表 | `GET /api/v1/teaching/cases/{case_id}/items` | `app/api/teaching.py::get_teaching_items` | `app/services/teaching_service.py::list_items` | `teaching_repository.py`、`case_repository.py` | `case_base`、`teaching_case` | 返回题目、选项、答案、解析文本、视频 |
|
|
| 教学互动 | 生成评价 | `POST /api/v1/teaching/evaluation` | `app/api/teaching.py::create_teaching_evaluation` | `app/services/teaching_service.py::create_evaluation` | `evaluation_repository.py`、`teaching_repository.py` | `training_record`、`training_score_detail`、`teaching_case` | 根据作答结果生成教学互动评价 |
|
|
| AI 学习助手 | 流式问答 | `POST /api/v1/learning-assistant/chat/stream` | `app/api/learning_assistant.py::learning_assistant_stream_chat` | `app/services/learning_assistant_service.py::stream_chat` | `knowledge_base_repository.py` | `kb_spaces`、`kb_chunks`、`kb_query_logs` | 优先 RAG 检索；无知识库时返回 `retrieval_hit=false` 后继续 LLM 回答 |
|
|
| AI 学习助手 | 非流式调试问答 | `POST /api/v1/learning-assistant/chat` | `app/api/learning_assistant.py::learning_assistant_chat` | `app/services/learning_assistant_service.py::chat` | `knowledge_base_repository.py` | `kb_spaces`、`kb_chunks`、`kb_query_logs` | `include_in_schema=False`，正式前端不使用 |
|
|
| 知识库管理 | 上传 PDF | `POST /api/v1/knowledge-admin/documents/upload` | `app/api/knowledge_admin.py::upload_knowledge_document` | `app/services/document_ingestion_service.py::upload_pdf` | `knowledge_base_repository.py` | `kb_spaces`、`kb_documents`、`kb_ingestion_tasks`、`kb_chunks` | 仅内容管理员使用；学生端不展示入口 |
|
|
| 健康检查 | 存活检查 | `GET /health/live` | `app/api/health.py::live` | 无 | 无 | 无 | 检查 FastAPI 进程可响应 |
|
|
| 健康检查 | 就绪检查 | `GET /health/ready` | `app/api/health.py::ready` | `settings.deployment_config_errors` | 数据库连接 | MySQL、Redis 配置 | 用于部署验证 |
|
|
|
|
## 3. 核心流程说明
|
|
|
|
### 3.1 训练链路
|
|
|
|
1. 前端调用 `GET /api/v1/auth/me` 验证用户。
|
|
2. 前端读取病例和训练配置。
|
|
3. 前端调用 `POST /api/v1/sessions` 创建 `training_session`，后端初始化 Redis 短期 memory。
|
|
4. 前端调用 `POST /api/v1/sessions/{session_id}/chat/stream` 进行流式问诊。
|
|
5. 用户申请体格检查或辅助检查，后端从 `case_exam_item` 返回固定结果并写入 `training_order` 和 Redis memory。
|
|
6. 用户完成问诊、提交诊断、提交治疗。
|
|
7. 后端读取 `scoring_rule`、问诊 memory、检查结果、诊断治疗提交内容，调用 Scoring Agent。
|
|
8. 完成评价后写入 `training_record` 和 `training_score_detail`，释放 Redis memory。
|
|
9. 用户通过评价详情或 PDF 下载查看结果。
|
|
|
|
### 3.2 教学互动链路
|
|
|
|
1. 前端调用 `GET /api/v1/teaching/cases/{case_id}/items` 获取题目、选项、答案、解析、视频。
|
|
2. 前端提交作答到 `POST /api/v1/teaching/evaluation`。
|
|
3. 后端生成评价并写入 `training_record`、`training_score_detail`。
|
|
4. 评价详情和 PDF 下载复用个人中心接口。
|
|
|
|
### 3.3 AI 学习助手链路
|
|
|
|
1. 前端调用 `POST /api/v1/learning-assistant/chat/stream`。
|
|
2. 后端根据当前用户 `institution_id` 查找知识空间。
|
|
3. 有知识库时：问题 embedding -> Milvus 检索 -> MySQL 读取 chunk 元数据 -> 拼接来源给 LLM。
|
|
4. 无知识库或检索失败时：返回 `retrieval_hit=false`，继续给出通用 LLM 学习回答。
|
|
5. 后端写入 `kb_query_logs`，记录命中、来源和耗时。
|
|
|
|
## 4. 重要边界
|
|
|
|
- FastAPI 不维护用户注册登录。
|
|
- FastAPI 不负责病例 PDF 解析入库。
|
|
- 检查结果必须来自 `case_exam_item`，不允许 LLM 编造。
|
|
- 问诊聊天记录只作为 Redis 短期 memory，评价完成后释放。
|
|
- 长期训练结果只写入 `training_record` 和 `training_score_detail`。
|
|
- 教学互动评价和训练评价共用评价详情、PDF 下载、个人中心记录列表。
|
|
- 知识库上传是内容管理员能力，学生端不展示入口。
|