刘金宝医疗问诊 Agent 第一版 Demo
这是大系统中的“医疗问诊 Agent”子功能 Demo。系统不做独立注册登录，宿主系统进入本 Agent 时通过请求头传入 X-User-Id，后端按该用户标识隔离训练会话、检查申请、诊断治疗提交、AI 评价报告和历史记录。
当前功能
病例列表
-> 病例详情
-> 病例 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 运行时拼接 |
核心数据表
当前功能依赖以下表：
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
旧表已不参与运行。
启动后端
cd D:\Code\newfounder\medical-consultation-agent\backend
.\.venv\Scripts\activate
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
接口文档：
http://127.0.0.1:8000/docs
初始化数据库
cd D:\Code\newfounder\medical-consultation-agent\backend
.\.venv\Scripts\python.exe scripts\migrate_to_new_schema.py
清理旧表：
.\.venv\Scripts\python.exe scripts\drop_legacy_tables.py
导入接口解析后的病例 SQL
后端提供安全导入能力，只解析源 SQL 中的 case_base、traditional_case、teaching_case、scoring_rule 四类病例数据，不执行源 SQL 中的删表、建表或锁表语句。
命令行预检：
cd D:\Code\newfounder\medical-consultation-agent\backend
.\.venv\Scripts\python.exe scripts\import_source_case_sql.py "C:\path\to\case.sql"
确认预检通过后写入：
.\.venv\Scripts\python.exe scripts\import_source_case_sql.py "C:\path\to\case.sql" --apply
前端导入页：
http://127.0.0.1:5173/#/import
启动前端
cd D:\Code\newfounder\medical-consultation-agent\frontend
npm.cmd install
npm.cmd run dev -- --host 127.0.0.1 --port 5173
访问：
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 后先调用：
GET /api/v1/auth/me
前端需要携带宿主系统登录态：
Authorization: Bearer <token>
X-Entry-Scene: mac_vue_dev
如果宿主系统使用 Cookie 登录，则前端需要开启 withCredentials，后端会把 Cookie 转发到：
http://192.168.2.76:8000/api/user/users/me/
FastAPI 会从 Django 返回值中提取 user_id，后续病例训练、会话、评价和历史记录都按该 user_id 隔离。X-User-Id 只作为本地 Demo 兼容方式。
验证命令
后端：
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
前端：
cd D:\Code\newfounder\medical-consultation-agent\frontend
npm.cmd run build
文档入口
| 文档 | 内容 |
|---|---|
| docs/00_development_log.md | 开发过程和变更记录 |
| docs/01_functional_scope.md | 当前功能范围 |
| docs/02_database_design.md | 数据库总体设计 |
| docs/02_database_table_dictionary.md | 表字段字典 |
| docs/03_api_design.md | 前端 API 对接文档 |
| docs/04_data_collection.md | 数据采集和存储边界 |
| docs/05_agent_prompt_design.md | Agent 和提示词模板调用说明 |
| docs/06_demo_testing_guide.md | 前端测试指南 |
| docs/07_demo_function_traceability.md | 功能到代码和数据表追踪 |
| docs/08_pediatric_case_demo_script.md | 儿科病例演示脚本 |
Git 管理说明
仓库上传范围包含 backend、frontend、docs、scripts 和项目说明文件。
不上传：
demo_frontend/.envbackend/.venv/frontend/node_modules/frontend/dist/storage/- 本地 PDF、日志、数据库文件和临时 SQL 文件