完善训练链路接口与PDF下载

2026-06-08 15:16:07 +08:00
parent 41a2851120
commit 11b1712b01
12 changed files with 550 additions and 164 deletions
@@ -1,7 +1,7 @@
-# 医疗问诊 Agent 前端联调 API 文档
+# 医疗问诊 Agent 前端联调 API 文档

-> 文档版本：2026-06-04  
-> 对应后端：FastAPI `main` 分支当前版本  
+> 文档版本：2026-06-04
+> 对应后端：FastAPI `main` 分支，提交 `b46e43a` 之后版本
 > 本文档以当前真实代码行为为准，用于正式 Vue 前端功能联调。

 ## 1. 联调地址
@@ -81,31 +81,28 @@ if (!response.ok || body.code !== "OK") {
 }
 ```

+### 2.4 CORS 配置
+
+正式前端通过 `http://8.160.178.88/app/` 访问 API 时，与 `/fastapi/` 同源，不会触发跨域限制。
+
+Mac 上使用 Vite 开发服务器直接调用公网 API 时，服务器 `.env` 必须允许前端 Origin。例如：
+
+```env
+CORS_ALLOW_ORIGINS=http://localhost:5173,http://192.168.2.100:5173
+CORS_ALLOW_ORIGIN_REGEX=
+```
+
+修改服务器 `.env` 后重新创建 FastAPI 容器：
+
+```bash
+cd /home/code/medical-ai
+docker compose up -d --force-recreate fastapi
+```
+
+不需要重新构建镜像。
+
 ## 3. 当前接口总览

-### 3.0 训练页面交付接口表
-
-以下表格为前端训练页面当前交付接口。`url` 使用公网网关前缀，前端实际调用时统一在 `api` 前拼接 `http://8.160.178.88/fastapi`。
-
-| 模块 | 接口名称 | url | api | methods | params | response | 说明 |
-|---|---|---|---|---|---|---|---|
-| 训练页面 | 推荐配置信息 | `http://8.160.178.88/fastapi/api/v1/training-config/recommended` | `/api/v1/training-config/recommended` | `GET` | Query：`case_id` | `recommended`、`recommended_labels`、`options` | 初始化训练页病人配置，默认选中门诊、青年、高等教育、平和。 |
-| 训练页面 | 训练配置信息 | `http://8.160.178.88/fastapi/api/v1/training-config/options` | `/api/v1/training-config/options` | `GET` | Query：`case_id` | `recommended`、`recommended_labels`、`options` | 返回自定义配置全部可选项，用于前端渲染就诊环境、年龄段、文化程度、性格。 |
-| 训练页面 | 新建会话 | `http://8.160.178.88/fastapi/api/v1/sessions` | `/api/v1/sessions` | `POST` | Body：`case_id`、`training_type`、`mode`、`score_type`、`patient_config` | `session_id`、`session_code`、`status`、`patient_opening`、`patient_config` | 创建训练会话并把病人初始化配置写入会话 metadata。 |
-| 训练页面 | 流式会话 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/chat/stream` | `/api/v1/sessions/{session_id}/chat/stream` | `POST` | Path：`session_id`；Body：`message` | SSE：`message_delta`、`message_done`、`error` | 医学生问诊，AI 病人按病例和配置流式回复。 |
-| 训练页面 | 练习提示 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/hints/stream` | `/api/v1/sessions/{session_id}/hints/stream` | `POST` | Path：`session_id`；Body：`last_user_message`、`scope` | SSE：`hint_delta`、`hint_done`、`error` | 返回一句话形式的练习提示，前端点击后按需展示。旧 JSON 接口 `/hints` 保留兼容。 |
-| 训练页面 | 体格检查列表获取 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/physical-exams` | `/api/v1/sessions/{session_id}/physical-exams` | `GET` | Path：`session_id` | `items[]` | 从当前病例检查项中筛选体格检查类项目。暂无独立表，复用 `case_exam_item`。 |
-| 训练页面 | 辅助检查列表获取 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/auxiliary-exams` | `/api/v1/sessions/{session_id}/auxiliary-exams` | `GET` | Path：`session_id` | `items[]` | 从当前病例检查项中筛选辅助检查类项目。暂无独立表，复用 `case_exam_item`。 |
-| 训练页面 | 体格检查某项结果 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/physical-exams/{item_code}` | `/api/v1/sessions/{session_id}/physical-exams/{item_code}` | `POST` | Path：`session_id`、`item_code` | 检查结果结构 | 返回数据库固定检查结果，并写入本次会话上下文。 |
-| 训练页面 | 辅助检查某项结果 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/auxiliary-exams/{item_code}` | `/api/v1/sessions/{session_id}/auxiliary-exams/{item_code}` | `POST` | Path：`session_id`、`item_code` | 检查结果结构 | 返回数据库固定检查结果，并写入本次会话上下文。 |
-| 训练页面 | 完成问诊 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/complete-inquiry` | `/api/v1/sessions/{session_id}/complete-inquiry` | `POST` | Path：`session_id` | `session_id`、`status` | 从问诊阶段进入诊断阶段。 |
-| 训练页面 | 提交诊断 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/diagnosis` | `/api/v1/sessions/{session_id}/diagnosis` | `POST` | Path：`session_id`；Body：诊断内容 | `status` | 保存主要诊断、鉴别诊断和诊断依据。 |
-| 训练页面 | 提交治疗 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/treatment` | `/api/v1/sessions/{session_id}/treatment` | `POST` | Path：`session_id`；Body：治疗内容 | `status` | 保存治疗原则、措施、风险预案、沟通和随访。 |
-| 训练页面 | 生成评价 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/evaluation` | `/api/v1/sessions/{session_id}/evaluation` | `POST` | Path：`session_id`；Body：`score_type` | 评价报告结构 | 调用评分 Agent，写入 `training_record` 和 `training_score_detail`。 |
-| 训练页面 | 获取评价（详情） | `http://8.160.178.88/fastapi/api/v1/evaluations/{evaluation_id}` | `/api/v1/evaluations/{evaluation_id}` | `GET` | Path：`evaluation_id` | 评价详情和评分明细 | 按当前 token 对应用户隔离查询。 |
-| 训练页面 | 下载 PDF | `http://8.160.178.88/fastapi/api/v1/evaluations/{evaluation_id}/export-pdf` | `/api/v1/evaluations/{evaluation_id}/export-pdf` | `POST` | Path：`evaluation_id` | `export_id`、`file_path` | 生成本地 PDF 报告路径。 |
-| 训练页面 | 历史评价列表 | `http://8.160.178.88/fastapi/api/v1/evaluations` | `/api/v1/evaluations` | `GET` | 无 | `items[]` | 查询当前 token 对应用户的完整训练评价历史。 |
-
 ### 3.1 无需认证

 | Method | Path | 用途 |
