sync: d8d-dev 步骤级验证跟踪增强 — 预生成清单 + 结果持久化 + 步骤级门禁

变更文件: - validation-mode.md: Phase 0V 生成 verification-checklist.yaml，E2E 每步记录 step_results/issues_detected/auto_fixes，GATE-CHECK 增加 SG1-SG3 - journey-mode.md: 旅程验证增加步骤级清单生成和跟踪，续跑支持步骤级恢复 - auto-fix-engine.md: 新增 5.5 节修复后步骤级状态更新规则 - visual-verification.md: 增加 step_id 关联和跨步骤累计追踪
2026-04-13 11:18:27 +00:00
parent 3f965e9171
commit b4cc100ed9
4 changed files with 279 additions and 13 deletions
--- a/.claude/skills/d8d-dev/auto-fix-engine.md
+++ b/.claude/skills/d8d-dev/auto-fix-engine.md
@@ -552,6 +552,50 @@ GATE-CHECK:

 ---

+## 5.5 步骤级状态更新（⛔ AUTO-FIX/AUTO-IMPLEMENT 完成后强制执行）
+
+**修复完成后，必须同步更新步骤级跟踪文件，确保修复证据完整可追溯。**
+
+```
+AUTO-FIX/AUTO-IMPLEMENT 执行后:
+  1. 更新 verification-checklist.yaml:
+     - 找到当前 step → status 改为 "fixed"（修复后待重测）或 "pass"（重测通过后）
+     - 如果重测通过 → status 改为 "pass"
+
+  2. 更新 pipeline-state.yaml step_results:
+     - 在当前步骤的 auto_fixes 数组中追加修复记录:
+       ```yaml
+       auto_fixes:
+         - fix_id: "FIX-{NNN}"
+           issue_id: "ISSUE-{NNN}"         # 关联触发修复的问题
+           fix_type: "AUTO-FIX|AUTO-IMPLEMENT|AUTO-DATA-FIX"
+           description: "{修复描述}"
+           files_changed: [ "{文件路径}" ]
+           retry_count: {N}
+           result: "pass|fail"
+           fixed_at: "{ISO timestamp}"
+           screenshot_after_fix: "{修复后重测截图路径}"
+       ```
+
+  3. 更新步骤级 GATE:
+     - 重新检查 G5: all_issues_resolved
+     - 修复通过 → step_gate 改为 "pass"
+     - 修复失败且重试耗尽 → step_gate 改为 "fail"，步骤标记 failed
+
+  4. 如重测需要重新截图和 analyze_image:
+     - browser_take_screenshot → 保存为新截图（原截图保留）
+     - analyze_image → 更新 analyze_image_result
+     - 更新 step_results 的 screenshot_path 和 analyze_image_result
+```
+
+**⛔ 禁止行为**:
+- ❌ 修复后不更新 verification-checklist.yaml 的 step status
+- ❌ 修复后不追加 auto_fix 记录到 step_results
+- ❌ 修复后不重新检查步骤级 GATE
+- ❌ 修复失败但 step_gate 仍标记为 "pass"
+
+---
+
 ## 6. 各模式引用方式

 以下文件必须引用本引擎，删除各自的重复定义：
--- a/.claude/skills/d8d-dev/journey-mode.md
+++ b/.claude/skills/d8d-dev/journey-mode.md
@@ -159,6 +159,29 @@ Story 验证全部通过 ≠ 用户能正常使用系统。旅程模式弥补这
    - 违规 → 自动修复旅程文件 → 重新校验（max 3x）
    - 环境适配：读取 pipeline-context.md 确定当前环境，按 R3 适配
    ↓
+1.8 生成步骤级验证清单（⛔ 强制 — 写入 verification-checklist.yaml）
+    - 解析每个旅程的「技术验证步骤」→ 为每个步骤生成 step 条目
+    - 提取验收标准 → 生成 acceptance_criteria 条目
+    - 写入/追加到 verification-checklist.yaml 的 journeys 部分：
+      ```yaml
+      journeys:
+        epic_N:
+          journey_M:
+            name: "{旅程名称}"
+            steps:
+              - id: "jN-M-s{S}"
+                action: "{操作描述}"
+                expected: "{预期结果}"
+                screenshot_required: true
+                screenshot_path: "tests/e2e/screenshots/journey-epicN-M-stepS.png"
+                analyze_image_required: true
+                status: "pending"
+            acceptance_criteria:
+              - criterion: "{验收标准}"
+                status: "pending"
+      ```
+    - 如 verification-checklist.yaml 已存在 → 跳过已 pass 的步骤，从 pending 步骤恢复
+    ↓
 2. 询问: 验证全部 Epic 还是指定 Epic?
    ↓
 3. 逐 Epic 执行旅程:
