chore: initialize medical consultation agent demo

2026-06-01 09:25:26 +08:00
commit a7733243b2
139 changed files with 15764 additions and 0 deletions
@@ -0,0 +1,174 @@
+# 医疗问诊 Agent 第一版 Demo
+
+这是大系统中的“医疗问诊 Agent”子功能 Demo。系统不做独立注册登录，宿主系统进入时通过请求头传入 `X-User-Id`，后端按该用户隔离会话、检查申请、诊断治疗提交、评价报告和历史记录。
+
+## 当前功能
+
+```text
+病例列表
+-> 病例详情
+-> 创建训练会话
+-> 多轮问诊 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
+```
+
+旧表 `cases`、`case_exam_items`、`training_sessions`、`session_orders`、`session_submissions`、`evaluation_records`、`evaluation_report_exports`、`rubric_templates` 已清理。
+
+## 启动后端
+
+```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 dump 不能直接在正式库执行。项目提供安全导入脚本，只解析病例数据并按当前新表字段映射写入，不执行源 SQL 中的 `DROP TABLE`、`CREATE TABLE`、`ALTER TABLE`。
+
+先检查不写库：
+
+```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
+```
+
+如果源 SQL 缺少 `case_exam_item`，脚本会根据病例描述生成基础检查项目，保障练习模式可继续申请检查。源 SQL 存在乱码、字段数量不匹配或损坏的 `INSERT` 时，脚本会拒绝导入。
+
+前端也提供同一套安全导入能力：
+
+```text
+http://127.0.0.1:5173/#/import
+```
+
+页面流程为“选择 SQL 文件 -> 解析检查 -> 确认导入 -> 刷新病例库”。后端接口只接受 `.sql` 文件，最大 5MB，只解析 `case_base`、`traditional_case`、`teaching_case`、`scoring_rule` 四类源表数据；`case_exam_item` 仍由后端按病例内容自动补齐。确认导入成功后，病例列表会重新请求后端，新病例可以直接进入练习模式或教学互动模式。
+
+## 启动前端
+
+```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 |
+
+## 验证命令
+
+```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) | 儿科病例演示脚本 |