fastapi/README.md

# 医疗问诊 Agent FastAPI 后端

本仓库提交内容只包含医疗问诊 Agent 的 FastAPI 后端工程。前端 Demo、开发文档、运行产物和本地环境文件不进入 Git。

## 运行地址

后端服务固定按以下地址启动：

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

Swagger：

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

启动命令：

```powershell
cd backend
.\.venv\Scripts\activate
uvicorn app.main:app --host 127.0.0.1 --port 9000
```

Docker 构建与运行：

```powershell
docker build -t medical-consultation-agent-backend .
docker run --env-file .env -p 9000:9000 medical-consultation-agent-backend
```

## 服务依赖

MySQL 使用容器或内网服务名 `mysql`：

```text
host=mysql
port=3306
database=medical
user=root
```

Redis 使用容器或内网服务名 `redis`：

```text
host=redis
port=6379
```

后端通过 `.env` 读取连接串。真实 `.env` 不提交到 Git，仓库只提供 `.env.example`。

## 环境变量

复制示例文件：

```powershell
copy .env.example .env
```

关键配置：

```env
APP_HOST=127.0.0.1
APP_PORT=9000
MYSQL_URL=mysql+aiomysql://root:<password>@mysql:3306/medical?charset=utf8mb4
DATABASE_URL=mysql+pymysql://root:<password>@mysql:3306/medical?charset=utf8mb4
RUNTIME_MEMORY_BACKEND=redis
REDIS_URL=redis://redis:6379/0
```

`<password>` 由部署环境注入。不要把真实数据库密码、LLM Key 或 access token 提交到 Git。

## 用户认证

医疗问诊 Agent 不做登录注册。正式联调时，前端携带宿主系统 access token：

```http
Authorization: Bearer <access_token>
X-Entry-Scene: mac_vue_dev
```

后端调用 Django 用户中心：

```text
GET /api/user/users/me/
```

Django 返回 200 后，后端使用返回的 `id` 作为内部 `user_id`，用于会话、训练记录、评价报告和历史记录隔离。

快速验证：

```bash
curl -X GET "http://127.0.0.1:9000/api/v1/auth/me" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Entry-Scene: mac_vue_dev"
```

成功条件：

```json
{
  "code": "OK",
  "data": {
    "source": "django_user_center"
  }
}
```

## 后端功能

- 病例列表与病例详情
- 病例 SQL 安全导入与删除
- 训练会话创建
- 多轮问诊与 SSE 流式回复
- 练习提示
- 检查/检验申请
- 诊断与治疗提交
- AI 评价报告生成
- PDF 报告导出
- 历史评价查询
- LLM Fast/Reason 测试

## 初始化数据库

```powershell
cd backend
.\.venv\Scripts\python.exe scripts\migrate_to_new_schema.py
```

## 测试

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

## Git 提交范围

Git 仓库只跟踪：

```text
backend/
README.md
.env.example
.gitignore
.gitattributes
```

不提交：

```text
frontend/
docs/
demo_frontend/
scripts/
.env
storage/
backend/.venv/
本地报告、日志、数据库文件和临时 SQL 文件
```