fastapi/docs/03_api_design.md

医疗问诊 Agent API 文档

本文档面向前端开发调用，描述当前 FastAPI 后端可调用接口。训练模式和教学互动模式按页面模块分开书写；即使底层复用同一路由，文档中也在对应模块下分别列出，便于前端按页面开发。

公网基础地址：

http://8.160.178.88/fastapi

本地调试地址：

http://127.0.0.1:9000

1. 通用规则

除健康检查外，所有业务接口都需要携带：

Authorization: Bearer <access_token>
X-Entry-Scene: vue_frontend
X-Request-Id: <可选>

参数说明：

参数	位置	是否必填	说明
Authorization	Header	是	Django 用户中心签发的 access token，格式必须为 Bearer <access_token>
X-Entry-Scene	Header	建议填	入口场景，例如 vue_frontend、production_vue、mac_vue_dev
X-Request-Id	Header	否	前端生成的请求 ID，便于日志追踪

普通 JSON 接口统一返回：

{
  "code": "OK",
  "message": "success",
  "data": {}
}

前端判断成功规则：

• HTTP 状态码为 2xx
• code 等于 OK
• 业务数据从 data 读取

SSE 流式接口不返回上述 JSON 包装，而是返回：

event: <event_name>
data: {"key":"value"}

2. 用户鉴权

接口名称	url	api	methods	params（入参）	response（返回参数）
当前用户信息	http://8.160.178.88/fastapi/api/v1/auth/me	/api/v1/auth/me	GET	Header：Authorization 必填，格式 Bearer <access_token>；X-Entry-Scene 建议填写	data.user_id 用户 ID；data.username 用户名；data.display_name 显示名；data.role 用户身份；data.institution_id 机构 ID；data.institution_name 机构名称；data.department_id 科室 ID；data.department_name 科室名称；data.status 用户状态

请求示例：

curl -X GET "http://8.160.178.88/fastapi/api/v1/auth/me" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Entry-Scene: vue_frontend"

返回示例：

{
  "code": "OK",
  "message": "success",
  "data": {
    "user_id": "37",
    "source": "django_user_center",
    "username": "13700000099",
    "display_name": "Swagger测试",
    "role": "student",
    "phone": "13700000099",
    "institution_id": 1,
    "institution_name": "某医院",
    "department_id": 1,
    "department_name": "儿科",
    "status": 1
  }
}

3. 病例 ID 说明

当前 FastAPI 后端不提供病例公开查询接口。训练页面和教学互动页面需要使用的 case_id 由页面上下文传入，后端在各业务接口内部读取 case_base、traditional_case、teaching_case 和 case_exam_item 完成校验和业务处理。

病例、教学题、检查项和评分规则由平台数据库维护。FastAPI 不提供病例新增、删除、PDF 解析入库接口。

4. 训练模式 API

本节用于训练页面，包括推荐配置、自定义配置、新建会话、流式问诊、练习提示、检查申请、诊断治疗提交、评价生成、评价详情和 PDF 下载。

4.1 训练配置

接口名称	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 必填，病例 ID	data.case_id 病例 ID；data.recommended 默认配置值；data.recommended_labels 默认配置中文名；data.options 可选项
训练配置信息	http://8.160.178.88/fastapi/api/v1/training-config/options	/api/v1/training-config/options	GET	Query：case_id 必填，病例 ID	data.options.visit_environment 就诊环境；data.options.age_group 年龄段；data.options.education_level 文化程度；data.options.personality 性格

patient_config 可选值：

字段	是否必填	允许值	说明
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	平和、焦虑、急躁、配合、多疑

4.2 新建训练会话

接口名称	url	api	methods	params（入参）	response（返回参数）
新建会话	http://8.160.178.88/fastapi/api/v1/sessions	/api/v1/sessions	POST	Body：case_id 必填，病例 ID；training_type 必填，当前使用 diagnosis_treatment；mode 必填，当前训练模式使用 practice；score_type 必填，percentage 或 five_point；patient_config 选填，病人初始化配置	data.session_id 会话 ID；data.session_code 会话编码；data.status 当前阶段；data.patient_opening AI 病人开场白；data.patient_config 实际使用配置

请求示例：

{
  "case_id": 1,
  "training_type": "diagnosis_treatment",
  "mode": "practice",
  "score_type": "percentage",
  "patient_config": {
    "visit_environment": "outpatient",
    "age_group": "child",
    "education_level": "higher",
    "personality": "calm"
  }
}

