动机（Why）

PR #3 合入后的隐性严重问题：远端 CI cnb-an8-1jnn1perq 虽显示 15/15 stages success，但核心 Docker 依赖 stage 事实上被静默跳过——

这意味着B 层棘轮阈值 78/70 仅在本地验证过，远端 CI 从未真实跑过。这是 meta-principles.md §原则 2（不可执行的测试 = 负价值）的典型反例——CI 绿灯 ≠ 测试通过，也是 LESSONS §二 B12（UI 推断数值）的严重变种：把 pipeline status:success 当作所有 stage 真跑的证据。

变更清单（What）

2 个 commits 分层推进

• commit 1 fix(ci) 8275a9d：CI 修复（3 文件 / +237/-96 行）
• commit 2 docs(meta) 2c4a4f6：CHECKPOINT §四 轮次 3.1 档案（1 文件 / +60/-1 行）

根因定位（通过查 CNB docs + 脚本行为分析）

1. .cnb.yml 使用 stage 级 image: maven:* + services: [docker] 组合
2. 按 CNB grammar.html §三 示例文档，声明 services 时应使用 docker: { image: ... } 语法——旧语法可能不正确注入 services
3. 即使 services 注入成功，CNB dind 默认不提供 docker compose v2 插件（grammar.html §五 明确说"compose 不一定预装"）
4. 脚本的 docker compose version 检测失败 → exit 0 + WARNING 静默跳过
5. 当时脚本设计为"Docker 不可用时幂等跳过"——方向 F 起初就用错的兜底策略

改动 1：.cnb.yml（push + MR 两段共 4 处）

两个 Docker 依赖 stage 统一改语法：

  - name: biz-backend-coverage
-   image: maven:3.9-eclipse-temurin-17
    services:
      - docker
+   docker:
+     image: maven:3.9-eclipse-temurin-17
    script:
      - sh scripts/ci/backend/check-backend-coverage.sh

同样改 biz-backend-functional。

改动 2：check-backend-functional.sh（107 → 163 行）

• Docker 严格要求："docker 不可用" 从 exit 0 改为 exit 1（真实失败）
  • 本地开发保留兜底：export DOCKER_REQUIRED=0 合法跳过
• 双路径启动策略：
  • 路径 A：docker compose v2/v1 插件（本地 + 部分 CI）
  • 路径 B：docker run 原生启动 PG（CNB dind 无 compose 插件时兜底）
• trap cleanup EXIT INT TERM 确保容器清理（替代之前手工 down -v）
• PG 就绪探测按 LAUNCH_MODE 分支（compose exec vs docker exec）

改动 3：check-backend-coverage.sh（114 → 176 行）

同构改写——相同的双路径启动 + 严格 Docker 要求 + trap cleanup。

改动 4：CHECKPOINT.md §四 轮次 3.1（新增 60 行档案）

• 完整根因 5 步定位
• 3 件事修复清单
• 双路径实测证据
• 3 条学到的东西
• §七 指标变化预期表（待 PR 合入后远端验证）

验证证据（How verified）

本地 15/15 CI stages 全绿 + 0 lint

路径 A 实测（本地 docker compose v2 插件）：

==> P1 后端功能测试 (MockMvc + PostgreSQL)
    使用路径 A: docker compose (v2 插件可用)
    启动 PG (mode=compose-v2) ...
    PG 已就绪
    运行功能测试 ...
[INFO] Tests run: 11, Failures: 0, Errors: 0 ✅
[INFO] BUILD SUCCESS
[OK] 后端功能测试通过

路径 B 实测（PATH 屏蔽 docker compose 模拟 CNB dind 无插件场景）：

==> P1 后端功能测试 (MockMvc + PostgreSQL)
    使用路径 B: docker run 原生启动（compose 插件不可用）
    启动 PG (mode=native) ...
    PG 容器启动: cnb-test-pg-17628 ✅
    PG 已就绪 ✅

（路径 B 测试最终失败是因沙箱 PATH 屏蔽了 mvn——docker 层所有行为完全正确）

覆盖率棘轮实测：

    行覆盖: 79%  保底: 78%
    分支覆盖: 71%  保底: 70%
[OK] 后端覆盖率棘轮达标

yml 对称性守门员：push/MR 两段 87 行完全一致 ✅

影响面（Impact）

行为变化矩阵

远端验证（待 PR 合入触发）

关键判据：本 PR 合入后的 CNB 构建，biz-backend-functional 耗时应 > 20s 才算真跑；若仍 < 5s，说明 CNB dind 配置仍有问题需进一步迭代（T-Q2-g 候选）。

关闭待办

• ✅ PR #3 遗留隐性问题"远端棘轮阈值 78/70 未真实验证"

新增待办

• T-Q2-f：向源仓库反馈 B13 候选反模式——"CI 静默跳过被当作通过" + cicd-pipeline/SKILL.md 补充"CNB dind 无 compose 插件"坑点
• T-Q2-g：若远端仍未真跑，深挖 CNB dind 其他配置选项

本轮的重要 meta 意义

这是本项目第 1 次"CI 修复"性质的 PR——不是新功能也不是规则修订，而是"发现已合 PR 的隐性缺陷并修复"。这类 PR 应作为未来项目周期的重要 PR 类型独立出来。

同时验证了"每次引入新 CI stage 必须核对耗时合理性"这条工程纪律——2 秒的 functional stage 本应立即警觉，这是对抗 B12/B13 反模式的一道实际防线。

Refs

• 父事件：PR #3 远端 CI cnb-an8-1jnn1perq stage 耗时异常发现
• 关联：
  • meta-principles.md §原则 2（不可执行的测试 = 负价值）
  • LESSONS.md §二 B12（UI 推断数值反模式的推论）
  • testing-standards.md §3.2 方案 A（显式 compose——本 PR 扩展为"compose + native 双路径"）
  • CHECKPOINT.md §四 轮次 3.1 完整档案
  • 源仓库 rules/cicd-pipeline.md 下次修订时登记 CNB dind 坑点
• CNB 文档参考：grammar.html §三/§五（services + docker 语法；compose 不一定预装）