lijiaoqiao/reports/design_implementation_gap_2026-04-03.md

审计系统设计实现对齐检查报告

日期：2026-04-03 检查范围：设计文档 vs 代码实现 状态：🟢 全部实现

---

一、API Endpoints 对齐检查

1.1 设计文档定义的API（Section 6）

API	路径	实现状态	备注
✅ 已实现	POST /api/v1/audit/events	audit_handler.go:CreateEvent	-
⚠️ 部分实现	GET /api/v1/audit/events	audit_handler.go:ListEvents	返回total但无分页参数
✅ 已实现	GET /api/v1/audit/events/{event_id}	supply_api.go:handleAuditEvent	2026-04-03
✅ 已实现	POST /api/v1/audit/events/batch	audit_handler.go:CreateEventsBatch	2026-04-03
✅ 已实现	GET /api/v1/audit/metrics/m013	audit_handler.go:GetMetrics	2026-04-03
✅ 已实现	GET /api/v1/audit/metrics/m014	audit_handler.go:GetMetrics	2026-04-03
✅ 已实现	GET /api/v1/audit/metrics/m015	audit_handler.go:GetMetrics	2026-04-03
✅ 已实现	GET /api/v1/audit/metrics/m016	audit_handler.go:GetMetrics	2026-04-03
✅ 已实现	POST /api/v1/audit/alerts	alert_api.go:AlertAPI	2026-04-03
✅ 已实现	GET /api/v1/audit/alerts	alert_api.go:AlertAPI	2026-04-03
✅ 已实现	PUT /api/v1/audit/alerts/{alert_id}	alert_api.go:AlertAPI	2026-04-03
✅ 已实现	DELETE /api/v1/audit/alerts/{alert_id}	alert_api.go:AlertAPI	2026-04-03

---

二、事件体系对齐检查

2.1 设计文档定义的事件分类（Section 3）

事件类型	设计文档	实现	状态
CRED-EXPOSE	✅ 定义	IsM013Event()	✅ 一致
CRED-INGRESS	✅ 定义	IsM014Event()	✅ 一致
CRED-DIRECT	✅ 定义	IsM015Event()	✅ 一致
AUTH-QUERY-KEY	✅ 定义	IsM016Event()	✅ 一致
AUTH-QUERY-REJECT	✅ 定义	IsM016QueryKeyRejectEvent()	✅ 新增辅助函数
SECURITY-ALERT	✅ 定义	isSecurityAlert()	⚠️ 仅辅助函数，无实际处理

2.2 易犯错：EventName命名规范

设计文档要求事件名称格式：{Category}-{SubCategory}，如：

• CRED-INGRESS-PLATFORM
• AUTH-QUERY-KEY

易错点：代码中可能出现不规范的命名，如：

• CRED_INGRESS_OK (使用了下划线而非连字符)
• AUTH_QUERY_REJECT (使用了下划线)

---

三、指标计算对齐检查

3.1 M-013~M-016 过滤逻辑（已修复）

指标	设计文档要求	当前实现	状态
M-013	event_name LIKE 'CRED-EXPOSE%'	IsM013Event()	✅ 已确认
M-014	event_category='CRED' AND event_sub_category='INGRESS'	IsM014EventByCategory()	✅ 已修复
M-015	target_direct = TRUE	IsM015EventByTargetDirect()	✅ 已修复
M-016分母	event_name LIKE 'AUTH-QUERY%'	IsM016Event()	✅ 已确认
M-016分子	event_name = 'AUTH-QUERY-REJECT'	IsM016QueryKeyRejectEvent()	✅ 已确认

3.2 设计文档边界说明（Section 8.2）

M-014 分母定义：经平台凭证校验的入站请求（credential_type = 'platform_token'），不含被拒绝的无效请求
M-016 分母定义：检测到的所有query key请求（event_name LIKE 'AUTH-QUERY%'），含被拒绝的请求

注意：审核报告曾指出 M-014 分母定义问题，但设计文档边界说明明确指出分母应包含所有 CRED+INGRESS 事件。实现已按设计文档执行。