4.3 流式会话

接口名称	url	api	methods	params（入参）	response（返回参数）
流式会话	http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/chat/stream	/api/v1/sessions/{session_id}/chat/stream	POST	Path：session_id 必填，会话 ID；Body：message 必填，1-2000 字，医学生问诊内容	SSE：message_delta AI 病人回复增量；message_done 完成事件；error 错误事件

请求示例：

{
  "message": "孩子发热几天了？最高体温多少？"
}

SSE 返回示例：

event: message_delta
data: {"delta":"发热有4天了，最高烧到39度多。"}

event: message_done
data: {"latency_ms":1200,"first_token_ms":300,"model":"deepseek-v4-pro","fallback_used":false}

4.4 王主任练习提示

接口名称	url	api	methods	params（入参）	response（返回参数）
王主任练习提示	http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/hints/stream	/api/v1/sessions/{session_id}/hints/stream	POST	Path：session_id 必填，会话 ID；Body：scope 选填，固定 current_conversation；last_user_message 选填，最后一句用户问题	SSE：hint_delta 提示文本增量；hint_done 完成事件；error 错误事件
结构化练习提示	http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/hints	/api/v1/sessions/{session_id}/hints	POST	Path：session_id 必填；Body：scope 选填，固定 current_conversation；last_user_message 选填	data.hints[] 提示；data.missing_dimensions[] 缺失维度；data.next_questions[] 下一步问题；data.recommended_orders[] 推荐检查

说明：当前前端主要使用流式提示接口，结构化提示接口作为备用能力保留。

4.5 体格检查

接口名称	url	api	methods	params（入参）	response（返回参数）
体格检查列表获取	http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/physical-exams	/api/v1/sessions/{session_id}/physical-exams	GET	Path：session_id 必填，会话 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 必填，例如 lung_auscultation	data.item_code 检查编码；data.item_name 检查名称；data.item_type 检查类型；data.result_text 检查结果；data.result_structured 结构化结果；data.is_key 是否关键检查；data.is_abnormal 是否异常；data.already_ordered 是否已申请；data.context_written 是否写入上下文

4.6 辅助检查

接口名称	url	api	methods	params（入参）	response（返回参数）
辅助检查列表获取	http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/auxiliary-exams	/api/v1/sessions/{session_id}/auxiliary-exams	GET	Path：session_id 必填，会话 ID	data.items[] 当前病例可用辅助检查项；每项包含 item_code、item_name、item_type
辅助检查某项结果	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 必填，例如 blood_routine、crp、chest_xray、oxygen_saturation	data.item_code 检查编码；data.item_name 检查名称；data.item_type 检查类型；data.result_text 检查结果；data.result_structured 结构化结果；data.is_key 是否关键检查；data.is_abnormal 是否异常；data.already_ordered 是否已申请；data.context_written 是否写入上下文

说明：检查结果只来自数据库 case_exam_item，不会由 LLM 编造。同一会话重复申请同一 item_code 时后端幂等返回已有结果。

4.7 阶段提交

接口名称	url	api	methods	params（入参）	response（返回参数）
完成问诊	http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/complete-inquiry	/api/v1/sessions/{session_id}/complete-inquiry	POST	Path：session_id 必填，会话 ID	data.session_id 会话 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 必填，主要诊断；differential_diagnoses 选填，鉴别诊断数组；diagnosis_basis 必填，诊断依据	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

诊断提交示例：

{
  "primary_diagnosis": "支气管肺炎",
  "differential_diagnoses": ["毛细支气管炎", "支气管哮喘急性发作", "上呼吸道感染"],
  "diagnosis_basis": "患儿发热、咳嗽、喘息，肺部湿啰音，炎症指标升高，胸片提示肺部感染，符合儿童支气管肺炎表现。"
}

治疗提交示例：

{
  "treatment_principle": "抗感染、止咳平喘、改善氧合、严密观察病情变化。",
  "treatment_measures": "根据病情选择抗感染治疗，必要时雾化吸入缓解喘息，监测体温、呼吸、血氧和精神反应。",
  "risk_plan": "关注低氧、呼吸困难加重、持续高热、精神反应差、脱水等情况。",
  "communication": "向家属说明肺炎病情、用药注意事项、观察指标和复诊或住院指征。",
  "follow_up": "治疗后复查体温、呼吸、血氧和必要炎症指标，症状加重时及时就诊。"
}

