91 lines
4.2 KiB
Markdown
91 lines
4.2 KiB
Markdown
# 第 14 轮工作计划（轻量合并版）：审计完整性告警
|
||
|
||
更新日期：2026-08-01
|
||
|
||
## 1. 本轮目标
|
||
|
||
新增审计完整性告警：`/api/gov/audit` 返回 `alerts` 聚合（链校验失败/锚定不匹配/镜像异常 → 结构化告警），前端 AuditView 展示告警条；黄金测试证明异常可检测并呈现；矩阵 104 行剩余「异常告警」落地。
|
||
|
||
## 2. 背景和当前状态
|
||
|
||
- 当前已完成：`/api/gov/audit` 已返回 `chain`（链校验）、`anchor`（锚定状态）、`source`（mirror/world）；`audit_ledger.py`/`audit_mirror.py`/`audit_export.py`。
|
||
- 当前缺口：chain/anchor/source 各自返回，未聚合成「告警」；前端 AuditView 只展示 chain 单条。
|
||
- 本轮为什么现在做：矩阵 104 行剩余「异常告警」；纯本地、低风险。
|
||
- Workspace preflight：第 13 轮收口（485 passed）；服务 8003/5173 正常；共享脏工作区、无提交。
|
||
- 方向分析：Q1 推荐（审计异常告警），目标续跑轮授权执行。
|
||
|
||
## 3. 本轮工作方向
|
||
|
||
```text
|
||
chain/anchor/source 分散返回
|
||
-> audit_alerts(chain, anchor, source) → alerts[]（code/severity/message）
|
||
-> /api/gov/audit 返回 alerts；前端 AuditView 展示告警条
|
||
-> 黄金测试：正常无告警、链断裂/锚定不匹配/镜像异常各触发告警
|
||
-> 矩阵 104 行注记；CHANGELOG
|
||
```
|
||
|
||
## 4. 已确认决策
|
||
|
||
任务重量：
|
||
- 档位：轻型（告警聚合函数 + 端点扩展 + 前端展示 + 黄金测试）。
|
||
- 规模依据：新增独立告警函数，不改审计写入；风险 LOW。
|
||
- 选择原因：矩阵 104 行明确剩余项；异常告警是审计闭环的最后一块。
|
||
|
||
P0/P1 决策（按 Q1 推荐采纳）：
|
||
- 决策 1（P0）：本轮切片 = 审计完整性告警。
|
||
- 决策 2（P1）：不新建分支、不提交、不推送。
|
||
- 决策 3（P1）：验证深度 = 聚焦告警测试 + 全量黄金回归。
|
||
|
||
默认假设：
|
||
- 假设 1：alerts 结构 [{code, severity: info|warning|critical, message}]；正常态返回空数组。
|
||
- 假设 2：触发条件——链校验失败（critical）、锚定不匹配/未锚定（warning）、镜像与 world 不一致或镜像异常（warning）。
|
||
- 假设 3：前端 AuditView 展示告警条（复用 gov-notice/gov-chain 样式，severity 区分）。
|
||
|
||
未决但不阻塞：WORM 物理介质、完整 Merkle 树、告警通知渠道（邮件/IM）。
|
||
|
||
## 5. 范围
|
||
|
||
In scope:
|
||
- `server/agent_core/audit_alerts.py`（新）：`build_alerts(chain, anchor, source)`。
|
||
- `server/gateway/app.py`：`gov_audit` 增加 `alerts` 字段。
|
||
- `apps/web/src/api/types.ts`：`AuditAlert` 类型 + `fetchAudit` 返回类型扩展。
|
||
- `apps/web/src/gov/GovConsole.tsx`：AuditView 展示告警条。
|
||
- `tests/golden/test_audit_alerts.py`（新）：正常无告警、链断裂告警、锚定不匹配告警、镜像异常告警。
|
||
- 文档：`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_alerts.py -p no:cacheprovider` 通过（≥4 项）。
|
||
- 全量：`python -m pytest tests/golden -q -p no:cacheprovider`（固定 .venv）≥ 485。
|
||
- ruff 干净；前端 tsc 通过；git diff --check 无空白错误。
|
||
|
||
## 7. 验证方式
|
||
|
||
- 告警聚合单测（各触发条件）；网关端点含 alerts；前端 tsc；全量回归。
|
||
|
||
## 8. 关键风险
|
||
|
||
| 风险 | 影响 | 控制方式 |
|
||
|---|---|---|
|
||
| 告警误报 | 前端噪音 | 仅明确异常触发；severity 分级 |
|
||
| 前端类型漂移 | 编译失败 | 同步 types.ts + tsc |
|
||
| 告警逻辑耦合审计 | 审计写入受影响 | 纯只读聚合，不改写入路径 |
|
||
|
||
## 9. 停止条件
|
||
|
||
- 全量黄金测试非本轮相关回归无法快速定位时暂停。
|
||
- 任何提交/推送/合并/清理操作停下等待授权。
|
||
|
||
## 10. 本轮完成定义
|
||
|
||
- 实现、测试、文档完成；聚焦与全量通过；矩阵/CHANGELOG 回写；不提交。
|
||
- 收口：报告主要结论、关键洞察、需要特别留意的地方。
|
||
|
||
## 11. 下一步
|
||
|
||
轻量合并版：主 agent 实现 + 验证 + 收口报告。
|