# 开发维护指南

本文档面向后续开发和运维人员，说明当前 FastAPI 后端的维护重点、发布检查、风险项和排查路径。

## 1. 维护目标

当前项目已经具备训练页面、教学互动、个人中心训练记录、PDF 报告、AI 学习助手和知识库预留链路。后续维护应优先保持以下原则：

- 不改变已稳定 API 的语义。
- 不把业务逻辑写入 API router。
- 不在 FastAPI 中实现登录注册。
- 不让 LLM 编造检查检验结果。
- 不长期保存完整问诊聊天记录。
- 不提交 `.env`、token、API Key、日志、PDF 生成物。

## 2. 重点维护模块

| 模块 | 代码入口 | 维护重点 |
|---|---|---|
| 用户鉴权 | `app/services/external_auth_service.py` | Django `/me` 地址、Authorization 透传、用户字段标准化 |
| 训练会话 | `app/services/session_service.py` | 状态流转、Redis memory、Patient Agent 调用 |
| 检查申请 | `app/services/order_service.py` | 数据库检查项、幂等写入、结果写入 memory |
| 评价生成 | `app/services/evaluation_service.py` | 评分规则、评分明细、PDF 数据结构 |
| 教学互动 | `app/services/teaching_service.py` | 教学题读取、答案评分、训练记录复用 |
| 个人中心 | `app/api/evaluations.py` | 分页、user_id 隔离、PDF 下载 |
| 学习助手 | `app/services/learning_assistant_service.py` | RAG 检索、来源引用、流式输出 |
| 知识库 | `app/services/document_ingestion_service.py` | 内容管理员权限、PDF 解析、embedding、Milvus |

## 3. 发布前检查清单

```powershell
.\backend\.venv\Scripts\python.exe -m compileall app scripts tests
.\backend\.venv\Scripts\python.exe tests\test_core_logic.py
.\backend\.venv\Scripts\python.exe tests\test_demo_flow.py
.\backend\.venv\Scripts\python.exe tests\test_api_contract.py
.\backend\.venv\Scripts\python.exe scripts\check_final_demo_readiness.py
```

通过标准：

- Python 编译无错误。
- 核心逻辑测试通过。
- Demo 流程测试通过。
- API 契约测试通过。
- 就绪检查 `ready=true`。

## 4. 数据库维护说明

FastAPI 当前依赖平台合并后的数据库，核心表包括：

- `user`
- `institution`
- `department`
- `case_base`
- `traditional_case`
- `teaching_case`
- `case_exam_item`
- `scoring_rule`
- `training_session`
- `training_order`
- `training_submission`
- `training_record`
- `training_score_detail`
- `audit_logs`
- `prompt_templates`
- `kb_spaces`
- `kb_documents`
- `kb_chunks`
- `kb_query_logs`

生产并发前需要重点确认推荐索引：

- `case_base.case_type`
- `case_base.difficulty`
- `case_base.publish_status`
- `case_base.status`
- `scoring_rule.dimension`
- `scoring_rule.competency_dimension`
- `training_score_detail.dimension`

## 5. Redis 维护说明

Redis 用于训练会话短期 memory，不作为长期训练记录保存。

生命周期：

1. 创建训练会话时写入开场消息。
2. 流式问诊时写入医生问题和 AI 病人回复。
3. 申请检查时写入工具结果。
4. 生成评价后释放当前会话 memory。
5. 未完成训练依赖 TTL 自动过期。

## 6. LLM 和提示词维护说明

提示词模板说明见 [09_prompt_template_catalog.md](09_prompt_template_catalog.md)。

维护规则：

- Patient Agent 只回答患者或家属视角，不输出诊断和治疗方案。
- Hint Agent 用于练习提示，不能直接给完整答案。
- Scoring Agent 必须输出可解析 JSON。
- Report Agent 只整理报告，不重新评分。
- Learning Assistant 命中知识库时必须引用 PDF 来源和页码；未命中时必须声明未检索到机构知识库参考。

## 7. 常见风险

| 风险 | 表现 | 处理 |
|---|---|---|
| Django 鉴权失败 | `AUTH_CREDENTIAL_REQUIRED` 或 `AUTH_INVALID` | 检查 token、`AUTH_USER_ME_URL`、Django 服务 |
| 问诊流式卡住 | 前端一直等待 SSE | 检查 LLM Key、Base URL、模型名、超时配置 |
| 检查项为空 | 前端无体格/辅助检查 | 检查 `case_exam_item.case_id` 和 `item_type` |
| 评价失败 | 无法生成报告 | 检查 `scoring_rule`、提交内容、LLM JSON 输出 |
| PDF 下载失败 | 文件不存在或 404 | 检查 `REPORT_STORAGE_DIR` 和文件权限 |
| 学习助手无来源 | `retrieval_hit=false` | 检查知识库表、Milvus、embedding 配置 |

## 8. 开发规范

- API 层只做参数接收、用户上下文获取和响应封装。
- Service 层承载业务流程。
- Repository 层只做数据库读写。
- Agent 层只做提示词拼接、LLM 调用和输出校验。
- Model 层只定义 ORM。
- Schema 层只定义 Pydantic 入参/出参。
- 新增接口必须同步更新 `docs/03_api_design.md` 和 `docs/08_feature_code_map.md`。
- 新增提示词必须同步更新 `docs/09_prompt_template_catalog.md`。