4.8 训练模式生成评价

接口名称	url	api	methods	params（入参）	response（返回参数）
训练模式生成评价	http://8.160.178.88/fastapi/api/v1/sessions/{session_id}/evaluation	/api/v1/sessions/{session_id}/evaluation	POST	Path：session_id 必填，会话 ID；Body：score_type 选填，percentage 或 five_point	data.evaluation_id 评价 ID；data.score_type 分数类型；data.total_score 总分；data.dimension_scores[] 维度评分；data.score_details[] 评分明细；data.errors[] 问题；data.improvement_plan[] 改进建议；data.overall_comment 总评

请求示例：

{
  "score_type": "percentage"
}

4.9 训练模式获取评价详情

接口名称	url	api	methods	params（入参）	response（返回参数）
训练模式获取评价详情	http://8.160.178.88/fastapi/api/v1/evaluations/{evaluation_id}	/api/v1/evaluations/{evaluation_id}	GET	Path：evaluation_id 必填，训练模式生成评价后返回的评价 ID	data.session_id 会话 ID；data.case_id 病例 ID；data.case_title 病例标题；data.total_score 总分；data.dimension_scores[] 维度评分；data.score_details[] 评分明细；data.pdf_file_path PDF 路径

说明：该接口底层与教学互动评价详情复用，但训练页面应按训练模式评价详情使用。

4.10 训练模式下载 PDF

接口名称	url	api	methods	params（入参）	response（返回参数）
训练模式下载 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 必填，训练模式评价 ID	application/pdf 文件流，浏览器可直接下载

前端下载示例：

async function downloadTrainingPdf(baseUrl: string, token: string, evaluationId: number) {
  const response = await fetch(`${baseUrl}/api/v1/evaluations/${evaluationId}/download-pdf`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${token}`,
      "X-Entry-Scene": "vue_frontend",
    },
  });
  if (!response.ok) throw new Error("PDF 下载失败");
  const blob = await response.blob();
  const url = URL.createObjectURL(blob);
  const link = document.createElement("a");
  link.href = url;
  link.download = `training-evaluation-${evaluationId}.pdf`;
  link.click();
  URL.revokeObjectURL(url);
}

5. 教学互动 API

本节用于教学互动页面。教学互动不走训练问诊会话，不调用 POST /api/v1/sessions。前端先获取教学题列表，用户答题后直接生成教学互动评价。

5.1 获取教学列表

接口名称	url	api	methods	params（入参）	response（返回参数）
教学互动获取教学列表	http://8.160.178.88/fastapi/api/v1/teaching/cases/{case_id}/items	/api/v1/teaching/cases/{case_id}/items	GET	Path：case_id 必填，病例 ID	data.case 病例摘要；data.teaching_goal 教学目标；data.teacher_guide 教学指导；data.scoring_focus 评分重点；data.questions[] 题目列表，包含题干、选项、答案、解析文本和视频

data.questions[] 字段：

字段	说明
question_id	题目 ID
question_type	题型，当前多为 single_choice
stem	题干
options[]	选项数组，包含 key 和 text
answer	标准答案
analysis	解析文本
video	教学视频，包含 title 和 url
knowledge_points[]	知识点

5.2 教学互动生成评价

接口名称	url	api	methods	params（入参）	response（返回参数）
教学互动生成评价	http://8.160.178.88/fastapi/api/v1/teaching/evaluation	/api/v1/teaching/evaluation	POST	Body：case_id 必填，病例 ID；answers[] 必填，作答数组；score_type 选填，percentage 或 five_point	data.evaluation_id 评价 ID；data.session_id 教学互动内部会话 ID；data.total_score 总分；data.dimension_scores[] 维度评分；data.score_details[] 评分明细；data.errors[] 错误项；data.improvement_plan[] 改进建议

请求示例：

{
  "case_id": 1,
  "score_type": "percentage",
  "answers": [
    {
      "question_id": "q1",
      "selected_answer": "A"
    },
    {
      "question_id": "q2",
      "selected_answer": "C"
    }
  ]
}

5.3 教学互动获取评价详情

接口名称	url	api	methods	params（入参）	response（返回参数）
教学互动获取评价详情	http://8.160.178.88/fastapi/api/v1/evaluations/{evaluation_id}	/api/v1/evaluations/{evaluation_id}	GET	Path：evaluation_id 必填，教学互动生成评价后返回的评价 ID	data.session_id 教学互动内部会话 ID；data.case_id 病例 ID；data.case_title 病例标题；data.total_score 总分；data.dimension_scores[] 维度评分；data.score_details[] 评分明细；data.pdf_file_path PDF 路径

说明：该接口底层与训练模式评价详情复用，但教学互动页面应按教学互动评价详情使用。

5.4 教学互动下载 PDF

接口名称	url	api	methods	params（入参）	response（返回参数）
教学互动下载 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 必填，教学互动评价 ID	application/pdf 文件流，浏览器可直接下载

前端下载示例：

async function downloadTeachingPdf(baseUrl: string, token: string, evaluationId: number) {
  const response = await fetch(`${baseUrl}/api/v1/evaluations/${evaluationId}/download-pdf`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${token}`,
      "X-Entry-Scene": "vue_frontend",
    },
  });
  if (!response.ok) throw new Error("PDF 下载失败");
  const blob = await response.blob();
  const url = URL.createObjectURL(blob);
  const link = document.createElement("a");
  link.href = url;
  link.download = `teaching-evaluation-${evaluationId}.pdf`;
  link.click();
  URL.revokeObjectURL(url);
}

