89 lines
4.4 KiB
Markdown
89 lines
4.4 KiB
Markdown
# 第 13 轮工作计划（轻量合并版）：审计合规导出与保留脱敏
|
||
|
||
更新日期：2026-08-01
|
||
|
||
## 1. 本轮目标
|
||
|
||
新增审计合规导出：`GET /api/gov/audit/export?format=json|csv` 导出当前作用域全部审计事件（含链校验与锚定状态摘要），导出时对敏感字段（token/password/secret/key/authorization 等）脱敏；黄金测试证明导出完整、脱敏生效、格式可解析；矩阵 104 行剩余项（保留脱敏、合规导出）落地。
|
||
|
||
## 2. 背景和当前状态
|
||
|
||
- 当前已完成：世界内 SHA-256 链（audit.py）、独立介质锚定（audit_ledger.py）、事件镜像（audit_mirror.py）、`/api/gov/audit` 展示链/锚定/镜像状态。
|
||
- 当前缺口：无导出端点；无保留脱敏（导出可能含 confirmId、用户信息等敏感字段）。
|
||
- 本轮为什么现在做：矩阵 104 行剩余「保留脱敏、合规导出」；纯本地、低风险。
|
||
- Workspace preflight：第 12 轮收口（479 passed）；服务 8003/5173 正常；共享脏工作区、无提交。
|
||
- 方向分析：Q1 推荐（审计合规导出/脱敏），目标续跑轮授权执行。
|
||
|
||
## 3. 本轮工作方向
|
||
|
||
```text
|
||
audit 事件仅内页展示，无导出/脱敏
|
||
-> audit_export.py：sanitize_event（敏感键脱敏）+ export_events(events, fmt=json|csv)
|
||
-> GET /api/gov/audit/export?format=...（含 chain/anchor 摘要）
|
||
-> 黄金测试：导出完整、脱敏生效、json/csv 可解析
|
||
-> 矩阵 104 行注记；CHANGELOG
|
||
```
|
||
|
||
## 4. 已确认决策
|
||
|
||
任务重量：
|
||
- 档位：轻型（audit_export 模块 + 网关端点 + 黄金测试）。
|
||
- 规模依据：新增独立模块与端点，不改既有审计写入；风险 LOW。
|
||
- 选择原因：矩阵 104 行明确剩余项之一；合规导出是审计闭环的收尾能力。
|
||
|
||
P0/P1 决策（按 Q1 推荐采纳）：
|
||
- 决策 1（P0）：本轮切片 = 审计合规导出与保留脱敏。
|
||
- 决策 2（P1）：不新建分支、不提交、不推送。
|
||
- 决策 3（P1）：验证深度 = 聚焦导出/脱敏测试 + 全量黄金回归。
|
||
|
||
默认假设：
|
||
- 假设 1：脱敏规则覆盖键名含 token/password/secret/key/authorization/credential 的值 → 替换为 `***REDACTED***`；嵌套 dict/list 递归。
|
||
- 假设 2：导出格式 json（列表）/ csv（表头 + 行），均含 `exportedAt` 与 `chainOk` 摘要元信息。
|
||
- 假设 3：导出仅当前作用域（复用 gov_audit 的 mirror-first 事件源），不含跨租户数据。
|
||
|
||
未决但不阻塞：WORM 物理介质、完整 Merkle 树、异常告警（后续轮）。
|
||
|
||
## 5. 范围
|
||
|
||
In scope:
|
||
- `server/agent_core/audit_export.py`（新）：`sanitize_value`/`sanitize_event`（敏感键脱敏，递归）+ `export_events(events, fmt)`（json/csv）。
|
||
- `server/gateway/app.py`：`GET /api/gov/audit/export?format=json|csv`（复用 mirror-first 事件源 + chain/anchor 摘要）。
|
||
- `tests/golden/test_audit_export.py`（新）：导出完整、脱敏生效（敏感键被掩码）、json/csv 可解析、非敏感值保留。
|
||
- 文档：`docs/architecture/harness.md`、`docs/product/plan-completion-matrix.md`（104 行注记）、`docs/CHANGELOG.md`。
|
||
|
||
Out of scope:
|
||
- WORM 物理介质、完整 Merkle 树、异常告警、前端导出 UI。
|
||
- 提交/推送/合并/清理用户改动。
|
||
|
||
## 6. 成功标准
|
||
|
||
- 聚焦：`python -m pytest -q tests/golden/test_audit_export.py -p no:cacheprovider` 通过（≥4 项）。
|
||
- 全量：`python -m pytest tests/golden -q -p no:cacheprovider`（固定 .venv）≥ 479。
|
||
- ruff 干净；git diff --check 无空白错误。
|
||
|
||
## 7. 验证方式
|
||
|
||
- 脱敏单测（敏感键掩码、非敏感保留、嵌套递归）；导出 json/csv 解析；全量回归。
|
||
|
||
## 8. 关键风险
|
||
|
||
| 风险 | 影响 | 控制方式 |
|
||
|---|---|---|
|
||
| 脱敏规则误伤合法字段 | 导出信息缺失 | 只掩码敏感键名；测试锁定非敏感保留 |
|
||
| 导出大事件集内存 | 性能 | 当前作用域事件量有限；分页留待后续 |
|
||
| CSV 转义问题 | 解析失败 | csv 模块标准写入 |
|
||
|
||
## 9. 停止条件
|
||
|
||
- 全量黄金测试非本轮相关回归无法快速定位时暂停。
|
||
- 任何提交/推送/合并/清理操作停下等待授权。
|
||
|
||
## 10. 本轮完成定义
|
||
|
||
- 实现、测试、文档完成；聚焦与全量通过；矩阵/CHANGELOG 回写；不提交。
|
||
- 收口：报告主要结论、关键洞察、需要特别留意的地方。
|
||
|
||
## 11. 下一步
|
||
|
||
轻量合并版：主 agent 实现 + 验证 + 收口报告。
|