docs(dacli/v3+webpatches): 集成 CI 关卡 G 到 webpatches 强制流程

按用户决策把 CI 关卡 G 集成到 webpatches 流程, 形成完整闭环:

**改 web-patches/README.md** (8 处扩展):
- §规则 加 4 步必跑 CI 关卡 G (改 web 前/后/升级后/验收流程)
- 新增 '验收 / 升级流程' 第 3 步: 必跑 CI 关卡 G
- 新增 'CI 关卡 G 集成背景 (v3.0+)' 章节: 改 web 必跑 + 基线 + 白名单限制
- patch 文档必含 'CI 关卡 G 跑通截图' (paste 真实 FAIL=0 输出)

**v3 主规范 +§二十二 webpatches 强制流程** (78 行):
- §22.1 三阶段强制流程 (改 web 前/后/升级后必跑 CI 关卡 G)
- §22.2 改 web 前必跑 (基线确认)
- §22.3 改 web 后必跑 (新改动验证, 必含截图)
- §22.4 web 升级后必跑 (升级后架构健康)
- §22.5 与 §二十 CI 关卡 G 的关系 (commit 自动 vs 手动强制)
- §22.6 反模式 (6 类, 违反都需修复)
- §22.7 与 §二十一 回归审计的联动 (双向闭环)

**同步更新 §19 版本历史** (新增 1 行 v3.0+):
- v3.0+ 第 4 行: webpatches 强制流程 (§二十二)

**v3.0+ 强制章节全景 (6 个)**:
- §四 应用隔离方案
- §十七 代码审查清单
- §十八 权威源速查
- §二十 CI 关卡 G
- §二十一 回归审计方法论
- §二十二 webpatches 强制流程 (本次新增)

**闭环防御链**:
- §二十 CI 关卡 G → git commit 自动跑 (commit-time 防御)
- §二十二 webpatches → 改 web 端必跑 (author-time 防御)
- §二十一 回归审计 → 周期审计 (audit-time 防御)

权威源: docs/web-patches/README.md + dacli/src/commands/_gate_webapi.ts
This commit is contained in:
ssw committed 2026-06-29 18:36:50 +08:00
1 parent 0d7c1657d1
commit 1e2ead67b6
2 files changed
+113 -5

No files matched your search

+29 -4
View File
@@ -9,13 +9,23 @@ dacli v0.11+ 镜像架构阶段, 当 dacli 需要复用 web 端 Vue 组件 setup
## 规则
1. **改 web 前**先在本目录写 `<component>.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, 不在本目录
- **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 前自动跑)
+84 -1
View File
@@ -1204,6 +1204,7 @@ feat(<scope>): <description> (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/<comp>.md` (待改动清单) | 跑 CI 关卡 G 确认基线 (真实 FAIL = 0) |
| **改 web 后** | 完善 patch 文档 (含 diff/原因/验收) | **再跑 CI 关卡 G**, 确认改动没引入新镜像失败 |
| **web 升级后** | 重新对照所有 patch | 跑 CI 关卡 G, 确认升级后没破坏镜像 |
### 22.2 改 web 前必跑
```bash
# 1. 写 patch 文档 (dacli/docs/web-patches/<comp>.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 端架构一致