6. 个人中心 API

个人中心用于展示当前用户已经完整生成评价的训练记录和教学互动记录。

接口名称	url	api	methods	params（入参）	response（返回参数）
训练记录列表	http://8.160.178.88/fastapi/api/v1/evaluations?page=1&page_size=10	/api/v1/evaluations	GET	Query：page 选填，页码，从 1 开始，默认 1；page_size 选填，每页数量，1-100，默认 10	data.items[] 当前用户完整训练后的评价记录；data.pagination.page 当前页；data.pagination.page_size 每页数量；data.pagination.total 总数；data.pagination.total_pages 总页数；data.pagination.has_next 是否有下一页；data.pagination.has_prev 是否有上一页
训练记录详情 / 评价详情	http://8.160.178.88/fastapi/api/v1/evaluations/{evaluation_id}	/api/v1/evaluations/{evaluation_id}	GET	Path：evaluation_id 必填，评价 ID	完整评价详情，训练模式和教学互动共用

7. AI 学习助手 API

该模块用于普通用户医学知识问答。前端点击 AI 学习助手入口后，先创建短期会话，再使用会话式 SSE 接口问答。后端优先检索本机构知识库；如果机构知识库未初始化、Milvus / embedding 暂不可用或未命中来源，接口仍会继续调用 LLM，回答开头会声明“未检索到本机构知识库参考，以下为大模型通用学习回答”。

学习助手会话保存在 Redis 短期缓存中，默认 TTL 为 7200 秒；该会话只用于当前学习问答上下文，不写入训练记录。

接口名称	url	api	methods	params（入参）	response（返回参数）
AI 学习助手新建会话	http://8.160.178.88/fastapi/api/v1/learning-assistant/sessions	/api/v1/learning-assistant/sessions	POST	Header：Authorization 必填，Bearer <access_token>；X-Entry-Scene 建议填。Body：title 选填，会话标题，最大 100 字	data.assistant_session_id 学习助手会话 ID；data.user_id 当前用户 ID；data.institution_id 当前机构 ID；data.institution_name 当前机构名称；data.title 会话标题；data.status 会话状态；data.expires_in_seconds 会话过期时间
AI 学习助手会话式流式问答	http://8.160.178.88/fastapi/api/v1/learning-assistant/sessions/{assistant_session_id}/chat/stream	/api/v1/learning-assistant/sessions/{assistant_session_id}/chat/stream	POST	Path：assistant_session_id 必填，新建会话接口返回。Body：question 必填，1-1000 字；top_k 选填，1-10，默认使用后端配置；score_threshold 选填，0-1，默认使用后端配置	SSE：session_ready 会话就绪；retrieval_done 检索状态和来源；answer_delta 回答增量；answer_done 完成事件；error 错误事件

新建会话请求示例：

{
  "title": "儿科肺炎知识复习"
}

新建会话返回示例：