@@ -379,6 +402,38 @@ Story 验证全部通过 ≠ 用户能正常使用系统。旅程模式弥补这
        2. analyze_image → 使用 visual-verification.md 中的标准提示词
        3. 结果记录到 pipeline-state.yaml 的 verification_detail（含 analyze_image_executed: true）
        4. 视觉验证 FAIL → 按分流规则处理（见 auto-fix-engine.md + iron-laws.md 检测即阻断表）
+        5. ⛔ **步骤级跟踪**（每个用户步骤完成后强制执行）:
+           a. 更新 verification-checklist.yaml 对应 step 的 status
+           b. 追加 step_results 到 pipeline-state.yaml 的 user_journeys:
+              ```yaml
+              - step_id: "j{N}-{M}-s{S}"
+                action: "{操作描述}"
+                status: "pass|fail|fixed|skipped"
+                screenshot_path: "tests/e2e/screenshots/journey-epic{N}-{M}-step{S}.png"
+                analyze_image_result: { ... }
+                issues_detected: [ ... ]       # 检测到的问题
+                auto_fixes: [ ... ]            # 自动修复记录
+                step_gate: "pass|fail|blocked"
+                gate_checks:
+                  - check: "screenshot_consistency"
+                    result: "pass|fail"
+                  - check: "analyze_image_executed"
+                    result: "pass|fail"
+                  - check: "checklist_synced"
+                    result: "pass|fail"
+                  - check: "state_persisted"
+                    result: "pass|fail"
+                  - check: "all_issues_resolved"
+                    result: "pass|fail"
+                executed_at: "{ISO timestamp}"
+                note: "{备注}"
+              ```
+           c. 步骤级 GATE 检查（5 项，任一 FAIL → 阻断）:
+              ├── G1: screenshot_consistency — screenshot_path 文件存在
+              ├── G2: analyze_image_executed — analyze_image_result 非空
+              ├── G3: checklist_synced — verification-checklist.yaml step status 已更新
+              ├── G4: state_persisted — pipeline-state.yaml step_results 已追加
+              └── G5: all_issues_resolved — 所有 issues_detected 有对应 resolved auto_fix
        4.5. ⛔ **源码 SVG data URI 扫描**（视觉验证关卡内 — 每次 snapshot 后强制执行）:
           - Bash: `grep -rn "data:image/svg+xml" app/mini-program/src/`（扫描小程序源码目录）
           - 发现匹配 → svg_data_uri_check.found = FOUND → 记录文件列表
@@ -585,6 +640,11 @@ user_journeys:
      auto_fix_result: "PASS"  # PASS / FAIL
      # --- FR 覆盖追踪（新增）---
      coverage_frs: ["FR1", "FR2", "FR4", "FR5", "FR6"]
+      # ===== 新增: 步骤级结果 =====
+      step_results: []              # 已在执行过程中逐步追加（格式见执行模板步骤 2e）
+      total_issues_detected: 0      # 所有步骤检测到的问题总数
+      total_auto_fixes: 0           # 所有步骤的自动修复总数
+      all_issues_resolved: true     # 所有问题是否全部修复
      details: "完整执行日志"
 ```

@@ -608,3 +668,8 @@ user_journeys:
 - 读取 `pipeline-state.yaml` 的 `user_journeys` 部分
 - 已 `pass` 的旅程跳过
 - 从第一个非 `pass` 的旅程继续
+- **步骤级恢复**（⛔ 增强）:
+  - 读取 `verification-checklist.yaml` → 找到当前旅程中第一个 `status: pending` 的 step
+  - 读取 `pipeline-state.yaml` 的 `step_results` → 确认最后一个已完成步骤
+  - 从下一个步骤继续执行（跳过已完成的步骤，不重复截图/分析）
+  - 如无 pending step → 该旅程验证已完成，继续下一个旅程
--- a/.claude/skills/d8d-dev/validation-mode.md
+++ b/.claude/skills/d8d-dev/validation-mode.md
@@ -15,6 +15,11 @@
   - `implemented` → 从 TEST 恢复
   - `tested-fail` → 从 AUTO-FIX 恢复
 4. 跳过 sprint-status 中已标记 `done` 的 Story
+5. **步骤级恢复**（⛔ 增强 — 优先于 Story 级恢复）：
+   - 读取 `verification-checklist.yaml` → 找到当前 Story 中第一个 `status: pending` 的 step
+   - 读取 `pipeline-state.yaml` 的 `step_results` → 确认最后一个已完成步骤
+   - 从下一个步骤继续执行（跳过已完成的步骤，不重复截图/分析）
+   - 如无 pending step → 该 Story 验证已完成，继续下一个 Story

 ## 验证模式续跑

@@ -80,12 +85,40 @@
       Story 类型: API+前端 (assignee: frontend+backend)
     ```

