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

docs/设计文档/模块设计/5.审计模块详细设计.md

@@ -0,0 +1,121 @@
+# 审计模块详细设计
+
+## 1. 模块目标
+
+Audit 模块记录 Agent 执行过程，使演示者能够解释一次输出的来源、工具调用和模型结果。它是系统从“普通问答页面”变成“可追踪业务 Agent”的关键。
+
+## 2. 职责边界
+
+负责：
+
+- `AgentAuditLog` 模型。
+- 审计写入服务。
+- 审计列表页。
+- 审计详情页。
+- 敏感信息过滤。
+
+不负责：
+
+- 不执行 Agent。
+- 不执行 RAG。
+- 不执行工具。
+- 不调用模型。
+
+## 3. 数据模型设计
+
+模型：`AgentAuditLog`
+
+字段见 `docs/设计文档/3.数据库设计.md`。
+
+JSON 字段默认值必须使用函数，例如 `default=list`、`default=dict`，避免多实例共享同一对象。
+
+## 4. 日志写入流程
+
+服务函数：
+
+```python
+def create_audit_log(
+    scenario_id: str,
+    scenario_name: str,
+    user_input: str,
+    agent_result: AgentResult,
+) -> AgentAuditLog:
+    """将 AgentResult 映射为 AgentAuditLog，并在保存前做敏感信息脱敏。"""
+```
+
+写入映射：
+
+- `agent_result.references` -> `retrieved_chunks`
+- `agent_result.tool_calls` -> `tool_calls`
+- `agent_result.structured_output` -> `structured_output`
+- `agent_result.answer` -> `final_answer`
+- `agent_result.raw_output` -> `raw_output`
+- `agent_result.model_name` -> `model_name`
+- `agent_result.latency_ms` -> `latency_ms`
+- `agent_result.status` -> `status`
+- `agent_result.error` -> `error_message`
+
+## 5. 日志列表页设计
+
+路径：`/audit/`
+
+查询：
+
+- 默认按创建时间倒序。
+- V1 可不做分页，若日志较多再加 Django Paginator。
+
+展示：
+
+- ID。
+- 场景名称。
+- 用户输入前 80 字。
+- 状态。
+- 模型名。
+- 耗时。
+- 创建时间。
+- 详情链接。
+
+## 6. 日志详情页设计
+
+路径：`/audit/<log_id>/`
+
+展示：
+
+- 基础信息。
+- 用户输入。
+- 最终回答。
+- 结构化输出。
+- RAG 检索片段。
+- 工具调用。
+- 原始输出。
+- 错误信息。
+
+JSON 可用格式化后的 `<pre>` 展示。
+
+## 7. 敏感信息处理
+
+不得保存：
+
+- `LLM_API_KEY`
+- 完整环境变量 dump
+- 用户机器上的敏感绝对路径
+- Docker secret 或 token
+
+如错误信息来自异常对象，应在保存前做简单脱敏，至少替换 API Key 值。
+
+## 8. 异常处理
+
+| 异常 | 处理 |
+|---|---|
+| AgentResult 字段缺失 | 使用默认空值 |
+| JSON 不可序列化 | 转为字符串或空对象 |
+| 日志不存在 | 返回 404 |
+| 写入失败 | 抛给 Chat，由 Chat 展示审计失败提示 |
+
+## 9. 验收标准
+
+- 每次对话成功后有审计日志。
+- Agent 失败也有失败日志。
+- 列表页可查看日志摘要。
+- 详情页可查看输入、输出、引用和工具调用。
+- 日志不包含 API Key。