{
  "code": "OK",
  "message": "success",
  "data": {
    "assistant_session_id": "las_2e2f4a6b8d4b4f0ba31731a814c1c5b8",
    "user_id": "37",
    "institution_id": 1,
    "institution_name": "某医院",
    "title": "儿科肺炎知识复习",
    "status": "active",
    "created_at": "2026-06-11T12:00:00Z",
    "updated_at": "2026-06-11T12:00:00Z",
    "expires_in_seconds": 7200
  }
}

会话式流式问答请求示例：

{
  "question": "支气管肺炎的典型临床表现有哪些？",
  "top_k": 5,
  "score_threshold": 0.35
}

会话式 SSE 返回示例：

event: session_ready
data: {"assistant_session_id":"las_xxx","status":"active","history_count":0}

event: retrieval_done
data: {"assistant_session_id":"las_xxx","retrieval_hit":true,"sources":[{"document_id":1,"document_title":"诊断学","file_name":"诊断学.pdf","page_start":12,"page_end":12,"chunk_uid":"chunk_001","score":0.82,"quote":"..."}],"retrieval_error":null}

event: answer_delta
data: {"assistant_session_id":"las_xxx","delta":"支气管肺炎常见表现包括..."}

event: answer_done
data: {"assistant_session_id":"las_xxx","model":"deepseek-chat","total_latency_ms":1800,"llm_latency_ms":1600}

8. 内容管理员知识库 API

该组接口是后台内容管理员能力，学生端不展示上传入口。当前阶段保留接口和数据结构，后续生产环境接入完整 PDF 解析、分片、embedding、Milvus 构建和异步任务。

接口名称	url	api	methods	params（入参）	response（返回参数）
上传知识库 PDF	http://8.160.178.88/fastapi/api/v1/knowledge-admin/documents/upload	/api/v1/knowledge-admin/documents/upload	POST	multipart/form-data：file 必填，PDF 文件；document_title 选填，文档标题；document_category 选填，textbook、guideline、manual、other；version 选填，默认 v1	data.document_id 文档 ID；data.task_id 任务 ID；data.status 文档状态；data.parse_status 解析状态；data.embedding_status 向量状态；data.chunk_count 分片数；data.collection_name Milvus 集合
知识库文档列表	http://8.160.178.88/fastapi/api/v1/knowledge-admin/documents	/api/v1/knowledge-admin/documents	GET	Header：内容管理员 token	data.items[] 本机构上传文档
知识库文档详情	http://8.160.178.88/fastapi/api/v1/knowledge-admin/documents/{document_id}	/api/v1/knowledge-admin/documents/{document_id}	GET	Path：document_id 必填；Header：内容管理员 token	文档构建状态、分片数、错误信息

9. 健康检查 API

接口名称	url	api	methods	params（入参）	response（返回参数）
存活检查	http://8.160.178.88/fastapi/health/live	/health/live	GET	无需认证	服务存活状态
就绪检查	http://8.160.178.88/fastapi/health/ready	/health/ready	GET	无需认证	服务就绪状态，包含配置、数据库、Redis 等检查结果

10. 常见错误码

HTTP 状态	code	含义
401	AUTH_CREDENTIAL_REQUIRED	缺少 Authorization
401	AUTH_USER_INVALID	token 无效、过期或 Django 返回非 200
403	AUTH_USER_DISABLED	Django 用户状态被禁用
403	KNOWLEDGE_ADMIN_FORBIDDEN	当前用户不是内容管理员，不能使用后台知识库上传接口
404	CASE_NOT_FOUND	病例不存在、未发布或已停用
404	SESSION_NOT_FOUND	会话不存在或不属于当前用户
400	SESSION_STATUS_INVALID	当前状态不允许执行该操作
404	ORDER_ITEM_NOT_FOUND	当前病例不存在该检查项
400	ORDER_ITEM_TYPE_MISMATCH	体格检查 / 辅助检查接口与检查项类型不匹配
404	EVALUATION_NOT_FOUND	评价不存在或不属于当前用户
404	LEARNING_ASSISTANT_SESSION_NOT_FOUND	AI 学习助手会话不存在、已过期或不属于当前用户
400	LEARNING_ASSISTANT_SESSION_INVALID	AI 学习助手会话状态不可用
502	LLM_STREAM_FAILED	LLM 流式调用失败
503	AUTH_USER_CENTER_UNAVAILABLE	Django 用户中心超时或不可达