-3. **标记已完成的 Task**
+3. **生成步骤级验证清单**（⛔ 强制 — 写入 verification-checklist.yaml）
+   - 为每个待验证 Story 从 V1/V2/V3 检查点生成操作步骤条目
+   - 每个步骤包含：id、phase（api/e2e/source-check）、action、expected、screenshot_required、screenshot_path、analyze_image_required、status（初始 pending）
+   - 为每个 Story 生成 gate_check 条目（9 项检查，初始 pending）
+   - 写入 `_bmad-output/implementation-artifacts/verification-checklist.yaml`：
+     ```yaml
+     generated_at: "{ISO timestamp}"
+     mode: "validation"
+     stories:
+       "X-Y-title":
+         title: "{Story 标题}"
+         assignee: "{assignee}"
+         steps:
+           - id: "X-Y-s{N}"
+             phase: "api|e2e|source-check"
+             action: "{操作描述}"
+             expected: "{预期结果}"
+             screenshot_required: true/false
+             screenshot_path: "tests/e2e/screenshots/story-X-Y-step{N}.png"
+             analyze_image_required: true/false
+             status: "pending"
+         gate_check:
+           - check: "{检查项名称}"
+             status: "pending"
+     ```
+
+4. **标记已完成的 Task**
   - 已 `verified: true` 的 Story → 立即 `TaskUpdate: completed`
+   - 同步将 verification-checklist.yaml 中对应 Story 的所有 steps 标记为 `skipped`
   - 输出: `已创建 N 个验证 Task，其中 M 个已完成（跳过），K 个待验证`

-4. **恢复时检查 TaskList**
+5. **恢复时检查 TaskList 和清单文件**
   - 如果 TaskList 已有 Task（续跑场景）→ 跳过批量创建，直接找 pending Task 继续
+   - 如果 verification-checklist.yaml 已存在 → 跳过清单生成，从第一个 status=pending 的 step 继续执行

 ### Phase 0V COMPLETE GATE

@@ -353,6 +386,74 @@ echo "placeholder_functions=$PLACEHOLDER_COUNT"
  - 关卡 = browser_take_screenshot + analyze_image（使用 visual-verification.md 标准提示词）
  - 关卡未通过 → 按分流规则处理，不得进入下一个操作

