docs(design): 补全中文设计文档体系

docs/设计文档/2.功能流程设计.md

@@ -0,0 +1,169 @@
+# V1 功能设计文档
+
+## 1. 功能设计目标
+
+V1 的功能设计目标是让复试展示者在本地快速完成一个可讲解、可演示、可改题的 Agent Demo。系统不追求复杂平台能力，而是优先保证以下闭环稳定：
+
+- 场景配置可选择。
+- 文档可上传并入库。
+- 用户可在场景下发起对话。
+- Agent 可返回结构化结果、引用来源和工具调用记录。
+- 每次成功或失败的对话都有审计记录。
+- 本地和 Docker 均可启动。
+
+## 2. 用户角色
+
+V1 仅设计一个用户角色：Demo 操作者。
+
+该角色负责启动系统、选择场景、上传材料、触发入库、发起对话、查看输出和审计日志。系统不在 V1 中区分管理员、审核员、普通用户等权限角色。
+
+## 3. 核心业务流程
+
+```text
+启动系统
+  ↓
+查看 5 个预置场景
+  ↓
+选择场景
+  ↓
+上传题目材料
+  ↓
+触发知识库入库
+  ↓
+发起 Agent 对话
+  ↓
+查看结构化输出、引用和工具调用
+  ↓
+查看审计日志
+```
+
+任一环节失败时，页面应给出明确提示，并尽量保留用户已完成的上下文。
+
+## 4. 场景选择流程
+
+1. 首页调用 `apps.scenarios.services.list_scenarios()`。
+2. 服务从 `configs/` 读取 YAML 场景配置。
+3. 校验必填字段、工具名称和输出类型。
+4. 页面展示场景名称、描述、适用题型、启用状态。
+5. 用户点击进入 `/chat/<scenario_id>/`。
+
+异常处理：
+
+- 配置目录不存在：展示空状态和配置目录提示。
+- 单个配置非法：不阻断其他配置，页面展示该配置错误。
+- 场景不存在：跳转或渲染错误页，提示检查场景 ID。
+
+## 5. 文件上传流程
+
+1. 用户进入 `/documents/upload/`。
+2. 页面加载可用场景下拉框。
+3. 用户选择场景并上传 `.txt`、`.md`、`.pdf` 或 `.docx` 文件。
+4. Documents 模块校验文件类型和大小。
+5. 保存文件到 `UPLOAD_ROOT/<scenario_id>/`。
+6. 写入 `UploadedDocument` 记录，状态为 `uploaded`。
+7. 返回文件列表页并展示上传结果。
+
+V1 文件上传默认手动入库，避免上传大文件时页面阻塞过久。
+
+## 6. 文档入库流程
+
+1. 用户在文件列表点击“入库”。
+2. Documents 模块读取文件并抽取文本。
+3. 调用 `agent_core.rag.ingest.ingest_document()`。
+4. Agent Core 按固定长度切分文本。
+5. 写入本地 Chroma collection。
+6. 入库成功：更新状态为 `indexed`。
+7. 入库失败：更新状态为 `failed`，保存错误信息。
+
+文本为空、文件丢失、向量库不可写都应进入失败状态，不能让页面报 500。
+
+## 7. Agent 对话流程
+
+```text
+用户提交问题
+  ↓
+Chat 表单校验
+  ↓
+Scenarios 加载场景配置
+  ↓
+Agent Core 执行 run_agent()
+  ↓
+RAG 按场景和可选文档范围检索知识片段
+  ↓
+工具系统执行可用工具
+  ↓
+LLM Provider 生成结果
+  ↓
+结构化输出解析
+  ↓
+Audit 写入日志
+  ↓
+Chat 页面展示结果
+```
+
+Chat 模块只负责请求处理和页面展示，不直接写 RAG、工具和模型调用细节。
+
+## 8. RAG 检索流程
+
+1. Orchestrator 读取场景配置中的 `rag.enabled`、`collection`、`top_k`。
+2. 若启用 RAG，则调用 `agent_core.rag.retriever.retrieve()`。
+3. 检索必须按 `scenario_id` 过滤，避免跨场景污染。
+4. 如果用户在对话页选择了文档，则同时按 `document_ids` 过滤；未选择时使用当前场景全部已入库文档。
+5. 返回片段内容、来源文件、chunk ID、分数。
+6. 片段进入 Prompt，同时随 AgentResult 返回给页面和审计日志。
+
+检索失败时，AgentResult 应记录错误或警告；若业务允许，可继续使用非 RAG 上下文回答。
+
+## 9. 工具调用流程
+
+1. 场景配置声明可用工具名称。
+2. Orchestrator 从 Tool Registry 查询工具。
+3. 对不可用工具记录失败，不中断整个流程。
+4. 内置工具按统一参数和返回结构执行。
+5. 工具结果进入 Prompt 或结构化输出上下文。
+6. 所有工具调用写入 AgentResult 和审计日志。
+
+V1 先采用“配置声明 + Orchestrator 决策”的轻量策略，不实现复杂多轮工具调用协议。
+
+## 10. 审计日志流程
+
+1. Chat 模块在 Agent Core 返回后调用 `apps.audit.services.create_audit_log()`。
+2. 成功结果记录输入、输出、引用、工具调用、模型名和耗时。
+3. 失败结果也记录场景、输入、错误信息和已产生的中间结果。
+4. 日志中不得保存 `LLM_API_KEY`、环境变量完整内容或上传文件绝对敏感路径。
+5. 审计列表展示摘要，详情页展示完整 JSON 片段。
+
+## 11. 复试改题流程
+
+1. 判断题目最接近的模板。
+2. 复制 `configs/` 中相近 YAML。
+3. 修改场景名称、角色、目标、指令和输出类型。
+4. 上传题目文档并入库。
+5. 如题目需要计算或查询，新增一个内置工具并在场景中声明。
+6. 用 2 到 3 个问题验证输出和审计链路。
+7. 演示时重点展示配置、知识库、工具调用、结构化结果和审计日志。
+
+## 12. 异常处理流程
+
+| 异常 | 处理方式 |
+|---|---|
+| 场景配置缺失 | 页面展示错误，保留返回首页入口 |
+| 场景字段非法 | 标记非法配置，不影响其他场景 |
+| 上传文件类型不支持 | 表单错误提示 |
+| 文件读取失败 | 文档状态改为 `failed` |
+| RAG 入库失败 | 记录错误信息并允许重试 |
+| LLM 配置缺失 | AgentResult 返回失败，审计日志记录失败 |
+| 工具调用失败 | 记录工具失败，流程尽量继续 |
+| 结构化解析失败 | 展示原始输出并记录解析错误 |
+
+## 13. V1 功能验收标准
+
+- 首页可以展示 5 个预置场景。
+- 场景配置来自 YAML 文件。
+- 可以上传 `.txt`、`.md`、`.pdf` 和 `.docx` 文件。
+- 文件可触发入库，并显示 `uploaded`、`indexed`、`failed` 状态。
+- 可以进入任一场景对话页并提交问题。
+- AgentResult 至少包含回答、结构化输出、引用、工具调用、耗时和状态。
+- 成功和失败对话都能生成审计日志。
+- 审计详情可以解释一次 Agent 输出的输入、依据和过程。
+- 本地启动和 Docker 启动路径清晰可执行。