fastapi/docs/02_database.md

# 数据库说明

本文档说明医疗问诊 Agent FastAPI 后端依赖的核心数据表、读写边界和交接注意事项。

## 1. 数据库边界

当前服务连接平台 MySQL 数据库 `medical`。用户、机构、科室由 Django 平台维护；FastAPI 只读取用户上下文，不负责注册登录。

FastAPI 主要负责：

- 读取病例、教学题、检查项、评分规则
- 写入训练会话过程中的提交结果
- 完整训练结束后写入训练记录和评分明细
- 生成 PDF 文件路径和导出状态
- 后台预留知识库相关表

## 2. 用户与组织表

### `user`

| 项 | 说明 |
|---|---|
| 来源 | Django 用户中心 |
| FastAPI 用途 | 通过 `/api/user/users/me/` 获取用户身份 |
| 关键字段 | `id`、`username`、`real_name`、`phone`、`role_type`、`institution_id`、`department_id`、`status` |
| 写入方 | Django |
| FastAPI 是否写入 | 否 |

FastAPI 使用 Django 返回的 `id` 作为业务 `user_id`。

### `institution`

| 项 | 说明 |
|---|---|
| 来源 | Django / 平台数据库 |
| FastAPI 用途 | 学习助手知识库按机构隔离 |
| 关键字段 | `id`、`name` |
| 写入方 | Django 或平台后台 |
| FastAPI 是否写入 | 否 |

### `department`

| 项 | 说明 |
|---|---|
| 来源 | 平台数据库 |
| FastAPI 用途 | 病例科室、评分规则、知识库筛选 |
| 关键字段 | `id`、`name`、`category`、`institution_id` |
| 写入方 | 平台后台 |
| FastAPI 是否写入 | 否 |

## 3. 病例与训练基础表

### `case_base`

| 项 | 说明 |
|---|---|
| 用途 | 病例主表，训练和教学互动共用 |
| 读取模块 | 病例列表、病例详情、训练会话、教学互动 |
| 关键字段 | `id`、`department_id`、`title`、`difficulty`、`case_type`、`status` |
| 写入方 | 平台病例解析 / 后台维护 |
| FastAPI 是否写入 | 否 |

### `traditional_case`

| 项 | 说明 |
|---|---|
| 用途 | 练习模式传统病例详情 |
| 读取模块 | 训练会话、Patient Agent、Scoring Agent |
| 关键字段 | `case_id`、主诉、现病史、既往史、查体、辅助检查、诊断、治疗 |
| 写入方 | 平台病例解析 / 后台维护 |
| FastAPI 是否写入 | 否 |

### `teaching_case`

| 项 | 说明 |
|---|---|
| 用途 | 教学互动病例和题目数据 |
| 读取模块 | 教学互动列表、教学互动评价 |
| 关键字段 | `case_id`、题目、选项、答案、解析、视频 |
| 写入方 | 平台病例解析 / 后台维护 |
| FastAPI 是否写入 | 否 |

### `case_exam_item`

| 项 | 说明 |
|---|---|
| 用途 | 当前病例可申请的体格检查和辅助检查项 |
| 读取模块 | 检查列表、检查结果、评价 |
| 关键字段 | `case_id`、`item_code`、`item_name`、`item_type`、`result_text` |
| 写入方 | 平台病例解析 / 后台维护 |
| FastAPI 是否写入 | 否 |

检查结果必须来自该表，不允许 LLM 编造。

### `scoring_rule`

| 项 | 说明 |
|---|---|
| 用途 | AI 评价基础评分规则 |
| 读取模块 | Scoring Agent、教学互动评价 |
| 关键字段 | `case_id`、`department_id`、评分维度、分值、规则内容 |
| 写入方 | 平台后台 |
| FastAPI 是否写入 | 否 |

## 4. 训练记录表

### `training_sessions`