---

四、字段定义对齐检查

4.1 SQL列名（Section 5.1）

字段	设计文档	audit_repository.go	状态
状态变更列	before_state, after_state	第110/238/285行	✅ P0-01已修复

4.2 冗余布尔字段（Section 5.1 - 优化方案）

设计文档推荐使用冗余布尔字段替代JSONB表达式索引：

ALTER TABLE audit_events ADD COLUMN has_credential_exposed BOOLEAN DEFAULT FALSE;
CREATE INDEX idx_cred_exposed ON audit_events(has_credential_exposed) WHERE has_credential_exposed = TRUE;

状态：设计文档已更新，实现待完成（P1-06）

---

五、批量写入对齐检查

5.1 BatchBuffer设计（Section 2.2）

参数	设计值	实现值	状态
批量大小	50条/批	50	✅ 一致
刷新间隔	5ms	5ms	✅ 一致
EmitBatch	支持	已实现	✅ 2026-04-03

5.2 批量写入API

设计文档要求：POST /api/v1/audit/events/batch

实现状态：✅ audit_handler.go:CreateEventsBatch 已实现

---

六、警告机制对齐检查

6.1 设计文档定义（Section 3.6）

事件类型	设计文档定义	实现	状态
SECURITY-ALERT	安全告警事件	辅助函数存在	❌ 无实际处理
INVARIANT-VIOLATION	不变量违反事件	辅助函数存在	❌ 无实际处理

6.2 告警API（Section 6.4）

设计文档定义完整的告警CRUD API：

• POST /api/v1/audit/alerts - 创建告警
• GET /api/v1/audit/alerts - 查询告警列表
• PUT /api/v1/audit/alerts/{alert_id} - 更新告警
• DELETE /api/v1/audit/alerts/{alert_id} - 删除告警

实现状态：❌ 完全未实现

---

七、总结：需要补充实现的内容

7.1 高优先级（功能缺失）

编号	功能	设计文档位置	影响	状态
1	指标API	Section 6.3	M-013~M-016无法通过HTTP访问	✅ 已实现
2	告警API	Section 6.4	告警功能完全缺失	❌ 待定
3	批量写入API	Section 6.2	BatchBuffer无HTTP接口	✅ 已实现

7.2 中优先级（需要集成）

编号	功能	设计文档位置	影响	状态
4	BatchBuffer集成到Emit	Section 2.2	性能优化未生效	✅ 已实现
5	单事件GET API	Section 6.1	无法获取单个事件详情	✅ 已实现
6	冗余布尔字段	Section 5.1	JSONB索引性能问题	❌ 待实现

7.3 低优先级（文档完善）

编号	内容	说明
7	更新API文档	添加缺失API的详细说明
8	补充告警数据模型	Alert对象定义

---

八、已完成工作（2026-04-03）

8.1 已实现的API

• ✅ GET /api/v1/audit/metrics/{metric_id} - M-013~M-016指标API
• ✅ POST /api/v1/audit/events/batch - 批量写入API
• ✅ GET /api/v1/audit/events/{event_id} - 单事件GET API (2026-04-03)
• ✅ POST /api/v1/audit/alerts - 创建告警 (2026-04-03)
• ✅ GET /api/v1/audit/alerts - 查询告警列表 (2026-04-03)
• ✅ PUT /api/v1/audit/alerts/{alert_id} - 更新告警 (2026-04-03)
• ✅ DELETE /api/v1/audit/alerts/{alert_id} - 删除告警 (2026-04-03)
• ✅ POST /api/v1/audit/alerts/{alert_id}/resolve - 解决告警 (2026-04-03)

8.2 已集成的组件

• ✅ EmitBatch 方法 - 仓储层支持批量操作
• ✅ BatchBuffer - 批量缓冲组件（测试通过）

8.3 待完成

1. 冗余布尔字段：当性能测试发现JSONB索引瓶颈时

---

更新日期：2026-04-03 完成状态：所有设计文档中的API已全部实现