finalize medical consultation agent backend

2026-06-03 15:51:46 +08:00
parent 93d9e1c6a5
commit eb43573a44
33 changed files with 1063 additions and 281 deletions
@@ -1,115 +1,20 @@
-# 医疗问诊 Agent FastAPI 后端
+# 医疗问诊 Agent 后端

-本仓库提交内容只包含医疗问诊 Agent 的 FastAPI 后端工程。前端 Demo、开发文档、运行产物和本地环境文件不进入 Git。
+医疗问诊 Agent 是宿主医疗教学平台中的问诊训练子功能。后端基于 FastAPI 构建，负责病例读取、训练会话、多轮问诊、检查申请、诊断治疗提交、AI 评价、PDF 报告导出和历史记录查询。

-## 运行地址
+## 技术栈

-后端服务固定按以下地址启动：
+- Python 3.11
+- FastAPI
+- SQLAlchemy 2.x
+- MySQL
+- Redis
+- OpenAI-compatible LLM Adapter
+- ReportLab PDF

-```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"
-  }
-}
-```
-
-## 后端功能
+## 核心功能

+- Django 用户中心 token 校验
 - 病例列表与病例详情
 - 病例 SQL 安全导入与删除
 - 训练会话创建
@@ -118,15 +23,104 @@ curl -X GET "http://127.0.0.1:9000/api/v1/auth/me" \
 - 检查/检验申请
 - 诊断与治疗提交
 - AI 评价报告生成
+- 评分明细落库
 - PDF 报告导出
 - 历史评价查询
 - LLM Fast/Reason 测试

-## 初始化数据库
+## 本地启动
+
+```powershell
+cd backend
+python -m venv .venv
+.\.venv\Scripts\activate
+pip install -r requirements.txt
+cd ..
+copy .env.example .env
+```
+
+编辑 `.env`，填写 MySQL、Redis、Django 用户中心和 LLM 配置。
+
+启动服务：
+
+```powershell
+cd backend
+uvicorn app.main:app --host 127.0.0.1 --port 9000
+```
+
+访问：
+
+```text
+http://127.0.0.1:9000/docs
+```
+
+## Docker 启动
+
+```powershell
+copy .env.example .env
+docker build -t medical-consultation-agent-backend .
+docker run --env-file .env -p 9000:9000 medical-consultation-agent-backend
+```
+
+## 环境变量
+
+关键配置见 `.env.example`：
+
+```env
+DATABASE_URL=mysql+pymysql://root:<password>@mysql:3306/medical_platform?charset=utf8mb4
+MYSQL_URL=mysql+aiomysql://root:<password>@mysql:3306/medical_platform?charset=utf8mb4
+REDIS_URL=redis://redis:6379/0
+AUTH_USER_ME_URL=http://django:8000/api/user/users/me/
+LLM_BASE_URL=https://api.deepseek.com/chat/completions
+LLM_API_KEY=
+```
+
+真实数据库密码、LLM Key 和 access token 只写入本地 `.env` 或部署环境变量。
+
+## 数据库初始化与检查
+
+数据库需先创建好，表结构由后端脚本创建和校验。

 ```powershell
 cd backend
 .\.venv\Scripts\python.exe scripts\migrate_to_new_schema.py
+.\.venv\Scripts\python.exe scripts\migrate_user_department_score_detail.py
+.\.venv\Scripts\python.exe scripts\check_final_schema.py
+.\.venv\Scripts\python.exe scripts\check_final_demo_readiness.py
+```
+
+清空训练运行数据和本地报告文件：
+
+```powershell
+cd backend
+.\.venv\Scripts\python.exe scripts\clear_training_runtime_data.py --confirm CLEAR_TRAINING_DATA --reports
+```
+
+该脚本只清理训练会话、检查申请、提交、评价记录、评分明细、审计日志和本地 PDF 报告，不删除病例、用户、科室、检查项、评分规则、提示词和知识库。
+
+## 用户认证
+
+前端请求医疗问诊 Agent 时携带宿主系统 access token：
+
+```http
+Authorization: Bearer <access_token>
+X-Entry-Scene: mac_vue_dev
+```
+
+后端会转发 token 到 Django 用户中心：
+
+```text
+GET /api/user/users/me/
+```
+
+Django 返回 200 后，后端使用返回的 `id` 作为本系统内部用户隔离 ID。前端不需要传 `X-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"
 ```

 ## 测试
@@ -139,27 +133,11 @@ cd backend
 .\.venv\Scripts\python.exe tests\test_demo_flow.py
 ```

-## Git 提交范围
+## API 文档

-Git 仓库只跟踪：
+启动后访问：

 ```text
-backend/
-README.md
-.env.example
-.gitignore
-.gitattributes
-```
-
-不提交：
-
-```text
-frontend/
-docs/
-demo_frontend/
-scripts/
-.env
-storage/
-backend/.venv/
-本地报告、日志、数据库文件和临时 SQL 文件
+http://127.0.0.1:9000/docs
+http://127.0.0.1:9000/openapi.json
 ```