| 项 | 说明 |
|---|---|
| 用途 | 训练过程会话状态 |
| 写入模块 | 新建会话、阶段流转 |
| 关键字段 | `id`、`session_uid`、`user_id`、`case_id`、`mode`、`status`、`patient_config` |
| 访问隔离 | 必须按 `user_id` 查询 |

### `session_orders`

| 项 | 说明 |
|---|---|
| 用途 | 记录当前会话已申请检查 |
| 写入模块 | 体格检查 / 辅助检查结果接口 |
| 关键字段 | `session_id`、`item_code`、`result_text`、`already_ordered` |
| 重要规则 | 同一会话同一 `item_code` 幂等，不重复写入 |

### `session_submissions`

| 项 | 说明 |
|---|---|
| 用途 | 保存诊断和治疗提交内容 |
| 写入模块 | 提交诊断、提交治疗 |
| 关键字段 | `session_id`、`submission_type`、`content` |

### `session_runtime_messages`

| 项 | 说明 |
|---|---|
| 用途 | 调试或短期会话消息辅助表 |
| 规则 | 长期历史不以完整聊天记录为主，正式上下文优先走 Redis 短期 memory |

### `training_record`

| 项 | 说明 |
|---|---|
| 用途 | 完整训练结束后的长期记录 |
| 写入模块 | 生成评价、教学互动评价 |
| 关键字段 | `id`、`user_id`、`case_id`、`score_type`、`total_score`、`report_summary`、`pdf_path` |
| 重要规则 | 中断、退出、未完成流程不写入 |

### `training_score_detail`

| 项 | 说明 |
|---|---|
| 用途 | 评分明细表 |
| 写入模块 | 训练评价、教学互动评价 |
| 关键字段 | `record_id`、`rule_id`、`dimension`、`score`、`deducted_reason`、`evidence_message_ids`、`ai_confidence`、`comment` |

## 5. 知识库预留表

### `kb_knowledge_space`

| 项 | 说明 |
|---|---|
| 用途 | 机构知识空间和 Milvus collection 映射 |
| 关键字段 | `institution_id`、`collection_name`、`embedding_model`、`embedding_dim`、`status` |

### `kb_knowledge_document`

| 项 | 说明 |
|---|---|
| 用途 | 内容管理员上传 PDF 的元数据 |
| 关键字段 | `institution_id`、`uploaded_by`、`file_name`、`file_sha256`、`status`、`parse_status`、`embedding_status`、`chunk_count` |

### `kb_knowledge_chunk`

| 项 | 说明 |
|---|---|
| 用途 | PDF 分片文本和页码来源 |
| 关键字段 | `document_id`、`institution_id`、`chunk_uid`、`page_start`、`page_end`、`chunk_text` |

### `kb_knowledge_ingestion_task`

| 项 | 说明 |
|---|---|
| 用途 | PDF 入库任务进度 |
| 关键字段 | `document_id`、`institution_id`、`status`、`progress`、`current_step`、`error_message` |

### `kb_knowledge_query_log`

| 项 | 说明 |
|---|---|
| 用途 | AI 学习助手 RAG 查询日志 |
| 关键字段 | `user_id`、`institution_id`、`question`、`retrieval_hit`、`retrieved_chunk_ids`、`answer_summary`、耗时字段 |

当前阶段 AI 学习助手不强依赖知识库存在；没有知识库时仍会调用 LLM 流式回答。

## 6. Redis 数据

Redis 用于短期会话 memory：

- 会话创建时初始化
- 问诊、检查结果、诊断治疗提交时写入
- 评价生成后释放
- TTL 到期后自动过期

Redis 不作为长期训练历史存储。

## 7. 数据库交接注意事项

- FastAPI 不维护用户注册登录。
- FastAPI 不直接修改病例基础数据。
- 训练记录按 `user_id` 隔离。
- 检查结果只从 `case_exam_item` 返回。
- 评价生成后才写长期训练记录。
- 知识库表是生产扩展点，真实大规模入库前需要压测。