刘金宝
126 lines
4.7 KiB
Markdown
126 lines
4.7 KiB
Markdown
# 开发维护指南
|
|
|
|
本文档面向后续开发和运维人员，说明当前 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`。
|