# 系统架构说明

本文档用于交接医疗问诊 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. 总体架构

```mermaid
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. 用户鉴权链路

```mermaid
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. 训练链路

```mermaid
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. 教学互动链路

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

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

## 7. AI 学习助手链路

```mermaid
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"]
```

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

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

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

## 8. 后台知识库预留链路

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

```mermaid
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 不在本仓库维护。