系统架构说明

本文档用于交接医疗问诊 Agent FastAPI 后端的系统边界、核心链路和外部依赖。

1. 项目定位

本项目是医疗教学平台中的 FastAPI 后端子服务，不负责登录注册和用户管理。用户从前端进入医疗问诊 Agent 时携带 Django 用户中心签发的 access_token，FastAPI 调用 Django /api/user/users/me/ 验证用户身份，并使用 Django 返回的 id 作为本服务统一 user_id。

当前已完成并保留的业务模块：

训练页面：训练配置、新建会话、流式问诊、练习提示、检查申请、诊断治疗提交、AI 评价、PDF 下载
教学互动：题目列表、答题评价、评价详情、PDF 下载
个人中心：训练记录列表、训练记录详情
AI 学习助手：流式知识问答，优先 RAG，知识库不可用时降级为通用 LLM 回答
后台预留：内容管理员知识库上传、PDF 解析、分片、Embedding、Milvus、Celery 异步任务

2. 总体架构

flowchart LR
  Vue["Vue 前端"] --> FastAPI["FastAPI 医疗问诊 Agent"]
  FastAPI --> Django["Django 用户中心 /api/user/users/me/"]
  FastAPI --> MySQL["MySQL medical"]
  FastAPI --> Redis["Redis 短期会话 memory"]
  FastAPI --> LLM["OpenAI-compatible LLM"]
  FastAPI --> Milvus["Milvus 向量库"]
  FastAPI --> Storage["storage/reports 和 storage/knowledge"]

3. 代码分层

目录	职责
`app/api`	FastAPI 路由层，只做参数接收、依赖注入和响应返回
`app/schemas`	Pydantic 入参和出参模型
`app/services`	业务流程编排，例如会话、评价、PDF、学习助手
`app/repositories`	数据库读写封装
`app/models`	SQLAlchemy ORM 模型
`app/agents`	LLM Agent、评分、报告、病人、学习助手
`app/integrations`	外部适配器：PDF、Embedding、Milvus
`app/core`	配置、响应、异常、上下文、用户鉴权依赖
`app/db`	数据库连接
`app/tasks`	Celery 异步任务预留
`app/prompts`	Markdown 提示词模板
`tests`	核心逻辑、Demo 流程、API 合约测试

4. 用户鉴权链路

sequenceDiagram
  participant FE as Vue 前端
  participant API as FastAPI
  participant DJ as Django 用户中心
  FE->>API: Authorization: Bearer access_token
  API->>DJ: GET /api/user/users/me/
  DJ-->>API: 用户信息 / 401
  API-->>FE: data.user_id / role / institution_id

关键点：

FastAPI 不解析和签发 token。
用户身份以 Django 返回为准。
user_id 使用 Django user.id。
业务接口通过 Authorization 和 X-Entry-Scene 进入上下文。

5. 训练链路

flowchart TD
  A["获取病例和训练配置"] --> B["创建 training_session"]
  B --> C["Redis 初始化短期 memory"]
  C --> D["流式问诊 Patient Agent"]
  D --> E["申请体格/辅助检查"]
  E --> F["完成问诊"]
  F --> G["提交诊断"]
  G --> H["提交治疗"]
  H --> I["Scoring Agent 生成评价"]
  I --> J["写入 training_record 和 score_detail"]
  J --> K["生成 / 下载 PDF"]

注意：

问诊过程只作为短期 memory，不作为长期聊天历史保存。
检查结果只来自数据库，不由 LLM 编造。
只有完整训练结束后写入训练记录。

6. 教学互动链路

flowchart TD
  A["读取 case_base + teaching_case"] --> B["返回题目、选项、答案、解析、视频"]
  B --> C["前端提交答题结果"]
  C --> D["教学互动评价"]
  D --> E["写入训练记录和评分明细"]
  E --> F["评价详情 / PDF 下载"]

当前教学题数据由数据库维护；如数据库暂无完整题目，可由种子数据或后台维护补齐。

7. AI 学习助手链路

flowchart TD
  A["用户提问"] --> B["按 institution_id 定位知识空间"]
  B --> C{"知识库可用?"}
  C -- 是 --> D["Embedding 用户问题"]
  D --> E["Milvus 检索 chunks"]
  E --> F["拼接来源和问题"]
  C -- 否 --> G["空来源降级"]
  F --> H["LLM 流式回答"]
  G --> H
  H --> I["SSE: retrieval_done / answer_delta / answer_done"]

当前正式前端接口只使用：

POST /api/v1/learning-assistant/chat/stream

知识库不可用时不会阻断回答，接口会返回 retrieval_hit=false 和 retrieval_error，随后继续输出通用 LLM 回答。

8. 后台知识库预留链路

后台内容管理员能力，学生端不展示入口：

flowchart TD
  A["内容管理员上传 PDF"] --> B["保存文档元数据"]
  B --> C["解析 PDF"]
  C --> D["语义分片"]
  D --> E["Embedding"]
  E --> F["写入 Milvus"]
  F --> G["写入 MySQL chunk 元数据"]

生产级后续重点：

大文件上传限制和进度
PDF 解析质量校验
分片策略调优
Embedding 批量重试
Milvus collection 生命周期管理
Celery 任务监控和失败重试

9. 当前生产化风险

部分知识库能力是生产预留接口，真实大规模 PDF 入库仍需压测。
Milvus、Embedding、Celery 需要运维侧监控。
LLM 调用需要进一步完善限流、重试、熔断和成本统计。
PDF 报告样式可继续优化。
前端最终 UI 不在本仓库维护。

5.1 KiB Raw Blame History Unescape Escape