开发维护指南

本文档面向后续开发和运维人员，说明当前 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. 发布前检查清单

.\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，不作为长期训练记录保存。

生命周期：

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

6. LLM 和提示词维护说明

提示词模板说明见 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。

4.7 KiB Raw Blame History