# 合规能力包设计评审报告

- 评审文档：`/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 趋势证据 |