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

docs/设计文档/模块设计/2.场景模块详细设计.md

@@ -0,0 +1,134 @@
+# 场景模块详细设计
+
+## 1. 模块目标
+
+Scenarios 模块是业务 Agent 的入口，负责读取和展示场景配置，并向 Chat、Documents、Agent Core 提供场景上下文。
+
+## 2. 职责边界
+
+负责：
+
+- 从 `configs/*.yaml` 读取场景。
+- 校验场景必填字段。
+- 展示场景列表和场景摘要。
+- 提供 `list_scenarios()`、`get_scenario()` 等服务。
+
+不负责：
+
+- 不执行 Agent。
+- 不做 RAG 检索。
+- 不调用工具和大模型。
+- 不保存审计日志。
+
+## 3. 场景配置结构
+
+必填结构：
+
+```yaml
+id: knowledge_qa
+name: 知识库问答助手
+description: 用于 SOP、制度和内部知识库问答
+applicable_questions:
+  - SOP 问答
+  - 制度问答
+
+agent:
+  role: 知识库问答专家
+  goal: 基于知识库回答用户问题
+  system_prompt: ""
+  instructions:
+    - 回答必须基于检索内容
+
+rag:
+  enabled: true
+  collection: knowledge_qa
+  top_k: 5
+
+tools:
+  - generate_action_items
+
+output:
+  type: general_answer
+
+audit:
+  enabled: true
+```
+
+`agent.system_prompt` 为可选字段。配置了非空值时，Agent Core 优先使用该字段作为系统提示词；为空或缺失时，由 `role`、`goal` 和 `instructions` 组合生成系统提示词。
+
+`applicable_questions` 作为页面展示字段，若缺失可显示为空列表。
+
+## 4. 场景加载流程
+
+1. 读取 `settings.SCENARIO_CONFIG_DIR`。
+2. 遍历 `.yaml` 和 `.yml` 文件。
+3. 使用 YAML parser 转为 dict。
+4. 调用 `validate_scenario()`。
+5. 转换为 `ScenarioConfig` dataclass 或普通 dict。
+6. 按文件名或配置顺序返回。
+
+为了便于复试修改，V1 不需要强缓存；若加缓存，应提供清理方式或在 DEBUG 下禁用缓存。
+
+## 5. 场景校验规则
+
+必填字段：
+
+- `id`
+- `name`
+- `description`
+- `agent.role`
+- `agent.goal`
+- `agent.instructions`
+- `rag.enabled`
+- `tools`
+- `output.type`
+- `audit.enabled`
+
+校验失败时返回包含文件名、字段路径、错误原因的结果。列表页可以跳过非法场景并展示错误摘要。
+
+## 6. 页面设计
+
+首页路径：`/`
+
+展示：
+
+- 场景名称。
+- 场景描述。
+- 适用题型。
+- RAG 是否启用。
+- 工具数量。
+- 进入对话按钮。
+
+可选详情页：`/scenarios/<scenario_id>/`。V1 可以把详情合并到 Chat 页面。
+
+## 7. 服务函数设计
+
+```python
+def list_scenarios() -> list[ScenarioConfig]:
+    """读取配置目录中的合法场景，非法场景以错误摘要返回给页面。"""
+
+def get_scenario(scenario_id: str) -> ScenarioConfig:
+    """按场景 ID 返回完整配置，找不到时抛出 ScenarioNotFound。"""
+
+def validate_scenario(config: dict) -> ValidationResult:
+    """校验必填字段、字段类型、工具名称和输出类型。"""
+```
+
+`get_scenario()` 找不到时抛出业务异常，例如 `ScenarioNotFound`，由 View 转成中文错误提示。
+
+## 8. 异常处理
+
+| 异常 | 处理 |
+|---|---|
+| 配置目录不存在 | 返回空列表和错误提示 |
+| YAML 语法错误 | 标记该文件无效 |
+| ID 重复 | 保留第一个，报告重复错误 |
+| 必填字段缺失 | 标记该场景无效 |
+| 工具不存在 | 场景仍可展示，但 Chat 执行时记录工具错误 |
+
+## 9. 验收标准
+
+- 首页至少展示 5 个场景。
+- 场景配置来自 `configs/` 文件。
+- 非法配置有明确错误，不导致首页 500。
+- Chat 可通过 `scenario_id` 获取完整配置。