diff --git a/docs/web-patches/README.md b/docs/web-patches/README.md index fb5108e..291ff4a 100644 --- a/docs/web-patches/README.md +++ b/docs/web-patches/README.md @@ -9,13 +9,23 @@ dacli v0.11+ 镜像架构阶段, 当 dacli 需要复用 web 端 Vue 组件 setup ## 规则 1. **改 web 前**先在本目录写 `.md` (含"待改动清单") -2. **改 web 后**完善该文档, 含: +2. **改 web 前 + 后**必跑 CI 关卡 G (§二十 v3 主规范): + ```bash + npx tsx src/commands/_gate_webapi.ts + ``` + - FAIL (exit 1, 真实违规) → 阻塞, 必须修 + - WARN (exit 2, 白名单命中) → 提示但通过 + - PASS (exit 0) → 可继续 +3. **改 web 后**完善该文档, 含: - 实际 diff (改前 vs 改后) - 改动原因 (为什么 dacli 需要这个改动) - 验收方法 (怎么验证 patch 还在) -3. **web 升级后** 重新读本目录所有 patch, 逐个对照, 缺失的重新应用 + - **CI 关卡 G 跑通截图** (paste 真实 FAIL=0 那一段输出) +4. **web 升级后** 重新读本目录所有 patch, 逐个对照, 缺失的重新应用 + - 升级后**必跑 CI 关卡 G**, 确认 patch 没有破坏架构 不写文档 = 改动 100% 会被升级覆盖丢失. +**不跑 CI 关卡 G = 改动可能引入镜像架构回归** (新 web 端依赖未镜像). ## 当前 Patches 状态 @@ -53,7 +63,11 @@ ls dacli/docs/web-patches/*.md # - 不在 → 重新应用, 跑 baseline 验证 # - 在 → 文档标 ✅ -# 3. 跑 baseline 验证 +# 3. 必跑 CI 关卡 G (v3.0+ 新增, 防止 patch 引入镜像架构回归) +npx tsx src/commands/_gate_webapi.ts +# 期望: 真实 FAIL = 0, 总体 PASS 或仅 WARN (白名单命中) + +# 4. 跑 baseline 验证 SKIP_PLAYWRIGHT=1 bash /home/ubuntu/ccWorkDir/.claude/skills/dacli-ts/examples/baseline/all.sh ``` @@ -61,4 +75,15 @@ SKIP_PLAYWRIGHT=1 bash /home/ubuntu/ccWorkDir/.claude/skills/dacli-ts/examples/b - **删 web 端文件**: 大概率不行 (其他模块依赖), 不在 patch 范围 - **改 web 端 bug**: 不属于 dacli 范围, 应报给 JNPF 平台组 -- **dacli 自有模块改动**: 走 git log, 不在本目录 \ No newline at end of file +- **dacli 自有模块改动**: 走 git log, 不在本目录 + +## CI 关卡 G 集成背景 (v3.0+, 2026-06-29) + +按 v3 主规范 §二十 CI 关卡 G + §二十二 webpatches 强制流程: + +- **改 web 前**: 跑 `_gate_webapi.ts` 确认当前基线 (真实 FAIL = 0) +- **改 web 后**: 再跑一次确认改动没有引入新镜像问题 +- **不通过**: 暂停, 检查改动是否引入了新的镜像失败模式 +- **白名单 (KNOWN_FALSE_POSITIVES)**: 仅限 web 端架构差异 (如 di 无正则), 不能为图方便加白名单 + +权威源: `dacli/src/commands/_gate_webapi.ts` + `dacli/.git/hooks/pre-commit` (commit 前自动跑) \ No newline at end of file diff --git a/docs/尚数网基本开发规范v3.0.md b/docs/尚数网基本开发规范v3.0.md index 5719e98..d5e0b7d 100644 --- a/docs/尚数网基本开发规范v3.0.md +++ b/docs/尚数网基本开发规范v3.0.md @@ -1204,6 +1204,7 @@ feat(): (vX.Y+) | **v3.0** | **2026-06-29** | **+ dacli (TS) + webapi 镜像 + 13 skill 收纳 + 7 阶段流程 + 4 关卡 CI + 3 HTML+4 MD 文档** | **Claude Code + dacli 团队** | | **v3.0+** | **2026-06-29** | **+ 应用隔离方案 (§四 新增, 9 维度隔离全景 + 数据库 + 目录 + 10 条反模式 + 审查清单, 含 BS-47 jxcj P1-5 字典 enCode 加 appCode 前缀修复)** | **Claude Code + dacli 团队** | | **v3.0+** | **2026-06-29** | **+ CI 关卡 G (§二十 新增, webapi 镜像架构自动防御 + git pre-commit hook + 故意 FAIL 白名单) + 回归审计方法论 (§二十一, docs/cmd-review/regression-2026-06-29.md, 381 行报告)** | **Claude Code + dacli 团队** | +| **v3.0+** | **2026-06-29** | **+ webpatches 强制流程 (§二十二 新增, 改 web 端必跑 CI 关卡 G + patch 文档必含 CI 关卡 G 截图 + 升级后必跑, 闭环防御)** | **Claude Code + dacli 团队** | ### v3.0 vs v2.0 关键变化 @@ -1360,4 +1361,86 @@ git config dacli.gate.enabled false > 详细命令/dacli 实现/skill 内部 references → 查 §17.4 权威源速查. > 应用特定信息 → 写 `docs/{app_code}/` (3 HTML + 4 MD). > 通用规则更新 → 改本规范, 一轮一提交. -> **v3.0+ 新增**: 应用隔离方案 §四 + CI 关卡 G §二十 + 回归审计方法论 §二十一, 共同构成 v3.0+ 强制章节. +> **v3.0+ 新增**: 应用隔离方案 §四 + CI 关卡 G §二十 + 回归审计方法论 §二十一 + webpatches 强制流程 §二十二, 共同构成 v3.0+ 强制章节. + +--- + +## 二十二、webpatches 强制流程 (v3.0+ 新增, 改 web 端必跑 CI 关卡 G) + +> **核心**: 改 web 端源码前 + 后**必跑 CI 关卡 G**, 防止 web 端修改破坏 dacli webapi 镜像架构. +> +> **权威源**: `dacli/docs/web-patches/README.md` + `dacli/src/commands/_gate_webapi.ts` + v3 主规范 §二十 + +### 22.1 三阶段强制流程 + +| 阶段 | 动作 | 必须做的检查 | +|------|------|------------| +| **改 web 前** | 写 `dacli/docs/web-patches/.md` (待改动清单) | 跑 CI 关卡 G 确认基线 (真实 FAIL = 0) | +| **改 web 后** | 完善 patch 文档 (含 diff/原因/验收) | **再跑 CI 关卡 G**, 确认改动没引入新镜像失败 | +| **web 升级后** | 重新对照所有 patch | 跑 CI 关卡 G, 确认升级后没破坏镜像 | + +### 22.2 改 web 前必跑 + +```bash +# 1. 写 patch 文档 (dacli/docs/web-patches/.md) +# 含: 待改动清单 / 改前 diff 估计 / 验收方法 + +# 2. 必跑 CI 关卡 G (基线确认) +cd /home/ubuntu/ccWorkDir/dacli +npx tsx src/commands/_gate_webapi.ts +# 期望: 真实 FAIL = 0, 总体 PASS 或仅 WARN (白名单命中) +``` + +### 22.3 改 web 后必跑 + +```bash +# 1. 完善 patch 文档, 含: +# - 实际 diff (改前 vs 改后) +# - 改动原因 (为什么 dacli 需要这个改动) +# - 验收方法 (怎么验证 patch 还在) +# - **CI 关卡 G 跑通截图** (paste 真实 FAIL=0 那一段输出) + +# 2. 必跑 CI 关卡 G (新改动验证) +npx tsx src/commands/_gate_webapi.ts +# 不通过: 暂停, 检查是否引入了新的镜像失败模式 +``` + +### 22.4 web 升级后必跑 + +```bash +# 1. 看 patch 清单 +ls dacli/docs/web-patches/*.md + +# 2. 对每个 patch: 读 patch "实际 diff", 对照当前 web/ 端文件 + +# 3. 必跑 CI 关卡 G (升级后架构健康) +npx tsx src/commands/_gate_webapi.ts +# 期望: 真实 FAIL = 0 (升级没破坏镜像架构) +``` + +### 22.5 与 §二十 CI 关卡 G 的关系 + +| 机制 | §二十 CI 关卡 G | §二十二 webpatches | +|------|----------------|-------------------| +| **触发时机** | git commit 前自动 | 改 web 端前 + 后**手动** | +| **作用** | 阻止 commit (真实 FAIL) | 阻止 patch 应用 (避免引入镜像失败) | +| **范围** | 整个 dacli 仓库 | 仅 webpatches 流程 | +| **白名单** | 共享 KNOWN_FALSE_POSITIVES | 共享同一白名单 | +| **跳过** | DACLI_SKIP_GATE=1 | 不允许 (webpatches 必跑) | + +### 22.6 反模式 (违反任何一条都需修复) + +| 反模式 | 后果 | 修复 | +|--------|------|------| +| ❌ 改 web 端不写 patch 文档 | 升级覆盖丢失 | 立即补写 | +| ❌ 改 web 前不跑 CI 关卡 G | 不知道基线状态 | 必跑 | +| ❌ 改 web 后不跑 CI 关卡 G | 可能引入镜像失败 | 必跑 | +| ❌ patch 文档无 CI 关卡 G 截图 | 后续无法审计 | 粘贴真实输出 | +| ❌ 为图方便加白名单 | 掩盖真实问题 | 仅限 web 端架构差异 | +| ❌ 升级后不跑 CI 关卡 G | 不知道升级破坏了什么 | 必跑 | + +### 22.7 与 §二十一 回归审计的联动 + +- **回归审计发现** web 端架构变化 → webpatches 流程需更新 +- **webpatches 流程** 跑了 CI 关卡 G FAIL → 触发回归审计 (找出根因) +- **双向闭环**: 回归审计 ↔ webpatches 流程, 共同保证 dacli 与 web 端架构一致