fastapi/README.md

# 医疗问诊 Agent 第一版 Demo

这是大系统中的“医疗问诊 Agent”子功能 Demo。系统不做独立注册登录，宿主系统进入本 Agent 时通过请求头传入 `X-User-Id`，后端按该用户标识隔离训练会话、检查申请、诊断治疗提交、AI 评价报告和历史记录。

## 当前功能

```text
病例列表
-> 病例详情
-> 病例 SQL 导入/删除病例
-> 创建训练会话
-> 多轮问诊 Chat / SSE 流式 Chat
-> 练习提示
-> 检查/检验申请
-> 完成问诊
-> 提交诊断
-> 提交治疗方案
-> 生成 AI 评价报告
-> 导出 PDF
-> 查询历史记录
-> LLM Fast/Reason 测试
```

## 技术栈

| 层级 | 技术 |
|---|---|
| 后端 | FastAPI、SQLAlchemy 2.x、Pydantic |
| 数据库 | MySQL，库名 `medical_consultation_agent` |
| 短期记忆 | Redis 优先，进程内 memory 兜底 |
| LLM | OpenAI-compatible Chat Completions Adapter |
| 前端 | Vue 3、Vite、TypeScript、Pinia、Vue Router |
| 报告 | 本地 PDF 文件生成 |
| 提示词 | Markdown 模板 + Agent 运行时拼接 |

## 核心数据表

当前功能依赖以下表：

```text
case_base
traditional_case
teaching_case
scoring_rule
case_exam_item
training_session
training_order
training_submission
training_record
prompt_templates
knowledge_sources
knowledge_documents
knowledge_chunks
user_learning_profiles
audit_logs
```

旧表已不参与运行。

## 启动后端

```powershell
cd D:\Code\newfounder\medical-consultation-agent\backend
.\.venv\Scripts\activate
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
```

接口文档：

```text
http://127.0.0.1:8000/docs
```

## 初始化数据库

```powershell
cd D:\Code\newfounder\medical-consultation-agent\backend
.\.venv\Scripts\python.exe scripts\migrate_to_new_schema.py
```

清理旧表：

```powershell
.\.venv\Scripts\python.exe scripts\drop_legacy_tables.py
```

## 导入接口解析后的病例 SQL

后端提供安全导入能力，只解析源 SQL 中的 `case_base`、`traditional_case`、`teaching_case`、`scoring_rule` 四类病例数据，不执行源 SQL 中的删表、建表或锁表语句。

命令行预检：

```powershell
cd D:\Code\newfounder\medical-consultation-agent\backend
.\.venv\Scripts\python.exe scripts\import_source_case_sql.py "C:\path\to\case.sql"
```

确认预检通过后写入：

```powershell
.\.venv\Scripts\python.exe scripts\import_source_case_sql.py "C:\path\to\case.sql" --apply
```

前端导入页：

```text
http://127.0.0.1:5173/#/import
```

## 启动前端

```powershell
cd D:\Code\newfounder\medical-consultation-agent\frontend
npm.cmd install
npm.cmd run dev -- --host 127.0.0.1 --port 5173
```

访问：

```text
http://127.0.0.1:5173
```

## 环境变量

真实 `.env` 只保留在本地，不提交 API Key。

| 变量 | 说明 |
|---|---|
| `MYSQL_URL` | MySQL 连接串 |
| `REDIS_URL` | Redis 地址 |
| `RUNTIME_MEMORY_BACKEND` | `redis` 或 `memory` |
| `LLM_BASE_URL` | OpenAI-compatible `chat/completions` URL |
| `LLM_API_KEY` | 模型服务 API Key |
| `LLM_MODEL` | 默认模型 |
| `LLM_FAST_MODEL` | 问诊、提示、快速测试模型 |
| `LLM_REASON_MODEL` | Reason 测试模型 |
| `LLM_MOCK_ENABLED` | 是否强制 mock |
| `LLM_FALLBACK_TO_MOCK` | 真实模型失败时是否回退 mock |
| `AUTH_VALIDATE_ENABLED` | 是否启用 Django 用户中心鉴权 |
| `AUTH_USER_ME_URL` | Django 当前用户接口，例如 `http://192.168.2.76:8000/api/user/users/me/` |
| `AUTH_TIMEOUT_SECONDS` | 调用用户中心超时时间 |
| `AUTH_CACHE_TTL_SECONDS` | 用户信息短期缓存时间 |
| `AUTH_ALLOW_DEMO_USER_ID` | 外部鉴权开启时是否允许 `X-User-Id` Demo 兜底 |

## Django 用户中心联调

正式联调时，前端进入医疗问诊 Agent 后先调用：

```text
GET /api/v1/auth/me
```

前端需要携带宿主系统登录态：

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

如果宿主系统使用 Cookie 登录，则前端需要开启 `withCredentials`，后端会把 Cookie 转发到：

```text
http://192.168.2.76:8000/api/user/users/me/
```

FastAPI 会从 Django 返回值中提取 `user_id`，后续病例训练、会话、评价和历史记录都按该 `user_id` 隔离。`X-User-Id` 只作为本地 Demo 兼容方式。

## 验证命令

后端：

```powershell
cd D:\Code\newfounder\medical-consultation-agent\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
```

前端：

```powershell
cd D:\Code\newfounder\medical-consultation-agent\frontend
npm.cmd run build
```

## 文档入口

| 文档 | 内容 |
|---|---|
| [docs/00_development_log.md](docs/00_development_log.md) | 开发过程和变更记录 |
| [docs/01_functional_scope.md](docs/01_functional_scope.md) | 当前功能范围 |
| [docs/02_database_design.md](docs/02_database_design.md) | 数据库总体设计 |
| [docs/02_database_table_dictionary.md](docs/02_database_table_dictionary.md) | 表字段字典 |
| [docs/03_api_design.md](docs/03_api_design.md) | 前端 API 对接文档 |
| [docs/04_data_collection.md](docs/04_data_collection.md) | 数据采集和存储边界 |
| [docs/05_agent_prompt_design.md](docs/05_agent_prompt_design.md) | Agent 和提示词模板调用说明 |
| [docs/06_demo_testing_guide.md](docs/06_demo_testing_guide.md) | 前端测试指南 |
| [docs/07_demo_function_traceability.md](docs/07_demo_function_traceability.md) | 功能到代码和数据表追踪 |
| [docs/08_pediatric_case_demo_script.md](docs/08_pediatric_case_demo_script.md) | 儿科病例演示脚本 |

## Git 管理说明

仓库上传范围包含 `backend`、`frontend`、`docs`、`scripts` 和项目说明文件。

不上传：

- `demo_frontend/`
- `.env`
- `backend/.venv/`
- `frontend/node_modules/`
- `frontend/dist/`
- `storage/`
- 本地 PDF、日志、数据库文件和临时 SQL 文件