docs(requirements): 统一需求文档中文命名

docs/需求分析/7.审计模块需求.md

@@ -0,0 +1,143 @@
+# Audit 模块需求文档
+
+## 1. 模块定位
+
+Audit 模块负责记录和展示 Agent 执行过程，是项目体现企业级能力的重要模块。
+
+复试演示时，审计日志用于证明系统不是黑盒问答，而是可以追踪输入、检索、工具调用、模型输出和执行耗时。
+
+## 2. 模块目标
+
+- 记录每次 Agent 对话。
+- 记录 RAG 检索片段。
+- 记录工具调用详情。
+- 记录模型输出和结构化结果。
+- 提供审计日志列表和详情页。
+- 支持按场景查看日志。
+
+## 3. 职责边界
+
+### 3.1 负责
+
+- 审计日志数据模型。
+- 日志写入服务。
+- 日志列表页面。
+- 日志详情页面。
+- 工具调用记录展示。
+- RAG 引用记录展示。
+
+### 3.2 不负责
+
+- 不执行 Agent。
+- 不执行工具调用。
+- 不执行 RAG 检索。
+- 不参与模型生成。
+- 不做复杂权限控制。
+
+## 4. 数据模型需求
+
+建议模型：`AgentAuditLog`
+
+字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | int | 主键 |
+| `scenario_id` | string | 场景 ID |
+| `scenario_name` | string | 场景名称 |
+| `user_input` | text | 用户输入 |
+| `retrieved_chunks` | JSON | 检索片段 |
+| `tool_calls` | JSON | 工具调用记录 |
+| `structured_output` | JSON | 结构化输出 |
+| `final_answer` | text | 最终回答 |
+| `raw_output` | text | 模型原始输出 |
+| `model_name` | string | 模型名称 |
+| `latency_ms` | int | 执行耗时 |
+| `status` | string | `success` / `failed` |
+| `error_message` | text | 错误信息 |
+| `created_at` | datetime | 创建时间 |
+
+## 5. 日志写入需求
+
+Audit 模块需要提供服务函数：
+
+```text
+create_audit_log(
+  scenario_id,
+  scenario_name,
+  user_input,
+  agent_result
+) -> AgentAuditLog
+```
+
+写入规则：
+
+- Agent 成功时，记录完整结果。
+- Agent 失败时，也要记录用户输入、场景和错误信息。
+- RAG 片段和工具调用使用 JSON 保存。
+- 不记录 API Key 等敏感配置。
+
+## 6. 页面需求
+
+### 6.1 审计日志列表页
+
+路径：`/audit/`
+
+展示字段：
+
+- 日志 ID。
+- 场景名称。
+- 用户输入摘要。
+- 状态。
+- 模型名称。
+- 执行耗时。
+- 创建时间。
+- 详情入口。
+
+### 6.2 审计日志详情页
+
+路径：`/audit/<log_id>/`
+
+展示内容：
+
+- 用户输入。
+- 最终回答。
+- 结构化输出。
+- RAG 检索片段。
+- 工具调用记录。
+- 模型名称。
+- 执行耗时。
+- 错误信息。
+
+## 7. 检索片段展示需求
+
+每个引用片段建议包含：
+
+| 字段 | 说明 |
+|---|---|
+| `source` | 来源文件名 |
+| `chunk_id` | 片段 ID |
+| `content` | 片段内容 |
+| `score` | 相似度分数 |
+
+## 8. 工具调用展示需求
+
+每次工具调用建议包含：
+
+| 字段 | 说明 |
+|---|---|
+| `tool_name` | 工具名称 |
+| `arguments` | 调用参数 |
+| `result` | 工具结果 |
+| `success` | 是否成功 |
+| `error` | 错误信息 |
+
+## 9. 验收标准
+
+- 每次对话成功后都会生成审计日志。
+- Agent 执行失败时也会生成失败日志。
+- 审计列表可以查看所有日志。
+- 审计详情可以查看用户输入、检索片段、工具调用和最终输出。
+- 日志中不保存 API Key。
+- 可以根据日志解释一次 Agent 输出的依据。
+