+**⛔ 步骤级跟踪（每个 E2E 操作步骤完成后强制执行）**：
+
+每个操作步骤完成后，必须执行以下 5 项操作（与视觉验证关卡配合执行）：
+
+```
+步骤级跟踪流程（每个 E2E 操作后）:
+  1. 截图保存 → browser_take_screenshot
+  2. 视觉分析 → analyze_image（如 analyze_image_required=true）
+  3. 更新清单 → Edit verification-checklist.yaml 对应 step 的 status
+  4. 记录结果 → 追加 step_results 到 pipeline-state.yaml:
+     ```yaml
+     - step_id: "X-Y-s{N}"
+       phase: "e2e"
+       action: "{操作描述}"
+       status: "pass|fail|fixed|skipped"
+       screenshot_path: "tests/e2e/screenshots/story-X-Y-step{N}.png"
+       analyze_image_result: { ... }    # 如有
+       issues_detected: [ ... ]         # 检测到的问题（如有）
+       auto_fixes: [ ... ]              # 自动修复记录（如有）
+       step_gate: "pass|fail|blocked"   # 步骤级门禁结果
+       gate_checks:                     # 5 项检查结果
+         - check: "screenshot_consistency"
+           result: "pass|fail"
+         - check: "analyze_image_executed"
+           result: "pass|fail"
+         - check: "checklist_synced"
+           result: "pass|fail"
+         - check: "state_persisted"
+           result: "pass|fail"
+         - check: "all_issues_resolved"
+           result: "pass|fail"
+       executed_at: "{ISO timestamp}"
+       note: "{备注}"
+     ```
+  5. 步骤级 GATE → 检查 5 项条件:
+     ├── G1: screenshot_consistency — 如步骤要求截图，screenshot_path 文件存在
+     ├── G2: analyze_image_executed — 如步骤要求分析，analyze_image_result 非空
+     ├── G3: checklist_synced — verification-checklist.yaml 中 step status 已更新
+     ├── G4: state_persisted — pipeline-state.yaml step_results 已追加
+     └── G5: all_issues_resolved — issues_detected 中所有问题有对应 auto_fix 且 result=pass
+     任一 FAIL → 阻断，不得继续下一步骤
+```
+
+**检测到问题时的记录格式**（issues_detected）:
+```yaml
+issues_detected:
+  - issue_id: "ISSUE-{NNN}"
+    type: "{问题类型}"              # layout_overflow | english_enum | emoji_icons | broken_images | svg_data_uri | dual_nav | placeholder | api_target | constraint_mismatch
+    severity: "{严重程度}"           # bug | unimplemented | data_issue | env_limit
+    description: "{问题描述}"
+    detected_by: "{检测方式}"        # browser_evaluate | analyze_image | source_scan | curl
+    detected_at: "{ISO timestamp}"
+```
+
+**自动修复记录格式**（auto_fixes）:
+```yaml
+auto_fixes:
+  - fix_id: "FIX-{NNN}"
+    issue_id: "ISSUE-{NNN}"         # 关联的问题
+    fix_type: "AUTO-FIX|AUTO-IMPLEMENT|AUTO-DATA-FIX"
+    description: "{修复描述}"
+    files_changed: [ "{文件路径}" ]
+    retry_count: {N}                # 重试次数
+    result: "pass|fail"             # 修复结果
+    fixed_at: "{ISO timestamp}"
+    screenshot_after_fix: "{修复后截图路径}"  # 修复后重测截图
+```
+
 #### 步骤 5: 最终截图保存（Story 涉及前端页面时）
 - browser_take_screenshot → filename: "tests/e2e/screenshots/story-{x}-{y}.png", type: "png"
 - 管理后台和小程序分别截图时使用不同后缀：
@@ -382,7 +483,10 @@ GATE-CHECK 检查项：
 ├── source_code_no_localhost === true              ← 步骤 3.5 检查 1（localhost fallback）
 ├── icon_solution_compliant === true               ← 步骤 3.5 检查 2（图标方案合规，小程序/移动端）
 ├── source_code_no_emoji_icons === true            ← 步骤 3.5 检查 3（Emoji 充当图标）
-└── no_placeholder_functions === true             ← 步骤 3.5 检查 4（"暂未开放"等未实现占位符）
+├── no_placeholder_functions === true             ← 步骤 3.5 检查 4（"暂未开放"等未实现占位符）
+├── SG1: all_steps_gated === true                 ← 所有 step_results 的 step_gate 均为 "pass"
+├── SG2: no_unresolved_issues === true            ← 所有 steps 的 issues_detected 都有对应 resolved 的 auto_fix
+└── SG3: checklist_complete === true              ← verification-checklist.yaml 中所有 steps 的 status 均非 "pending"

 任一 FAIL → 分类分流：
  Bug（代码有但值错误）→ AUTO-FIX
@@ -392,6 +496,23 @@ GATE-CHECK 检查项：

 **⛔ 跳过此步骤直接执行步骤 7 是严重违规行为。**