@@ -123,13 +120,13 @@ if (!response.ok || body.code !== "OK") {
 | `GET` | `/agent/hello` | 获取 Agent 能力开关。 | 必须 |
 | `GET` | `/cases` | 获取病例列表。 | 必须 |
 | `GET` | `/cases/{case_id}` | 获取病例入口详情。 | 必须 |
-| `GET` | `/training-config/recommended` | 获取推荐配置信息。 | 必须 |
-| `GET` | `/training-config/options` | 获取训练配置选项。 | 必须 |
+| `GET` | `/training-config/recommended` | 获取训练页推荐病人初始化配置。 | 必须 |
+| `GET` | `/training-config/options` | 获取训练页自定义配置选项。 | 必须 |
 | `POST` | `/sessions` | 创建训练会话。 | 必须 |
 | `POST` | `/sessions/{session_id}/chat` | 非流式问诊。 | 必须 |
 | `POST` | `/sessions/{session_id}/chat/stream` | SSE 流式问诊。 | 必须 |
 | `POST` | `/sessions/{session_id}/hints` | 练习模式提示。 | 必须 |
-| `POST` | `/sessions/{session_id}/hints/stream` | SSE 一句话练习提示。 | 必须 |
+| `POST` | `/sessions/{session_id}/hints/stream` | SSE 流式练习提示。 | 必须 |
 | `GET` | `/sessions/{session_id}/order-items` | 获取病例可申请检查项。 | 必须 |
 | `POST` | `/sessions/{session_id}/orders` | 申请检查并返回结果。 | 必须 |
 | `GET` | `/sessions/{session_id}/physical-exams` | 获取体格检查列表。 | 必须 |
@@ -143,12 +140,11 @@ if (!response.ok || body.code !== "OK") {
 | `GET` | `/evaluations` | 查询当前用户历史评价。 | 必须 |
 | `GET` | `/evaluations/{evaluation_id}` | 查询评价详情和评分明细。 | 必须 |
 | `POST` | `/evaluations/{evaluation_id}/export-pdf` | 生成 PDF 报告。 | 必须 |
+| `GET` | `/evaluations/{evaluation_id}/download-pdf` | 生成并下载 PDF 报告文件流。 | 必须 |
 | `GET` | `/knowledge/search` | 调试知识检索。 | 调试 |
 | `POST` | `/llm/test/deepseek-fast` | 测试快速模型。 | 调试 |
 | `POST` | `/llm/test/deepseek-reason` | 测试 Reason 模型。 | 调试 |

-病例接口为只读接口。病例新增、解析、修改和删除由外部病例管理系统负责，正式前端不得调用本服务管理病例。
-
 ## 4. 前端完整业务流程

 ```text
@@ -164,6 +160,7 @@ GET /auth/me
  -> POST /sessions/{session_id}/evaluation
  -> GET /evaluations/{evaluation_id}
  -> POST /evaluations/{evaluation_id}/export-pdf
+  -> GET /evaluations/{evaluation_id}/download-pdf
 ```

 会话状态流转：
@@ -182,6 +179,41 @@ inquiry -> diagnosis -> treatment -> evaluating -> completed

 当前没有“获取会话详情”“恢复聊天记录”接口。页面刷新或中断后，前端不能恢复短期对话，应重新创建训练会话。

+### 4.1 训练页面当前使用接口明细
+
+下表为正式前端训练页面当前需要直接调用的接口。`url` 为公网联调完整地址，`api` 为前端代码中拼接的相对路径。除健康检查外，以下接口都需要携带 `Authorization: Bearer <access_token>`；`X-Entry-Scene` 建议固定传 `vue_frontend` 或实际入口场景。
+
+| 接口名称 | url | api | methods | params（入参） | response（返回参数） |
+|---|---|---|---|---|---|
+| 新建会话 | `http://8.160.178.88/fastapi/api/v1/sessions` | `/api/v1/sessions` | `POST` | Header：`Authorization` 必填，`X-Entry-Scene` 建议传；Body：`case_id` 必填，`training_type` 必填，`mode` 必填，`score_type` 可选，`patient_config` 可选。 | `code`、`message`、`data.session_id`、`data.session_code`、`data.status`、`data.patient_opening`、`data.patient_config`。 |
+| 流式会话 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/chat/stream` | `/api/v1/sessions/{session_id}/chat/stream` | `POST` | Path：`session_id` 必填；Body：`message` 必填。 | SSE：`message_delta` 返回 `delta`；`message_done` 返回 `latency_ms`、`first_token_ms`、`model`、`fallback_used`；异常返回 `error`。 |
+| 练习提示 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/hints/stream` | `/api/v1/sessions/{session_id}/hints/stream` | `POST` | Path：`session_id` 必填；Body：`last_user_message` 可选，`scope=current_conversation`。仅 `practice` 且 `inquiry` 状态可调用。 | SSE：`hint_delta` 返回一句话提示增量；`hint_done` 返回耗时；异常返回 `error`。 |
+| 体格检查列表获取 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/physical-exams` | `/api/v1/sessions/{session_id}/physical-exams` | `GET` | Path：`session_id` 必填。 | `data.items[]`，包含 `item_code`、`item_name`、`item_type`。不返回检查结果。 |
+| 辅助检查列表获取 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/auxiliary-exams` | `/api/v1/sessions/{session_id}/auxiliary-exams` | `GET` | Path：`session_id` 必填。 | `data.items[]`，包含 `item_code`、`item_name`、`item_type`。不返回检查结果。 |
+| 体格检查某项结果 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/physical-exams/{item_code}` | `/api/v1/sessions/{session_id}/physical-exams/{item_code}` | `POST` | Path：`session_id` 必填，`item_code` 必填。`item_code` 必须属于体格检查项。 | `data.item_code`、`item_name`、`item_type`、`result_text`、`result_structured`、`is_key`、`is_abnormal`、`context_written`、`already_ordered`。 |
+| 辅助检查某项结果 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/auxiliary-exams/{item_code}` | `/api/v1/sessions/{session_id}/auxiliary-exams/{item_code}` | `POST` | Path：`session_id` 必填，`item_code` 必填。`item_code` 必须属于辅助检查项。 | 同体格检查结果。检查结果来自数据库，并写入本次会话短期 memory。重复申请返回已有结果，`already_ordered=true`。 |
+| 完成问诊 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/complete-inquiry` | `/api/v1/sessions/{session_id}/complete-inquiry` | `POST` | Path：`session_id` 必填。至少完成一轮医生问诊后可调用。 | `data.session_id`、`data.status=diagnosis`。 |
+| 提交诊断 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/diagnosis` | `/api/v1/sessions/{session_id}/diagnosis` | `POST` | Path：`session_id` 必填；Body：`primary_diagnosis` 必填，`diagnosis_basis` 必填，`differential_diagnoses` 可选数组。 | `data.status=treatment`。 |
+| 提交治疗 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/treatment` | `/api/v1/sessions/{session_id}/treatment` | `POST` | Path：`session_id` 必填；Body：`treatment_principle` 必填，`treatment_measures` 必填，`risk_plan`、`communication`、`follow_up` 可选。 | `data.status=evaluating`。 |
+| 生成评价 | `http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/evaluation` | `/api/v1/sessions/{session_id}/evaluation` | `POST` | Path：`session_id` 必填；Body：`score_type` 可选，允许 `percentage`、`five_point`。必须已提交治疗。 | `data.evaluation_id`、`score_type`、`total_score`、`dimension_scores`、`score_details`、`errors`、`improvement_plan`、`evidence_summary`、`guideline_refs`、`overall_comment`。 |
+| 获取评价（详情） | `http://8.160.178.88/fastapi/api/v1/evaluations/{evaluation_id}` | `/api/v1/evaluations/{evaluation_id}` | `GET` | Path：`evaluation_id` 必填。只允许当前 token 对应用户访问自己的评价。 | 评价完整详情，包含 `session_id`、`case_id`、`case_title`、`created_at`、`pdf_file_path`。 |
+| 生成 PDF | `http://8.160.178.88/fastapi/api/v1/evaluations/{evaluation_id}/export-pdf` | `/api/v1/evaluations/{evaluation_id}/export-pdf` | `POST` | Path：`evaluation_id` 必填。只允许当前 token 对应用户导出自己的评价。 | `data.export_id`、`data.file_path`。 |
+| 下载 PDF 文件流 | `http://8.160.178.88/fastapi/api/v1/evaluations/{evaluation_id}/download-pdf` | `/api/v1/evaluations/{evaluation_id}/download-pdf` | `GET` | Path：`evaluation_id` 必填。Header：`Authorization` 必填，`X-Entry-Scene` 建议传。只允许当前 token 对应用户下载自己的评价报告。 | 成功时返回 `application/pdf` 文件流，响应头包含 `Content-Disposition: attachment`；失败时返回统一错误 JSON。 |
+
+常见错误码：
+
+| code | 场景 |
+|---|---|
+| `AUTH_CREDENTIAL_REQUIRED` | 缺少 `Authorization`。 |
+| `SESSION_NOT_FOUND` | 会话不存在或不属于当前用户。 |
+| `SESSION_STATUS_INVALID` | 当前会话状态不允许该操作。 |
+| `INQUIRY_REQUIRED` | 未完成至少一轮医生问诊就完成问诊。 |
+| `ORDER_ITEM_NOT_FOUND` | 当前病例下不存在该检查项。 |
+| `ORDER_ITEM_TYPE_MISMATCH` | 用体格检查接口申请辅助检查，或用辅助检查接口申请体格检查。 |
+| `TREATMENT_REQUIRED` | 未提交治疗就生成评价。 |
+| `EVALUATION_NOT_FOUND` | 评价不存在或不属于当前用户。 |
+| `PDF_EXPORT_FAILED` | PDF 生成失败。 |
+
 ## 5. 认证与 Agent

 ### 5.1 获取当前用户
@@ -352,15 +384,23 @@ GET /api/v1/cases/{case_id}
 }
 ```

-## 7. 创建训练会话
+### 6.3 推荐配置信息

-### 7.1 推荐配置信息
+推荐配置信息用于训练页初始化病人沟通风格。后端会读取病例主表内容，根据病例年龄、标题、主诉、描述和标签推断默认值。例如儿科患儿病例默认推荐 `age_group=child`；急诊、危重、低氧等关键词会推荐 `visit_environment=emergency` 和 `personality=anxious`。

 ```http
 GET /api/v1/training-config/recommended?case_id=2
 ```

-响应：
+入参：
+
+```json
+{
+  "case_id": 2
+}
+```
+
+返回：

 ```json
 {
@@ -370,37 +410,39 @@ GET /api/v1/training-config/recommended?case_id=2
    "case_id": 2,
    "recommended": {
      "visit_environment": "outpatient",
-      "age_group": "youth",
+      "age_group": "child",
      "education_level": "higher",
      "personality": "calm"
    },
    "recommended_labels": {
      "visit_environment": "门诊",
-      "age_group": "青年",
+      "age_group": "儿童",
      "education_level": "高等教育",
      "personality": "平和"
    },
-    "options": {
-      "visit_environment": [
-        {"value": "outpatient", "label": "门诊", "description": "适合常规问诊训练"}
-      ],
-      "age_group": [],
-      "education_level": [],
-      "personality": []
-    }
+    "options": {}
  }
 }
 ```

-### 7.2 训练配置信息
+### 6.4 训练配置信息
+
+训练配置信息用于前端渲染自定义配置页面，返回推荐值和全部可选项。前端可以直接使用 `recommended` 作为默认选中项，用户修改后把 `patient_config` 传给创建会话接口。

 ```http
 GET /api/v1/training-config/options?case_id=2
 ```

-该接口返回和推荐配置信息相同的结构，前端使用 `options` 渲染自定义配置按钮，使用 `recommended` 初始化默认选中项。
+返回字段与推荐配置信息一致，`options` 包含以下可选值：

-### 7.3 新建会话
+| 配置字段 | 可选值 | 说明 |
+|---|---|---|
+| `visit_environment` | `outpatient`、`emergency`、`ward` | 门诊、急诊、病房。 |
+| `age_group` | `child`、`youth`、`middle_aged`、`elderly` | 儿童、青年、中年、老年。 |
+| `education_level` | `primary_or_below`、`secondary`、`higher` | 小学及以下、中等教育、高等教育。 |
+| `personality` | `calm`、`anxious`、`impatient`、`cooperative`、`suspicious` | 平和、焦虑、急躁、配合、多疑。 |
+
+## 7. 创建训练会话

 ```http
 POST /api/v1/sessions
