# /audit — 变更审计

回顾本次会话中你所做的所有文件变更，结合自动预扫描结果，执行审计落盘。

## 执行步骤

### 第 1 步：运行预扫描脚本（Python，零 token）

运行：
```bash
python scripts/audit/prescan.py
```

该脚本自动完成：
- 从 git status 获取所有变更文件
- 分类高风险文件 + 生成 risk_tags
- 合规检查：代码→文档映射、迁移 SQL 检测、DDL 基线检查

读取输出的 JSON。如果 `audit_required: false`，告知用户"无需审计"并结束。

**备选**：如果 git status 包含大量非本次会话的历史变更，可以用 `--files` 参数只传入本次会话的文件：
```bash
python scripts/audit/prescan.py --files "file1.py,file2.sql,..."
```
文件列表从你的对话记忆（本次会话的 Edit/Write 工具调用）中提取。

### 第 2 步：补充语义上下文

预扫描脚本能告诉你"哪些文件变了、是否高风险、文档是否缺失"，但它不知道**为什么改**。

从对话记忆中补充：
- 每个变更文件的修改原因（用户的需求是什么）
- 改动的技术思路和设计决策
- 与其他模块的关联影响

将预扫描 JSON + 语义上下文合并，作为第 3 步的输入。

### 第 3 步：委托子代理写审计记录

用 Agent 工具启动子代理，传入：
1. 预扫描 JSON 结果（完整）
2. 每个变更的原因和内容概要（你补充的语义上下文）

子代理的任务指令：

> 在 `docs/audit/changes/` 目录下创建审计记录文件，文件名格式 `<YYYY-MM-DD>__<英文短标识>.md`。
>
> 使用以下格式：
>
> ```markdown
> # 变更审计记录：<中文标题>
>
> | 字段 | 值 |
> |------|-----|
> | 日期 | YYYY-MM-DD HH:MM:SS |
>
> ## 操作摘要
> <1-3 段，说清楚做了什么、为什么做>
>
> ## 变更文件
> 按新增/修改/删除分组，每个文件一行，简要说明改动内容。
>
> ## 改动注解
> 对每个变更文件写注解：
> - 高风险文件（ETL 任务/后端路由/数据库迁移/金额相关）：写详细注解（变更类型、原因、思路、结果）
> - 普通文件：一行简要说明
> - 删除的文件：只记录删除原因
>
> ## 数据库变更（如有）
> 列出新建/修改/删除的表、字段、约束、索引。标注迁移执行状态。
>
> ## 风险与回滚
> - 风险点（标注高/中/低）
> - 回滚要点
>
> ## 验证
> - 至少 1 条可执行的验证方式（测试命令 / SQL / 联调步骤）
>
> ## 合规检查
> - 列出文档同步状态（已同步 / 待补齐 / 不适用）
> ```
>
> 当前北京时间通过 `python -c "from datetime import datetime, timezone, timedelta; print(datetime.now(timezone(timedelta(hours=8))).strftime('%Y-%m-%d %H:%M:%S'))"` 获取。
>
> 审计记录语言使用简体中文。
>
> 完成后运行 `python scripts/audit/gen_audit_dashboard.py` 刷新审计一览表。
>
> 最终只返回：done / files_written / next_step。

### 第 4 步：补齐缺失的文档同步

根据预扫描 JSON 中 `code_without_docs` 列出的不合规项，逐项补齐：
- 读取对应代码文件当前内容
- 更新对应文档

如果补齐工作量大（>3 个文档），委托子代理处理。

### 第 5 步：向用户报告

简短回执：
- 审计记录文件路径
- 合规检查结果（全部通过 / N 项已补齐 / N 项待用户处理）
- 下一步建议（如 "commit when ready"）