+**SG1-SG3 详细判定**：
+```
+SG1 (all_steps_gated):
+  读取 step_results → 所有条目的 step_gate === "pass"
+  任一 step_gate === "fail" 或 "blocked" → SG1 FAIL
+
+SG2 (no_unresolved_issues):
+  遍历所有 step_results 的 issues_detected:
+    对每个 issue → 在 auto_fixes 中找到 issue_id 匹配的修复记录 → result === "pass"
+    无匹配修复或 result !== "pass" → SG2 FAIL
+
+SG3 (checklist_complete):
+  读取 verification-checklist.yaml 当前 Story 的 steps:
+    所有条目的 status !== "pending"
+    任一 status === "pending" → SG3 FAIL
+```
+
 #### 步骤 7: 标记完成（三个写入操作，缺一不可）

 **7a. TaskUpdate**：
@@ -413,18 +534,23 @@ story_results:
      screenshot_path: "tests/e2e/screenshots/story-x-y.png"
      analyze_image_called: true/false
      url_used: "外网域名" / "localhost(fallback)"
-      # 新增字段（⛔ 强制填写）
-      api_centralized: true/false        # 前端 API 调用是否使用集中式模块
+      api_centralized: true/false
      layout_check:
-        horizontal_overflow: true/false   # 页面宽度是否溢出视口
-        tabbar_visible: true/false/null   # 底部 TabBar 是否可见（null=无TabBar）
-        document_width: 375               # 实际文档宽度
-        viewport_width: 375              # 视口宽度
+        horizontal_overflow: true/false
+        tabbar_visible: true/false/null
+        document_width: 375
+        viewport_width: 375
      icons_check:
-        tabbar_icons_visible: true/false  # TabBar 图标是否全部可见
-        broken_images: true/false         # 是否有加载失败的图片
-        emoji_as_icons: true/false        # 是否有 emoji 充当功能图标
-      dual_write_verified: true           # 三写一致性验证是否通过
+        tabbar_icons_visible: true/false
+        broken_images: true/false
+        emoji_as_icons: true/false
+      dual_write_verified: true
+      # ===== 新增: 步骤级结果 =====
+      step_results: []                   # 已在步骤 3/4 执行过程中逐步追加
+      # ===== 新增: Story 级问题汇总 =====
+      total_issues_detected: 0           # 所有步骤检测到的问题总数
+      total_auto_fixes: 0               # 所有步骤的自动修复总数
+      all_issues_resolved: true          # 所有问题是否全部修复
    note: "简短验证摘要"
 ```

--- a/.claude/skills/d8d-dev/visual-verification.md
+++ b/.claude/skills/d8d-dev/visual-verification.md
@@ -227,6 +227,37 @@ verification_detail:
    details: "描述"
 ```

+**⛔ 步骤级关联**：上述 verification_detail 中发现的每个问题，必须同时记录到对应步骤的 `step_results[].issues_detected` 中（含 `step_id` 关联），确保问题可追溯到具体操作步骤：
+
+```yaml
+# step_results 中的关联记录示例
+step_results:
+  - step_id: "2-1-s2"
+    # ... 其他字段 ...
+    issues_detected:
+      - issue_id: "ISSUE-001"
+        type: "layout_overflow"
+        severity: "bug"
+        description: "水平溢出: document_width=420 > viewport=375"
+        detected_by: "browser_evaluate"
+        detected_at: "{ISO timestamp}"
+        # ⛔ 关联: 此问题同时记录在 verification_detail.layout_check.horizontal_overflow = true
+    analyze_image_result:
+      # ⛔ 以下字段与 verification_detail 同步（同一来源）
+      design_compliance: "PASS"             # → verification_detail.design_check.design_compliance
+      icons_check: { emoji_as_icons: "NONE", broken_images: "NONE" }
+      layout_check: { horizontal_overflow: true }  # → verification_detail.layout_check.horizontal_overflow
+```
+
+**跨步骤累计检测规则增强**：累计检测按 `step_id` 追踪，每个步骤的检测结果独立记录但跨步骤累计：
+```
+跨步骤累计:
+  step 1: emoji_as_icons = NONE → 累计 0
+  step 2: emoji_as_icons = FOUND → 累计 1 → ⛔ 触发修复（step_id: "2-1-s2"）
+  修复后 step 2 重测: emoji_as_icons = NONE → 累计重置为 0
+  step 3: emoji_as_icons = NONE → 累计 0 → 不触发
+```
+
 ---

 ## 视觉检查问题分流规则