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

docs/设计文档/模块设计/4.对话模块详细设计.md

@@ -0,0 +1,118 @@
+# 对话模块详细设计
+
+## 1. 模块目标
+
+Chat 模块负责复试演示中的主交互：用户选择场景后提交问题，系统展示 Agent 输出、引用、工具调用和审计入口。
+
+## 2. 职责边界
+
+负责：
+
+- 对话页 GET/POST。
+- 用户输入表单校验。
+- 获取场景配置。
+- 调用 Agent Core。
+- 调用 Audit 服务写日志。
+- 渲染 AgentResult。
+
+不负责：
+
+- 不直接读取 YAML。
+- 不直接调用 LLM。
+- 不直接执行 RAG 和工具。
+- 不实现复杂多轮会话状态。
+
+## 3. 页面设计
+
+路径：`/chat/<scenario_id>/`
+
+GET：
+
+- 加载场景配置。
+- 展示场景摘要。
+- 加载当前场景下状态为 `indexed` 的文档列表。
+- 展示空表单。
+
+POST：
+
+- 校验输入。
+- 执行 Agent。
+- 写审计。
+- 展示结果和审计链接。
+
+## 4. 表单设计
+
+字段：
+
+| 字段 | 类型 | 规则 |
+|---|---|---|
+| `message` | textarea | 必填，最大 4000 字 |
+| `document_ids` | 多选 | 可选，只能选择当前场景下已入库文档 |
+
+错误提示：
+
+- 空输入：`请输入要咨询的问题。`
+- 超长输入：`问题过长，请控制在 4000 字以内。`
+- 文档不属于当前场景或未入库：`请选择当前场景下已入库的文档。`
+
+## 5. Agent Core 调用流程
+
+```python
+scenario = get_scenario(scenario_id)
+result = run_agent(
+    scenario_config=scenario,
+    user_input=form.cleaned_data["message"],
+    options={"document_ids": form.cleaned_data.get("document_ids", [])}
+)
+```
+
+Chat 只依赖 Agent Core 的统一返回对象，不关心内部是否使用 RAG、工具或真实模型。
+
+未选择文档时，`document_ids` 传空列表或不传，由 Agent Core 默认使用当前场景全部已入库文档。
+
+## 6. 结果展示设计
+
+优先级：
+
+1. 如果 `structured_output` 不为空，展示结构化 JSON 或字段化结果。
+2. 展示 `answer`。
+3. 展示 `references`。
+4. 展示 `tool_calls`。
+5. 展示 `latency_ms`、`model_name`、`status`。
+6. 如果有 `error`，展示中文错误提示。
+
+结构化解析失败时，页面仍展示 `raw_output` 或 `answer`。
+
+## 7. 审计日志写入流程
+
+Agent Core 返回后调用：
+
+```python
+audit_log = create_audit_log(
+    scenario_id=scenario.id,
+    scenario_name=scenario.name,
+    user_input=message,
+    agent_result=result,
+)
+```
+
+如果 Agent Core 抛异常，Chat 应构造失败结果并继续写失败审计。
+
+## 8. 异常处理
+
+| 异常 | 处理 |
+|---|---|
+| 场景不存在 | 显示错误并返回首页入口 |
+| 表单无效 | 留在页面并显示表单错误 |
+| Agent Core 抛异常 | 构造 failed AgentResult，写审计 |
+| 审计写入失败 | 页面提示审计失败，但展示 Agent 输出 |
+| LLM 配置缺失 | 展示模型配置缺失 |
+
+## 9. 验收标准
+
+- 从首页可进入对话页。
+- 可提交问题并渲染 AgentResult。
+- 可选择本次对话使用的文档范围；未选择时默认使用当前场景全部已入库文档。
+- 失败时有中文提示。
+- 成功和失败都尽量写入审计。
+- View 中没有 RAG、工具、LLM 的细节实现。