fastapi/docs/05_modules.md

功能模块说明

本文档用于说明当前后端功能模块的职责、接口、数据表和后续优化方向。

1. 用户鉴权模块

项	内容
主要作用	调用 Django 用户中心验证 access token，并生成 FastAPI 用户上下文
当前状态	已实现
相关接口	GET /api/v1/auth/me
相关代码	app/api/auth.py、app/services/external_auth_service.py、app/core/user_context.py
相关表	Django user、institution、department
外部依赖	Django /api/user/users/me/
后续优化	增加用户中心失败重试和更细的审计日志

2. 训练配置模块

项	内容
主要作用	返回推荐病人配置和可选配置项
当前状态	已实现
相关接口	GET /api/v1/training-config/recommended、GET /api/v1/training-config/options
相关代码	app/api/training_config.py、app/services/training_config_service.py
相关表	case_base、traditional_case
后续优化	配置项可迁移到独立后台配置表

3. 训练会话模块

项	内容
主要作用	创建训练会话、维护状态流转和短期 memory
当前状态	已实现
相关接口	POST /api/v1/sessions、POST /api/v1/sessions/{session_id}/chat/stream
相关代码	app/api/sessions.py、app/services/session_service.py、app/agents/patient_agent.py
相关表	training_sessions
Redis	保存当前会话短期问诊上下文
后续优化	增加会话超时策略和更完整的状态机校验

4. 王主任练习提示模块

项	内容
主要作用	根据当前病例和会话上下文生成练习提示
当前状态	已实现，正式接口为 SSE
相关接口	POST /api/v1/sessions/{session_id}/hints/stream
相关代码	app/agents/hint_agent.py、app/services/session_service.py
相关提示词	app/prompts/hint/novice_case_hint.md
后续优化	增加科室主任风格模板、提示质量评估和可配置提示强度

5. 检查/检验模块

项	内容
主要作用	获取体格检查和辅助检查列表，返回单项检查结果
当前状态	已实现
相关接口	体格检查列表、辅助检查列表、体格检查结果、辅助检查结果
相关代码	app/services/order_service.py、app/repositories/case_repository.py
相关表	case_exam_item、session_orders
重要规则	结果只来自数据库；同一会话同一检查项幂等
后续优化	检查项可按阶段、难度、病例类型做更细配置

6. 诊断治疗提交模块

项	内容
主要作用	完成问诊后提交诊断和治疗方案
当前状态	已实现
相关接口	complete-inquiry、diagnosis、treatment
相关代码	app/services/session_service.py
相关表	session_submissions、training_sessions
后续优化	增加更细的字段级校验和草稿保存

7. AI 评价模块

项	内容
主要作用	读取病例、评分规则、会话过程、诊断治疗提交内容，调用 LLM 生成评价
当前状态	已实现
相关接口	POST /api/v1/sessions/{session_id}/evaluation
相关代码	app/services/evaluation_service.py、app/agents/scoring_agent.py、app/agents/report_agent.py
相关表	scoring_rule、training_record、training_score_detail
后续优化	增加评分一致性校验、评分重试和人工复核入口

8. PDF 报告模块

项	内容
主要作用	生成和下载 AI 评价 PDF
当前状态	已实现
相关接口	POST /api/v1/evaluations/{evaluation_id}/export-pdf、GET /api/v1/evaluations/{evaluation_id}/download-pdf
相关代码	app/services/pdf_export_service.py
相关表	training_record
文件目录	storage/reports
后续优化	优化 PDF 样式、分页、字体和医院模板

9. 教学互动模块

项	内容
主要作用	返回教学题目并根据答题结果生成评价
当前状态	已实现
相关接口	GET /api/v1/teaching/cases/{case_id}/items、POST /api/v1/teaching/evaluation
相关代码	app/api/teaching.py、app/services/teaching_service.py
相关表	case_base、teaching_case、training_record、training_score_detail
后续优化	增加题目后台维护、错题统计和视频播放记录

10. 个人中心模块

项	内容
主要作用	查询当前用户训练记录和评价详情
当前状态	已实现
相关接口	GET /api/v1/evaluations、GET /api/v1/evaluations/{evaluation_id}
相关代码	app/api/evaluations.py、app/services/evaluation_service.py
相关表	training_record、training_score_detail
重要规则	必须按 user_id 隔离
后续优化	增加分页筛选、统计图表和能力画像

11. AI 学习助手模块

项	内容
主要作用	普通用户提出医学学习问题，后端优先检索机构知识库并流式回答
当前状态	已实现正式流式接口；无知识库时自动降级为通用 LLM 回答
相关接口	POST /api/v1/learning-assistant/chat/stream
相关代码	app/api/learning_assistant.py、app/services/learning_assistant_service.py、app/agents/learning_assistant_agent.py
相关表	kb_knowledge_space、kb_knowledge_chunk、kb_knowledge_query_log
外部依赖	LLM、Embedding、Milvus
后续优化	查询改写、rerank、多轮记忆、来源引用格式优化、成本统计

12. 后台知识库预留模块

项	内容
主要作用	内容管理员上传 PDF，构建机构知识库
当前状态	接口和数据结构已预留，生产级大规模入库仍需压测
相关接口	POST /api/v1/knowledge-admin/documents/upload、文档列表、文档详情
相关代码	app/api/knowledge_admin.py、app/services/document_ingestion_service.py、app/integrations/*
相关表	kb_knowledge_space、kb_knowledge_document、kb_knowledge_chunk、kb_knowledge_ingestion_task
外部依赖	Milvus、Embedding 服务、Celery
后续优化	任务队列监控、失败重试、分片策略、文件去重、权限后台