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. 发布前必须检查

本地检查：

```powershell
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 检查：

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

敏感信息检查：

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

服务器检查：

```bash
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. 常用命令

本地测试：

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

服务器日志：

```bash
docker compose logs -f fastapi
```

服务器重启：

```bash
docker compose up -d fastapi
```

拉取最新代码：

```bash
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 学习助手流式可用