fastapi/README.md

# 医疗问诊 Agent FastAPI 后端

医疗问诊 Agent 是医疗教学平台中的问诊训练服务。后端负责 Django 用户身份校验、病例读取、多轮问诊、检查申请、诊断治疗提交、AI 评价、评分明细、PDF 报告和历史训练记录。

病例库在本服务中为只读数据源。病例新增、解析、修改和删除由外部病例管理系统负责；本服务只读取已发布病例及其训练扩展、检查项和评分规则。

## 项目结构

仓库根目录可以直接部署为服务器的 `fastapi/` 目录：

```text
fastapi/
├── app/                    # FastAPI 应用、Agent、服务、模型与提示词
├── scripts/                # 数据库迁移、结构检查与运维脚本
├── tests/                  # 核心逻辑与接口测试
├── Dockerfile
├── requirements.txt
├── .env.example
└── .env.production.example
```

## 核心依赖

- Python 3.11
- FastAPI
- SQLAlchemy 2.x
- MySQL 8
- Redis 7
- OpenAI-compatible LLM API
- Django 用户中心 `/api/user/users/me/`

## 本地启动

```powershell
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
uvicorn app.main:app --host 127.0.0.1 --port 9000
```

本地 Swagger：

```text
http://127.0.0.1:9000/docs
```

真实密码、LLM Key 和 access token 只写入本地 `.env` 或服务器环境变量，不提交到 Git。

## Docker Compose 部署

服务器目录：

```text
/home/code/medical-ai/
├── django/
├── fastapi/                # 本仓库
├── vueapp/
├── vuecms/
└── docker-compose.yml
```

首次拉取：

```bash
cd /home/code/medical-ai
git clone http://82.157.235.104:3000/Liu_JB/LiuJinbao.git fastapi
cp fastapi/.env.production.example fastapi/.env
vi fastapi/.env
```

必须在服务器 `.env` 中填写：

- MySQL 密码和数据库名
- `LLM_API_KEY`
- 实际前端来源 `CORS_ALLOW_ORIGINS`
- Nginx 使用 `/fastapi/` 前缀时保留 `APP_ROOT_PATH=/fastapi`

父目录 `docker-compose.yml` 的 FastAPI 服务需要包含：

```yaml
fastapi:
  build:
    context: ./fastapi
  container_name: fastapi
  restart: always
  ports:
    - "9000:9000"
  env_file:
    - ./fastapi/.env
  volumes:
    - ./logs/fastapi:/app/logs
    - ./data/fastapi-reports:/app/storage/reports
  depends_on:
    - mysql
    - redis
    - django
  networks:
    - medical
```

构建并启动：

```bash
cd /home/code/medical-ai
docker compose config
docker compose build fastapi
docker compose up -d fastapi
docker compose logs --tail=200 fastapi
```

后续更新：

```bash
cd /home/code/medical-ai/fastapi
git pull origin main
cd ..
docker compose build fastapi
docker compose up -d fastapi
```

## 数据库初始化与检查

服务启动后先进行只读结构检查：

```bash
cd /home/code/medical-ai
docker compose exec fastapi python scripts/check_final_schema.py
docker compose exec fastapi python scripts/check_final_demo_readiness.py
```

以下迁移脚本只用于独立本地开发库或旧环境升级，不得用于共享生产病例库：

```bash
docker compose exec fastapi python scripts/migrate_to_new_schema.py
docker compose exec fastapi python scripts/migrate_user_department_score_detail.py
```

迁移脚本使用 `create_all` 补齐 Agent 所需表，不删除 Django 或现有业务表；`migrate_to_new_schema.py` 会写入 Demo 病例和基础数据。共享环境中的病例数据由外部病例管理系统维护。

## 部署验证

容器内部端口验证：

```bash
curl http://127.0.0.1:9000/health/live
curl http://127.0.0.1:9000/health/ready
```

使用 Nginx `/fastapi/` 代理后的公网验证：

```text
http://8.160.178.88/fastapi/docs
http://8.160.178.88/fastapi/openapi.json
http://8.160.178.88/fastapi/health/ready
```

`/health/live` 返回 200 表示 FastAPI 进程正常。`/health/ready` 返回 200 表示 MySQL、Redis 和关键配置已经就绪；返回 503 时查看响应中的检查项和容器日志。

验证 Django 用户中心联调：

```bash
curl "http://8.160.178.88/fastapi/api/v1/auth/me" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Entry-Scene: production_vue"
```

验证 PDF 文件流下载：

```bash
curl -L "http://8.160.178.88/fastapi/api/v1/evaluations/<evaluation_id>/download-pdf" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Entry-Scene: production_vue" \
  -o evaluation_report.pdf
```

## 测试

```powershell
python -m compileall app scripts tests
python tests\test_core_logic.py
python tests\test_api_contract.py
python tests\test_demo_flow.py
```

当前测试覆盖训练页主要链路：

- Django token 鉴权与 user_id 隔离。
- 新建会话、流式问诊、练习提示。
- 体格检查列表、辅助检查列表、单项检查结果和重复申请幂等。
- 完成问诊、提交诊断、提交治疗、生成评价。
- 评价详情、历史评价、PDF 路径导出、PDF 文件流下载和跨用户访问拒绝。

病例新增、解析、导入、删除不在本 FastAPI 服务中实现；本服务只读取数据库中已发布病例、检查项和评分规则。