fastapi/docs/00_project_overview.md

项目总览

本文档用于快速说明医疗问诊 Agent FastAPI 后端的项目边界、功能现状、代码入口、部署方式、测试方法和后续维护重点。团队成员优先阅读本文，再按链接进入详细文档。

1. 项目定位

本项目是医疗教学平台中的 FastAPI 后端子服务，负责医疗问诊训练、教学互动、AI 评价、PDF 报告、AI 学习助手和机构知识库预留能力。

本项目不负责：

• 用户注册登录
• 用户管理后台
• 病例 PDF 解析入库
• 病例增删改后台
• 多租户权限后台
• HIS/LIS/PACS 连接
• 前端最终 UI

用户身份来自 Django 用户中心。前端携带 Authorization: Bearer <access_token> 调用 FastAPI，FastAPI 转发 token 到 Django /api/user/users/me/，以 Django 返回的 id 作为本服务统一 user_id。

2. 当前已实现功能

模块	状态	主要入口
用户鉴权	已实现	GET /api/v1/auth/me
训练配置	已实现	GET /api/v1/training-config/recommended、GET /api/v1/training-config/options
训练会话	已实现	POST /api/v1/sessions
流式问诊	已实现	POST /api/v1/sessions/{session_id}/chat/stream
王主任练习提示	已实现	POST /api/v1/sessions/{session_id}/hints/stream
体格检查 / 辅助检查	已实现	physical-exams、auxiliary-exams 相关接口
诊断 / 治疗提交	已实现	complete-inquiry、diagnosis、treatment
AI 评价	已实现	POST /api/v1/sessions/{session_id}/evaluation
个人中心训练记录	已实现，支持分页	GET /api/v1/evaluations?page=1&page_size=10
PDF 下载	已实现	GET /api/v1/evaluations/{evaluation_id}/download-pdf
教学互动	已实现	GET /api/v1/teaching/cases/{case_id}/items、POST /api/v1/teaching/evaluation
AI 学习助手	已实现短期会话和流式问答	POST /api/v1/learning-assistant/sessions、POST /api/v1/learning-assistant/sessions/{assistant_session_id}/chat/stream
内容管理员知识库上传	后台预留能力，当前前端不展示	POST /api/v1/knowledge-admin/documents/upload
健康检查	已实现	/health/live、/health/ready

3. 逻辑顺序

1. 项目边界：FastAPI 是后端子服务，不做登录、病例管理和最终 UI。
2. 认证链路：前端 token -> FastAPI -> Django /me -> 统一 user_id。
3. 训练链路：病例 ID -> 配置 -> 会话 -> 问诊 -> 检查 -> 诊断 -> 治疗 -> 评价 -> PDF -> 历史记录。
4. 教学互动链路：题目列表 -> 答题 -> 评价 -> PDF。
5. AI 学习助手链路：机构知识库检索 -> LLM 流式回答；无知识库时降级通用回答。
6. 数据库边界：平台基础数据由 Django/平台维护，FastAPI 主要写训练过程和训练结果。
7. 部署和验证：Docker、.env、/fastapi/docs、测试命令。
8. 后续生产化工作：索引补齐、任务队列、知识库构建、权限细化、日志监控。

4. 重点代码入口

目录/文件	作用
app/main.py	FastAPI 应用工厂、CORS、路由挂载、异常处理
app/api/router.py	所有业务路由聚合
app/core/user_context.py	从请求中解析当前用户上下文
app/services/external_auth_service.py	调用 Django 用户中心 /me
app/api/sessions.py	训练链路接口
app/services/session_service.py	训练会话、问诊、诊断治疗状态流转
app/services/order_service.py	体格检查和辅助检查
app/services/evaluation_service.py	训练评价生成和训练记录查询
app/services/teaching_service.py	教学互动题目与评价
app/services/pdf_export_service.py	PDF 报告生成与下载
app/services/learning_assistant_service.py	AI 学习助手 RAG + LLM 编排
app/services/document_ingestion_service.py	内容管理员 PDF 上传入库
app/agents	Patient、Hint、Scoring、Report、Learning Assistant 等 LLM Agent
app/prompts	Markdown 提示词模板

完整功能映射见 08_feature_code_map.md。

5. 核心文档索引

文档	用途
01_architecture.md	系统架构、核心链路、模块边界
02_database.md	数据库表、读写边界、表含义
03_api_design.md	前端 API 文档
04_deployment.md	云服务器部署、更新、回滚
05_modules.md	模块职责、接口、代码入口
06_maintenance_guide.md	开发维护、风险、发布检查清单
07_troubleshooting.md	常见故障排查
08_feature_code_map.md	功能到接口、代码、数据表的映射表
09_prompt_template_catalog.md	提示词模板目录和调用说明
10_function_workflow.md	功能工作流程、接口、提示词、数据库和结果去向

6. 本地测试命令

cd D:\Code\newfounder\medical-consultation-agent

.\backend\.venv\Scripts\python.exe -m compileall app scripts tests
.\backend\.venv\Scripts\python.exe tests\test_core_logic.py
.\backend\.venv\Scripts\python.exe tests\test_demo_flow.py
.\backend\.venv\Scripts\python.exe tests\test_api_contract.py

7. 数据库与 Redis 检查

.\backend\.venv\Scripts\python.exe scripts\check_final_schema.py
.\backend\.venv\Scripts\python.exe scripts\check_final_demo_readiness.py

推荐索引缺失不会阻断当前功能，但生产并发前需要补齐。

8. 云端部署验证

cd /home/code/medical-ai/fastapi
git pull origin main

cd /home/code/medical-ai
docker compose build fastapi
docker compose up -d fastapi
docker compose logs --tail=200 fastapi
curl http://127.0.0.1:9000/health/ready

公网访问：

http://8.160.178.88/fastapi/docs

9. 发布前检查

• git status --short 无未确认改动，或已明确哪些改动尚未提交。
• .env 不提交 Git。
• docs/03_api_design.md 是前端开发调用依据。
• docs/02_database.md 与当前 ORM 表名一致。
• 自动化测试全部通过。
• 云端 /fastapi/docs 可访问。
• GET /api/v1/auth/me 可用。
• 训练链路、教学互动、PDF、AI 学习助手各跑通一次。