@@ -417,7 +459,7 @@ Content-Type: application/json
  "score_type": "percentage",
  "patient_config": {
    "visit_environment": "outpatient",
-    "age_group": "youth",
+    "age_group": "child",
    "education_level": "higher",
    "personality": "calm"
  }
@@ -431,12 +473,13 @@ Content-Type: application/json
 | `training_type` | `case_analysis`、`diagnosis_treatment`、`consultation` | 训练类别。 |
 | `mode` | `practice`、`teaching` | 正式前端使用的两种模式。 |
 | `score_type` | `percentage`、`five_point` | 百分制或五分制。 |
-| `patient_config.visit_environment` | `outpatient`、`emergency`、`ward` | 就诊环境。 |
-| `patient_config.age_group` | `child`、`youth`、`middle_aged`、`elderly` | 病人年龄段配置。 |
-| `patient_config.education_level` | `primary_or_below`、`secondary`、`higher` | 病人文化程度配置。 |
-| `patient_config.personality` | `calm`、`anxious`、`impatient`、`cooperative`、`suspicious` | 病人性格配置。 |
+| `patient_config.visit_environment` | `outpatient`、`emergency`、`ward` | 就诊环境，影响 AI 病人沟通节奏。 |
+| `patient_config.age_group` | `child`、`youth`、`middle_aged`、`elderly` | 年龄段，影响病人或家属表达方式。 |
+| `patient_config.education_level` | `primary_or_below`、`secondary`、`higher` | 文化程度，影响医学术语理解和表达清晰度。 |
+| `patient_config.personality` | `calm`、`anxious`、`impatient`、`cooperative`、`suspicious` | 性格，影响情绪和配合度。 |

 后端仍接受旧值 `novice`，但会自动转换为 `practice`。正式前端不要继续使用 `novice`。
