fastapi/docs/08_feature_code_map.md

功能-接口-代码-数据表映射表

本文档说明每个功能对应的 API、Router、Service、Repository、Model/数据表和关键逻辑。开发人员排查问题时优先从本表定位代码入口。

1. 通用调用规则

除健康检查外，业务接口都需要携带：

Authorization: Bearer <access_token>
X-Entry-Scene: vue_frontend
X-Request-Id: <可选>

普通 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 下载、个人中心记录列表。
• 知识库上传是内容管理员能力，学生端不展示入口。