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 |
| 后续优化 | 任务队列监控、失败重试、分片策略、文件去重、权限后台 |