lijiaoqiao/reports/review/compliance_capability_package_design_review_2026-04-02.md

合规能力包设计评审报告

• 评审文档：/home/long/project/立交桥/docs/compliance_capability_package_design_v1_2026-04-02.md
• 评审日期：2026-04-02
• 评审人：Claude Code
• 基线版本：v1.0

---

评审结论

CONDITIONAL GO

该设计文档整体架构合理，扩展了 ToS 合规引擎设计，但在以下方面存在重大缺口需在实施前解决：

1. CI 脚本缺失：设计文档中引用的 compliance/ci/*.sh 脚本均不存在
2. 事件命名不一致：合规规则事件命名与 audit_log_enhancement_design_v1_2026-04-02.md 规范不兼容
3. 外部工具依赖：M-017 四件套依赖 syft 工具但无降级方案

---

1. M-017四件套覆盖

件套	覆盖状态	实现说明	问题
SBOM	部分覆盖	文档指定 SPDX 2.3 格式，示例 JSON 结构正确	依赖外部工具 syft，工具缺失时仅生成空 SBOM
Lockfile Diff	已覆盖	文档定义了变更分类（新增/升级/降级/删除）	脚本未实现
兼容矩阵	已覆盖	文档定义了矩阵格式（组件 x 版本）	脚本未实现
风险登记册	已覆盖	文档定义了 CVSS >= 7.0 收录要求	脚本未实现

关键问题

问题 M017-01（严重）：

• 文档第 560-571 行：当 syft 工具不存在时，生成空 SBOM（"packages": []）
• 这会导致 dependency-audit-check.sh 第 33 行断言失败（grep -q '"packages"' 通过但内容为空）
• 建议：添加 syft 必需性检查，工具缺失时应 FAIL 而不是生成无效报告

问题 M017-02（严重）：

• scripts/ci/dependency-audit-check.sh 是检查脚本而非生成脚本
• 合规能力包设计第 4.4 节的 m017_dependency_audit.sh 脚本不存在
• 实际存在的 reports/dependency/ 目录及四件套报告文件亦不存在

---

2. 与ToS合规引擎一致性

检查项	状态	问题描述
规则引擎架构继承	部分一致	设计扩展了 ToS 引擎（compiler/matcher/executor/audit），但未说明是否复用同一组件
规则配置格式	一致	均使用 YAML 格式定义规则
规则生命周期	一致	支持热更新、版本追踪
事件分类体系	不一致	合规包使用 C013-R01 格式，审计日志设计使用 CRED-EXPOSE 格式
执行位置	一致	均支持 API Gateway 入口拦截

关键问题

问题 TOS-01（严重）：

• 合规能力包（第 44-80 行）定义规则 ID 为 C013-R01~R04
• 审计日志增强设计（第 94-142 行）定义事件分类为 CRED-EXPOSE、AUTH-QUERY-KEY 等
• 两者无法映射，导致 M-013~M-016 指标无法通过统一审计 API 聚合
• 建议：合规规则事件应映射到审计日志的事件分类体系

问题 TOS-02（中等）：

• 合规能力包设计第六章目录结构（第 672-710 行）包含 compliance/ 目录
• 该目录不存在，实际代码库中无对应实现

---

3. CI/CD集成评估

检查项	状态	建议
CI 脚本目录结构	缺失	compliance/ci/ 目录及脚本不存在
Pre-Commit 集成点	已定义	需实现 m013_credential_scan.sh
Build 阶段集成点	已定义	需实现 m017_dependency_audit.sh
Deploy 阶段集成点	已定义	需实现 m014/m015/m016 检查脚本
合规门禁脚本	已定义	compliance_gate.sh 引用了不存在的脚本
阻断条件定义	合理	P0 事件阻断符合安全原则

关键问题

问题 CI-01（严重）：

• 合规能力包第 294-342 行定义了 compliance_gate.sh，引用了以下不存在的脚本：
  • m013_credential_scan.sh
  • m014_ingress_coverage.sh
  • m015_direct_access_check.sh
  • m016_query_key_reject.sh
  • m017_dependency_audit.sh

问题 CI-02（中等）：

• 设计第 295 行硬编码路径 /home/long/project/立交桥/compliance
• 该路径不存在，无法直接部署

问题 CI-03（中等）：

• 设计第 3.3.1 节（第 284-291 行）定义了 CI 集成点，但未提供：
  • 具体的 hook 集成方式（如 git hook、CI YAML 配置）
  • 与现有 superpowers_release_pipeline.sh 的集成说明

---

4. 与审计日志设计一致性

检查项	状态	问题描述
事件结构	部分一致	合规包使用简化事件结构，审计日志使用完整 AuditEvent
凭证字段	一致	两者均定义了 credential_type 字段
事件分类	不一致	见问题 TOS-01
存储设计	一致	均支持 PostgreSQL + 索引
API 设计	一致	均支持 GET /api/v1/audit/metrics/m{013-016}

关键问题

问题 AUD-01（严重）：

• 合规能力包规则事件（如 C013-R01）无法通过审计日志 API 查询
• 审计日志增强设计定义了完整的事件分类，但合规包未实现映射

问题 AUD-02（中等）：

• 合规能力包第 3.2.1 节定义的规则执行流程与审计日志增强设计第 7.1 节的中间件集成方式需协调
• 当前两个设计独立，难以保证端到端审计链路

---

5. 实施可行性评估

5.1 工期评估

任务	设计工期	评审意见
P2-CMP-001 合规规则引擎核心开发	5d	可行
P2-CMP-002~005 四大规则实现	9d	依赖 P2-CMP-001
P2-CMP-006 M-017 四件套	3d	脚本未实现，需额外工作量
P2-CMP-007 CI 流水线集成	2d	所有 CI 脚本均缺失，工作量被低估
P2-CMP-008 监控告警配置	2d	可行
P2-CMP-009 安全机制联动	3d	依赖与现有组件集成
P2-CMP-010 端到端测试	2d	可行
总计	26d	实际工作量可能需要 35-40d

5.2 里程碑评估

里程碑	设计日期	评审意见
M1: 规则引擎完成	2026-04-07	可行
M2: 四大规则就绪	2026-04-11	可行
M3: CI 集成完成	2026-04-13	CI 脚本缺失，延期风险高
M4: 监控告警就绪	2026-04-15	可行
M5: P2 交付完成	2026-04-17	延期概率 > 50%

5.3 验收标准评估

指标	验收条件	评审意见
M-013	凭证泄露事件 = 0	可测试，需自动化扫描
M-014	入站覆盖率 = 100%	可测试，需日志分析
M-015	直连事件 = 0	检测方法未具体化
M-016	拒绝率 = 100%	可测试，需构造外部 query key
SBOM	SPDX 2.3 格式有效	可测试
Lockfile Diff	变更条目完整	无脚本实现
兼容矩阵	版本对应关系正确	无脚本实现
风险登记册	CVSS >= 7.0 收录	无脚本实现

---

6. 一致性问题清单

严重度	问题 ID	问题	建议修复
P0	CI-01	CI 脚本全部缺失，compliance_gate.sh 引用不存在的脚本	优先实现所有 compliance/ci/*.sh 脚本，或调整设计引用已存在的 scripts/ci/ 目录
P0	M017-01	syft 工具缺失时生成无效 SBOM	添加必需性检查，工具缺失时 FAIL
P0	TOS-01	事件命名体系与审计日志不兼容	将 C013-R01 格式映射到 CRED-EXPOSE 格式
P1	CI-02	硬编码路径 /home/long/project/立交桥/compliance	改为环境变量或相对路径
P1	M017-02	m017_dependency_audit.sh 脚本不存在	实现四件套生成脚本
P1	AUD-01	合规事件无法通过审计 API 查询	实现事件分类映射
P2	CI-03	未提供与现有 CI 管道的集成说明	补充 git hook 或 CI YAML 配置示例
P2	TOS-02	compliance/ 目录不存在	补充目录创建脚本或调整到现有目录结构
P2	M015-01	直连检测方法未具体化	补充蜜罐或流量检测实现方案

---

7. 改进建议

7.1 高优先级（阻断发布）

1. 补充 CI 脚本实现

   • 建议复用现有 scripts/ci/ 目录结构而非新建 compliance/ci/
   • 优先实现 m013_credential_scan.sh（凭证扫描可复用现有 secret scanner）
   • 优先实现 m017_dependency_audit.sh 四件套生成脚本

2. 统一事件命名体系

   • 合规规则事件应使用 audit_log_enhancement_design 的分类格式
   • 建议：C013-R01 -> CRED-EXPOSE-RESPONSE

3. M-017 四件套必需性

   • syft 工具应标记为必需依赖（而非可选）
   • 添加 Dockerfile 或 CI 配置确保工具可用

7.2 中优先级

4. 目录结构优化

   • 建议将 compliance/ 改为 scripts/compliance/ 接入现有脚本目录
   • 或在 scripts/ci/ 下新增 compliance-*.sh 脚本

5. 与现有系统集成

   • 说明与 superpowers_release_pipeline.sh 的集成方式
   • 说明与 dependency-audit-check.sh 的关系（当前设计是补充而非替代）

6. M-015 直连检测实现

   • 补充具体检测方法（蜜罐配置、网络流量分析、API 日志分析）
   • 明确检测点位置（出网防火墙、API Gateway、中间件）

7.3 低优先级

7. 文档完整性

   • 补充 P2-CMP-009 安全机制联动的详细设计
   • 补充规则热更新机制的实现细节

8. 测试覆盖

   • 补充各规则的单元测试用例设计
   • 补充端到端测试场景

---

8. 最终结论

评审结论：CONDITIONAL GO

通过条件（实施前必须满足）：

1. 实现所有引用的 CI 脚本（m013~m017_*.sh）
2. 统一事件命名体系与 audit_log_enhancement_design 兼容
3. 补充 M-017 四件套生成脚本（当前仅检查脚本存在）

风险项：

1. 工期风险：CI 脚本实现工作量被低估（建议增加 10-15d）
2. 集成风险：与审计日志系统、ToS 合规引擎的集成需额外协调
3. 测试风险：M-015 直连检测实现方案未具体化

建议行动：

1. 优先实现 CI 脚本，与合规能力包设计同步进行
2. 召开联合评审会议，对齐事件分类体系
3. 拆分 M-015 直连检测为独立子任务，明确实现方案

---

附录：评审基线文档

文档	关键引用
llm_gateway_prd_v1_2026-03-25.md	P2 需求：合规能力包；企业版首批：审计报表与策略留痕导出；关键规则：策略变更必须可审计
tos_compliance_engine_design_v1_2026-03-18.md	合规规则库、自动化合规检查、合规报告生成；规则引擎架构（matcher/executor/audit）
audit_log_enhancement_design_v1_2026-04-02.md	事件分类体系（CRED/AUTH/DATA/CONFIG/SECURITY）；M-013~M-016 指标专用字段
dependency_compatibility_audit_baseline_v1_2026-03-27.md	M-017 四件套：SBOM、锁文件 Diff、兼容矩阵、风险登记册；无四件套发布门禁阻断
2026-03-30-superpowers-execution-tasklist-v2.md	M-017 四件套：SBOM, Lockfile Diff, 兼容矩阵, 风险登记册；F-03 项依赖 M-017 趋势证据