+`patient_config` 为可选字段；未传时后端会根据当前病例自动使用推荐配置。前端训练页已调用推荐配置接口时，应把用户最终选中的配置传入本接口。

 响应：

@@ -452,13 +495,13 @@ Content-Type: application/json
    "patient_config": {
      "values": {
        "visit_environment": "outpatient",
-        "age_group": "youth",
+        "age_group": "child",
        "education_level": "higher",
        "personality": "calm"
      },
      "labels": {
        "visit_environment": "门诊",
-        "age_group": "青年",
+        "age_group": "儿童",
        "education_level": "高等教育",
        "personality": "平和"
      }
@@ -586,8 +629,6 @@ async function streamChat(baseUrl: string, token: string, sessionId: number, mes

 ### 8.3 练习提示

-#### 8.3.1 JSON 兼容接口
-
 ```http
 POST /api/v1/sessions/{session_id}/hints
 ```
@@ -630,43 +671,6 @@ POST /api/v1/sessions/{session_id}/hints
 - 仅 `inquiry` 状态可调用。
 - 前端默认不自动展示提示，由用户点击后调用。

-#### 8.3.2 SSE 一句话提示
-
-```http
-POST /api/v1/sessions/{session_id}/hints/stream
-Content-Type: application/json
-Accept: text/event-stream
-```
-
-请求：
-
-```json
-{
-  "last_user_message": "孩子发热几天了？最高体温多少？",
-  "scope": "current_conversation"
-}
-```
-
-事件格式：
-
-```text
-event: hint_delta
-data: {"delta":"当前可补充既往史、严重程度评估；"}
-
-event: hint_done
-data: {"latency_ms":1200}
-
-event: error
-data: {"code":"HINT_STREAM_FAILED","message":"练习提示生成失败，请稍后重试"}
-```
-
-前端规则：
-
- 该接口用于训练页面“查看提示”的新交互。
- 返回内容为一句话形式，适合在提示区域流式展示。
- 如果收到 `error`，前端结束 loading 并展示错误。
- 旧 JSON 接口 `/hints` 保留，用于需要结构化缺失维度和推荐检查的页面。
-
 ## 9. 检查与检验

 ### 9.1 获取当前病例检查项
@@ -695,23 +699,7 @@ GET /api/v1/sessions/{session_id}/order-items

 前端不得写死检查项编码。不同病例拥有不同检查项，必须使用本接口返回的 `item_code`。

-### 9.2 获取体格检查列表
-
-```http
-GET /api/v1/sessions/{session_id}/physical-exams
-```
-
-响应结构与 `/order-items` 相同。当前没有独立体格检查表，后端按 `item_type`、`category`、`item_name` 从 `case_exam_item` 中识别体格检查类项目。
-
-### 9.3 获取辅助检查列表
-
-```http
-GET /api/v1/sessions/{session_id}/auxiliary-exams
-```
-
-响应结构与 `/order-items` 相同。当前没有独立辅助检查表，非体格检查类项目均归入辅助检查。
-
-### 9.4 申请检查
+### 9.2 申请检查

 ```http
 POST /api/v1/sessions/{session_id}/orders
@@ -756,22 +744,6 @@ POST /api/v1/sessions/{session_id}/orders
 - 前端按 `item_code` 去重；点击后立即禁用，避免重复请求。
 - 检查申请允许在 `inquiry`、`diagnosis`、`treatment` 状态执行。

-### 9.5 获取体格检查某项结果
-
-```http
-POST /api/v1/sessions/{session_id}/physical-exams/{item_code}
-```
-
-响应结构与 `/orders` 相同。该接口用于前端按“体格检查”分区调用，内部仍复用检查申请逻辑。
-
-### 9.6 获取辅助检查某项结果
-
-```http
-POST /api/v1/sessions/{session_id}/auxiliary-exams/{item_code}
-```
-
-响应结构与 `/orders` 相同。该接口用于前端按“辅助检查”分区调用，内部仍复用检查申请逻辑。
-
 ## 10. 阶段提交

 ### 10.1 完成问诊
@@ -988,17 +960,123 @@ POST /api/v1/evaluations/{evaluation_id}/export-pdf
 }
 ```

-当前接口只生成 PDF 并返回服务器内部文件路径，没有提供浏览器文件下载流。前端功能测试阶段展示“导出成功”和文件路径即可。正式下载接口需要后续增加受鉴权保护的文件响应接口。
+该接口只生成 PDF 并返回服务器内部文件路径，适合前端展示“导出成功”和保存导出记录。

-## 12. 调试接口
+### 11.5 下载 PDF 文件流

-### 12.1 知识检索
+```http
+GET /api/v1/evaluations/{evaluation_id}/download-pdf
+Authorization: Bearer <access_token>
+X-Entry-Scene: vue_frontend
+```
+
+成功响应不是统一 JSON 包装，而是 PDF 文件流：
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/pdf
+Content-Disposition: attachment; filename="training_record_101_percentage_xxx.pdf"
+```
+
+错误响应仍然使用统一 JSON：
+
+```json
+{
+  "code": "EVALUATION_NOT_FOUND",
+  "message": "evaluation not found",
+  "data": null
+}
+```
+
+前端通过浏览器直接下载时不能使用普通 `<a href>` 携带 Bearer token，应使用 `fetch` 或 `axios` 的 blob 请求，然后创建临时下载链接：
+
+```ts
+async function downloadEvaluationPdf(baseUrl: string, token: string, evaluationId: number) {
+  const response = await fetch(`${baseUrl}/evaluations/${evaluationId}/download-pdf`, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "X-Entry-Scene": "vue_frontend",
+    },
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => null);
+    throw new Error(error?.message || `PDF 下载失败：${response.status}`);
+  }
+
+  const blob = await response.blob();
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = `evaluation_${evaluationId}.pdf`;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  URL.revokeObjectURL(url);
+}
+```
+
+## 12. 管理与调试接口
+
+### 12.1 病例 SQL 预检
+
+```http
+POST /api/v1/imports/case-sql/preview
+Content-Type: multipart/form-data
+```
+
+FormData：
+
+```text
+file=<病例SQL文件>
+```
+
+只读取以下四张源表：
+
+```text
+case_base
+traditional_case
+teaching_case
+scoring_rule
+```
+
+预检不会写入数据库。
+
+### 12.2 确认导入
+
+```http
+POST /api/v1/imports/case-sql/apply
+Content-Type: multipart/form-data
+```
+
+后端根据导入病例生成或更新 `case_exam_item`，导入后病例列表可立即查询。
+
+### 12.3 病例删除
+
+```http
+GET /api/v1/cases/{case_id}/delete-preview
+DELETE /api/v1/cases/{case_id}
+```
+
+删除请求：
+
+```json
+{
+  "confirm": true,
+  "delete_training_data": true
+}
+```
+
+删除会级联清理病例、病例扩展数据、检查项、评分规则以及相关训练数据。学生前端不得开放该功能。
+
+### 12.4 知识检索

 ```http
 GET /api/v1/knowledge/search?department_id=2&training_type=diagnosis_treatment&q=肺炎,血氧
 ```

-### 12.2 LLM 测试
+### 12.5 LLM 测试

 ```http
 POST /api/v1/llm/test/deepseek-fast
