# 项目总览

本文档用于快速说明医疗问诊 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](08_feature_code_map.md)。

## 5. 核心文档索引

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

## 6. 本地测试命令

```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
```

## 7. 数据库与 Redis 检查

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

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

## 8. 云端部署验证

```bash
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
```

公网访问：

```text
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 学习助手各跑通一次。