# 审计模块详细设计

## 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。