@@ -1068,6 +1146,7 @@ apiClient.interceptors.response.use(
 | SSE error | `LLM_STREAM_FAILED` | 流式模型调用失败。 |
 | SSE error | `LLM_EMPTY_RESPONSE` | 模型未返回有效文本。 |
 | 500 | `PDF_EXPORT_FAILED` | PDF 生成失败。 |
+| 400 | `CASE_SQL_IMPORT_INVALID` | 病例 SQL 预检或导入失败。 |

 ## 15. 前端功能验收顺序

@@ -1082,13 +1161,14 @@ apiClient.interceptors.response.use(
 9. 完成问诊、提交诊断、提交治疗。
 10. 生成评价，确认包含 `dimension_scores` 和 `score_details`。
 11. 查询历史列表和评价详情。
-12. 导出 PDF，确认接口返回文件路径。
+12. 生成 PDF，确认接口返回文件路径。
+13. 下载 PDF 文件流，确认浏览器触发文件下载。

 ## 16. 当前前端必须了解的限制

 - 无会话详情和聊天恢复接口，页面刷新后无法恢复短期问诊。
 - 问诊聊天只保存在 Redis 短期 memory 中，评价完成后释放。
- PDF 导出当前只返回服务器文件路径，不直接下载文件。
- 病例库为只读数据源；新增、解析、修改和删除由外部病例管理系统完成。
+- PDF 支持两种调用：`export-pdf` 返回服务器文件路径，`download-pdf` 返回 `application/pdf` 文件流并触发浏览器下载。
+- 病例导入和删除接口尚未增加管理员角色授权，学生前端必须隐藏。
 - 所有检查项必须从 `/order-items` 动态读取，不能写死。
 - 正式训练模式只有 `practice` 和 `teaching`；`novice` 仅为旧接口兼容值。