fastapi/docs/06_handover.md

交接文档

本文档用于说明医疗问诊 Agent FastAPI 后端当前状态、接手重点、风险和后续工作。

1. 当前项目状态

当前 FastAPI 后端已经完成第一阶段核心功能，并已接入 Django 用户中心、MySQL、Redis、LLM、PDF 下载和 AI 学习助手。

已完成能力：

• Django access token 鉴权
• 训练配置和推荐配置
• 新建训练会话
• AI 病人流式问诊
• 王主任练习提示
• 体格检查和辅助检查
• 完成问诊、提交诊断、提交治疗
• AI 评价和评分明细
• PDF 报告导出和下载
• 教学互动题目和评价
• 个人中心训练记录和详情
• AI 学习助手流式问答
• 后台知识库上传和 RAG 架构预留

当前不是最终生产级完整系统，后续上线后仍需要逐模块做稳定性、监控、权限、性能和运维增强。

2. 优先关注

接手后建议按顺序确认：

1. 能否本地启动 FastAPI。
2. 能否连接云端 MySQL 和 Redis。
3. GET /api/v1/auth/me 是否能通过 Django token 返回用户信息。
4. 训练全流程是否能跑通。
5. 教学互动是否能跑通。
6. PDF 下载是否正常。
7. AI 学习助手流式接口是否正常。
8. 云服务器 docker compose build fastapi 是否成功。
9. .env 是否与云服务器 docker-compose 服务名一致。

3. 当前重要约定

• FastAPI 不负责登录注册。
• 用户身份来自 Django /api/user/users/me/。
• FastAPI 使用 Django 返回的 id 作为 user_id。
• 普通业务接口需要 Authorization: Bearer <access_token>。
• 训练记录只有完整流程完成后写入。
• 问诊过程主要存在 Redis 短期 memory。
• 检查结果只来自数据库。
• AI 学习助手正式接口只保留流式接口。
• 知识库未初始化时，学习助手仍应正常回答。

4. 发布前必须检查

本地检查：

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

Git 检查：

git status --short
git grep -n "<<<<<<<\|=======\|>>>>>>>"
git diff --check

敏感信息检查：

git grep -n "sk-"
git grep -n "api_key"
git grep -n "password"
git grep -n "access_token"
git grep -n "secret"

服务器检查：

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

5. 已知风险

风险	当前处理	后续建议
LLM 调用超时或失败	已有异常返回和 mock/fallback 配置	增加限流、重试、熔断、成本统计
知识库真实大规模入库	当前为生产预留能力	压测 PDF 解析、embedding、Milvus 写入
Celery 任务监控	已预留任务模块	增加 worker 部署、重试、任务状态看板
部分宽异常处理	保证 Demo 稳定	逐步收窄异常类型并补充结构化日志
PDF 报告样式	当前可下载	后续按医院模板优化
前端最终样式	不在本仓库维护	以后按 API 文档继续联调

6. 后续生产级优化建议

6.1 工程与质量

• 增加 CI/CD。
• 增加 lint 和格式化。
• 增加数据库 migration 管理。
• 增加更多 service 单元测试。
• 增加接口压测。

6.2 安全与权限

• 完善内容管理员角色来源。
• 对后台知识库接口增加更细权限。
• 增加审计日志检索。
• 增加敏感信息脱敏。

6.3 AI 与 Agent

• 优化 Patient Agent 回答稳定性。
• 优化 Scoring Agent JSON 结构校验。
• 增加评分重试和人工复核。
• 增加 LLM 调用耗时、token、费用统计。
• 增加提示词版本管理。

6.4 知识库

• 完善 PDF 解析质量检测。
• 优化分片策略。
• 接入真实 embedding 批量任务。
• 增加 Milvus collection 生命周期管理。
• 增加 RAG 命中率和用户反馈统计。

7. 常用命令

本地测试：

.\backend\.venv\Scripts\python.exe tests\test_api_contract.py

服务器日志：

docker compose logs -f fastapi

服务器重启：

docker compose up -d fastapi

拉取最新代码：

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

8. 交接清单

• main 分支是最新代码
• git status 干净
• 无 Git 冲突标记
• 无真实密钥提交
• .env.example 和 .env.production.example 已更新
• README 已更新
• API 文档已更新
• 架构、数据库、部署、模块、排障文档已补齐
• 本地测试全部通过
• Docker build 通过
• 云端 /fastapi/docs 可访问
• auth/me 可用
• 训练链路可用
• 教学互动可用
• PDF 下载可用
• AI 学习助手流式可用