sdd-flow-kit 1.3.18 → 1.3.21

package/scripts/lib/visual-regression.mjs

@@ -0,0 +1,191 @@
+/**
+ * L4 视觉回归分析（与 src/core/visualRegression.ts 语义一致）。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseTestBlocks, stripComments, testBlockReferencesAc } from "./test-assertion-analysis.mjs";
+
+const IMAGE_REF_RE =
+  /(?:source\/[\w/.-]+\.(?:png|jpe?g|webp)|visual-baseline\/[\w/.-]+\.(?:png|jpe?g|webp)|image_\d+\.(?:png|jpe?g|webp))/gi;
+const DIFF_PERCENT_RE = /diff\s*[≤<=]\s*(\d+(?:\.\d+)?)\s*%/i;
+const TO_HAVE_SCREENSHOT_RE = /\btoHaveScreenshot\s*\(/;
+const PAGE_SCREENSHOT_ONLY_RE = /\bpage\.screenshot\s*\(/;
+
+export function parseAcMatrixFrom05(content) {
+  const items = [];
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|")) continue;
+    if (/^\|\s*[-:]+/.test(trimmed)) continue;
+    if (/^\|\s*ID\s*\|/i.test(trimmed)) continue;
+    const cells = trimmed
+      .split("|")
+      .map((c) => c.trim())
+      .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+    if (cells.length < 5) continue;
+    const id = (cells[0] ?? "").toUpperCase();
+    if (!/^AC-\d{2,}/.test(id)) continue;
+    items.push({
+      id,
+      criterion: cells[2] ?? "",
+      testType: cells[3] ?? "",
+      priority: cells[4] ?? "",
+    });
+  }
+  return items;
+}
+
+export function parseVisualAcRequirements(items) {
+  const out = [];
+  for (const item of items) {
+    if (!/visual/i.test(item.testType ?? "")) continue;
+    const criterion = item.criterion ?? "";
+    const baselineRefs = [...new Set((criterion.match(IMAGE_REF_RE) ?? []).map((s) => s.trim()))];
+    const diffMatch = criterion.match(DIFF_PERCENT_RE);
+    out.push({
+      acId: item.id,
+      criterion,
+      baselineRefs,
+      maxDiffPercent: diffMatch ? Number(diffMatch[1]) : null,
+    });
+  }
+  return out;
+}
+
+function walkImages(dir, out) {
+  if (!fs.existsSync(dir)) return;
+  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, ent.name);
+    if (ent.isDirectory()) walkImages(full, out);
+    else if (/\.(png|jpe?g|webp)$/i.test(ent.name)) out.push(full);
+  }
+}
+
+export function listPrdSourceImages(outputRoot) {
+  const images = [];
+  walkImages(path.join(outputRoot, "source"), images);
+  return images;
+}
+
+export function resolveBaselinePath(pkgRoot, outputRoot, ref, prdImages) {
+  const normalized = ref.replace(/\\/g, "/");
+  const candidates = [];
+  if (outputRoot) {
+    candidates.push(path.join(outputRoot, normalized));
+    candidates.push(path.join(outputRoot, "visual-baseline", path.basename(normalized)));
+  }
+  candidates.push(path.join(pkgRoot, normalized));
+  candidates.push(path.join(pkgRoot, "visual-baseline", path.basename(normalized)));
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  if (/^image_\d+\./i.test(normalized)) {
+    const hit = prdImages.find((p) => path.basename(p) === path.basename(normalized));
+    if (hit) return hit;
+  }
+  return prdImages.find((p) => p.endsWith(`/${path.basename(normalized)}`)) ?? null;
+}
+
+function e2eBlockHasVisualAssertion(body) {
+  return TO_HAVE_SCREENSHOT_RE.test(stripComments(body));
+}
+
+function e2eReferencesBaseline(body, baselineRefs) {
+  const stripped = stripComments(body);
+  if (baselineRefs.length === 0) return TO_HAVE_SCREENSHOT_RE.test(stripped);
+  return baselineRefs.some((ref) => {
+    const base = path.basename(ref).replace(/\.(png|jpe?g|webp)$/i, "");
+    return (
+      stripped.includes(ref) ||
+      stripped.includes(base) ||
+      stripped.includes(`'${base}'`) ||
+      stripped.includes(`"${base}"`)
+    );
+  });
+}
+
+export function collectChangeE2eSpecs(root, changeName) {
+  const changeDir = path.join(root, "openspec/changes", changeName);
+  const specs = new Set();
+  let blob = "";
+  for (const f of ["tasks.md", "proposal.md", "design.md"]) {
+    const fp = path.join(changeDir, f);
+    if (!fs.existsSync(fp)) continue;
+    blob += fs.readFileSync(fp, "utf8");
+  }
+  const re = /\be2e\/[\w/.-]+\.spec\.(?:ts|js)\b/g;
+  let m;
+  while ((m = re.exec(blob)) !== null) {
+    const rel = m[0];
+    if (fs.existsSync(path.join(root, rel))) specs.add(rel);
+  }
+  return [...specs].sort();
+}
+
+export function assessVisualRegression(root, outputRoot, changeName, acItems) {
+  const errors = [];
+  const visualReqs = parseVisualAcRequirements(acItems);
+  const prdImages = outputRoot ? listPrdSourceImages(outputRoot) : [];
+  const specPaths = collectChangeE2eSpecs(root, changeName);
+
+  const tasksPath = path.join(root, "openspec/changes", changeName, "tasks.md");
+  if (fs.existsSync(tasksPath) && /^VISUAL_REGRESSION_EXEMPT:/m.test(fs.readFileSync(tasksPath, "utf8"))) {
+    return { errors: [], visualReqs, exempt: true };
+  }
+
+  if (prdImages.length > 0 && visualReqs.length === 0) {
+    errors.push(
+      `PRD source 含 ${prdImages.length} 张原型图，但 05 无 visual AC；请补充基线对比验收项`,
+    );
+    return { errors, visualReqs, exempt: false };
+  }
+
+  if (visualReqs.length === 0) return { errors: [], visualReqs, exempt: false };
+
+  let e2eBlob = "";
+  const e2eBlocks = [];
+  for (const rel of specPaths) {
+    const content = fs.readFileSync(path.join(root, rel), "utf8");
+    e2eBlob += content;
+    for (const block of parseTestBlocks(content)) {
+      e2eBlocks.push({ spec: rel, title: block.title, body: block.body });
+    }
+  }
+
+  if (specPaths.length === 0) errors.push("含 visual AC 但未绑定 e2e spec");
+  else if (!TO_HAVE_SCREENSHOT_RE.test(e2eBlob)) {
+    errors.push("e2e 须使用 toHaveScreenshot（禁止仅 page.screenshot）");
+  }
+
+  for (const req of visualReqs) {
+    if (req.baselineRefs.length === 0) {
+      errors.push(`${req.acId}: visual AC 须写明基线路径`);
+      continue;
+    }
+    for (const ref of req.baselineRefs) {
+      if (!resolveBaselinePath(root, outputRoot, ref, prdImages)) {
+        errors.push(`${req.acId}: 基线图不存在 ${ref}`);
+      }
+    }
+    const bound = e2eBlocks.filter(
+      (b) =>
+        testBlockReferencesAc({ title: b.title, body: b.body, index: 0 }, req.acId) &&
+        e2eBlockHasVisualAssertion(b.body),
+    );
+    if (bound.length === 0) {
+      errors.push(`${req.acId}: e2e 须含 [${req.acId}] + toHaveScreenshot`);
+      continue;
+    }
+    if (!bound.some((b) => e2eReferencesBaseline(b.body, req.baselineRefs))) {
+      errors.push(
+        `${req.acId}: toHaveScreenshot 须引用 ${req.baselineRefs.map((r) => path.basename(r)).join("、")}`,
+      );
+    }
+  }
+
+  if (PAGE_SCREENSHOT_ONLY_RE.test(e2eBlob) && !TO_HAVE_SCREENSHOT_RE.test(e2eBlob)) {
+    errors.push("仅有 page.screenshot 无 toHaveScreenshot");
+  }
+
+  return { errors, visualReqs, exempt: false };
+}

package/src/templates/artifacts/04-/346/212/200/346/234/257/346/226/207/346/241/243.template.md

@@ -158,6 +158,14 @@ type ExampleEntity = {
 
 ### 4.3 响应数据映射（API -> UI）
 
+#### 4.3.1 响应字段映射表（门禁 SSOT，对接后端须逐字段登记）
+
+| 后端字段 | 前端字段 | 展示位置 | 兜底值 |
+| --- | --- | --- | --- |
+| `subject_id` | `subjectId` | 列表第1列 | `-` |
+| `subject_name` | `subjectName` | 列表项目名称 | `-` |
+| （填写） | （填写） | （填写） | `-` |
+
 - 展示字段组装规则：
 - 兜底值处理：
 - 时间/金额/百分比格式化规则：

package/src/templates/artifacts/05-/351/252/214/346/224/266/346/270/205/345/215/225.template.md

@@ -11,8 +11,8 @@
 ## 填写规则
 
 1. **ID**：`AC-01`、`AC-02`… 全局唯一。
-2. **验收标准**：必须可观测（DOM 顺序、完整 toast/tooltip 文案、E2E 路径、截图对比等）；**详情/弹窗类须写明演示模块名**（如「对齐演示 ProjectDetail §红票及其他」）。
-3. **测试类型**：`unit` | `component` | `e2e` | `visual` | `manual`（可组合，如 `unit+e2e`）。
+2. **验收标准**：必须可观测（DOM 顺序、完整 toast/tooltip 文案、E2E 路径、**截图基线对比**等）；含 PRD 原型图时须写 `source/.../image_N.png` 或 `visual-baseline/xxx.png` 与 `diff≤2%`。
+3. **测试类型**：`unit` | `component` | `e2e` | `visual` | `manual`（可组合，如 `unit+e2e+visual`）。**PRD source 含 `.png` 原型图时，至少 1 条 P0/P1 `visual` AC**。
 4. **优先级**：`P0`（交付阻断）/ `P1` / `P2`。
 5. **映射**：propose 后在 `openspec/changes/<change>/tasks.md` 或 `spec.md` 中引用 `[AC-XX]`；**tasks 须有「演示模块迁移」段，与 design 映射表一行一任务**。
 6. **Intentional 偏差**：与 PRD 有意不一致时，必须同步记入 `03-待确认问题清单.md` 并在下文登记。
@@ -23,6 +23,7 @@
 |----|---------|-------------------|---------|--------|-------------------|---------|
 | AC-01 | PRD §（填写） | （填写可观测断言，toast/tooltip 须一字不差） | unit | P0 | 待映射 | 待验收 |
 | AC-02 | PRD §（填写） | （填写） | e2e | P1 | 待映射 | 待验收 |
+| AC-02-V | PRD §（填写） | 列表页与基线 `source/.../image_1.png` 布局一致（diff≤2%） | visual+e2e | P1 | e2e/*.spec.ts | 待验收 |
 
 ## Intentional 偏差登记
 

package/src/templates/artifacts/design-demo-reference.template.md

@@ -10,11 +10,11 @@
 
 ### 演示模块 → 生产组件映射（门禁 SSOT）
 
-| 演示模块 | 演示文件/组件 | 生产组件路径 | 关键交互信号（须在生产代码出现） |
-|---------|--------------|-------------|--------------------------------|
-| （示例）列表页 | FinancialOverview.vue | src/views/finance/index.vue | 请输入项目ID或名称、拉取欢聚最新数据 |
-| （示例）详情-BD预估 | ProjectDetail.vue | src/views/finance/components/BdEstimateSection.vue | 编辑预估、BD预计开票日期、距BD预计 |
-| （示例）详情-红票 | ProjectDetail.vue | src/views/finance/components/RedInvoiceSection.vue | 红票及其他、添加记录、红票 |
+| 演示模块 | 演示文件/组件 | 生产组件路径 | 关键交互信号（须在生产代码出现） | E2E 点击绑定（getByText/click） |
+|---------|--------------|-------------|--------------------------------|--------------------------------|
+| （示例）列表页 | FinancialOverview.vue | src/views/finance/index.vue | 请输入项目ID或名称、拉取欢聚最新数据 | getByPlaceholder('请输入项目ID或名称') |
+| （示例）详情-BD预估 | ProjectDetail.vue | src/views/finance/components/BdEstimateSection.vue | 编辑预估、BD预计开票日期 | getByRole('button', { name: '编辑预估' }).click() |
+| （示例）详情-红票 | ProjectDetail.vue | src/views/finance/components/RedInvoiceSection.vue | 红票及其他、添加记录 | getByText('添加记录').click() |
 | （填写） | | | |
 
 ### 禁止的实现方式

package/src/templates/artifacts/tests-fixtures-readme.template.md

@@ -0,0 +1,19 @@
+# API Fixture 样例（v1.3.20 门禁）
+
+将**联调/抓包**得到的真实后端 JSON 放在此目录（保持 **snake_case** 键名）。
+
+## 命名建议
+
+- `finance-subject-page.json` — 列表分页响应
+- `finance-subject-info.json` — 详情 subject-info
+- `finance-subject-detail.json` — 详情 subject-detail
+
+## 要求
+
+1. 须含 `_` 分隔的后端字段（如 `subject_id`），禁止手写全 camelCase 空对象
+2. 配套单测：`tests/**/caseTransform.test.ts` 加载本目录 JSON，`snakeToCamelDeep` 后 `expect` 关键 camelCase 字段
+3. 04 技术文档 §4.3.1 字段映射表须与 fixture 字段一致
+
+## 门禁
+
+`assess-api-field-coverage.mjs` 在 deliver 阶段校验。

package/src/templates/artifacts/visual-baseline-readme.template.md

@@ -0,0 +1,28 @@
+# visual-baseline（L4 视觉回归基线）
+
+> 由 `sdd-flow-kit` 在 PRD run 脚手架时创建。与 `source/` 下 PRD 原型图配合使用。
+
+## 用途
+
+- 存放 **裁剪后的 UI 基线截图**（可选；也可直接引用 `source/**/image_N.png`）
+- `05-验收清单.md` 中 `visual` 类型 AC 须在「验收标准」写明基线路径，例如：
+  - `列表页与基线 source/adi-v234/image_1.png 布局一致（diff≤2%）`
+  - `详情抽屉与 visual-baseline/finance-detail.png 一致（diff≤2%）`
+
+## E2E 要求（v1.3.21 门禁）
+
+```typescript
+await expect(page).toHaveScreenshot("finance-report-list.png", {
+  maxDiffPixelRatio: 0.02,
+});
+```
+
+- 须与 `[AC-xx]` 同处一个 test 块
+- **禁止**仅用 `page.screenshot()` 代替 `toHaveScreenshot`
+- Playwright 快照目录默认：`e2e/finance/*.spec.ts-snapshots/` 或与基线名一致
+
+## 门禁
+
+`assess-visual-regression.mjs` 在 deliver 阶段校验。
+
+豁免：`tasks.md` 写 `VISUAL_REGRESSION_EXEMPT: <原因>` 或 `OPSX_SKIP_VISUAL_REGRESSION=1`

package/src/templates/prompts/04-tech-doc-fill-prompt.md

@@ -41,13 +41,18 @@
 
 ### §4 接口与数据交互
 - **4.1 表格**：接口路径 | Method | 用途 | 请求字段 | 响应字段 | 异常处理
-- **4.3** 写明后端 SNAKE_CASE → 前端 camelCase normalize 位置（如 `config/api/modules/*/caseTransform`）
+- **4.3** 写明 normalize 位置 + **4.3.1 字段映射表**（| 后端字段 | 前端字段 |）；`tests/fixtures/<module>/*.json` 放联调抓包样例
 - 提交 payload 示例（JSON）
 
 ### §5 表单与校验
 - 关键弹窗/编辑字段校验矩阵（必填、格式、错误文案）
 
-### §6–§11
+### §2.5 视觉基线（PRD 含原型图时必填）
+
+- 基线图路径：`source/.../image_N.png` 或 `visual-baseline/xxx.png`
+- 在 `05-验收清单.md` 增加 `visual` 类型 AC，写明 `diff≤2%`
+- E2E 使用 `toHaveScreenshot`，禁止仅 `page.screenshot`
+
 - 边界场景、文件级改造清单（**禁止**只写一个大组件名）、风险表、发布检查、测试要点与 05 AC 对应、待确认项（无则写「无」）
 
 ---

package/src/templates/skills/demo-reference-mandatory-workflow.md

@@ -57,7 +57,9 @@
 ## 阶段 E — Validate / Deliver
 
 - `assess-demo-implementation-coverage.mjs`：映射表中的生产文件存在，且含「关键交互信号」
-- `assess-e2e-assertion-depth.mjs`：E2E 须点到演示中的主按钮/区块（非 placeholder-only）
+- `assess-component-substance.mjs`（v1.3.19）：组件非空壳（≥40 有效行、template 含控件、API/emit）；Section/Modal 须被父组件 import
+- `assess-ac-assertion-binding.mjs`（v1.3.19）：P0 AC 的 05 验收标准字面量须出现在 test expect 中；禁止纯 manual P0
+- `assess-e2e-assertion-depth.mjs`：E2E 须数据/交互断言；**可点击信号**须在 spec 中有 click/getByText（v1.3.19）
 - 08 报告证据须指向 **具体组件文件 + 行号 + 交互文案**
 
 ## 05 验收清单

package/src/templates/skills/layered-testing-strategy.md

@@ -6,11 +6,13 @@
 
 | 层级 | 覆盖范围 | 典型断言 | 缺失风险 | 门禁 |
 |------|---------|---------|---------|------|
-| **L1 能力** | API、状态机、mapper、脏数据 | 接口封装、枚举映射、mutation 参数、**snake/camel normalize** | 主流程不通、列表空数据 | `assess-api-field-contract.mjs` + unit |
+| **L1 能力** | API、状态机、mapper、脏数据 | 接口封装、枚举映射、mutation 参数、**snake/camel normalize** + **fixture 字段覆盖** | 主流程不通、列表空数据 | `assess-api-field-contract.mjs` + `assess-api-field-coverage.mjs` + unit |
 | **L2 交互契约** | 列序、disabled、toast、tooltip、placeholder | **完整字符串**（禁止 `toContain('成功')`） | PRD 细节漏项 | AC 映射须 test 块内 `expect` |
 | **L3 路径** | 每页面/每主链路一条 E2E | 登录 → 列表有数据 → 点详情 → **演示映射中的按钮/区块** | 只 smoke placeholder | `assess-e2e-assertion-depth.mjs` |
-| **L3.5 演示迁移** | 演示模块 → 生产组件 1:1 | design 映射表每行在生产代码有「关键交互信号」 | 单文件只读骨架代替演示 | `assess-demo-implementation-coverage.mjs` |
-| **L4 视觉** | 原型图 / Figma / `playwright-pic` | 列位置、紫色摘要、布局两行限制 | UI 与原型偏差 | 人工 + 截图 |
+| **L3.5 演示迁移** | 演示模块 → 生产组件 1:1 | design 映射表每行在生产代码有「关键交互信号」+ **非空壳组件** | 单文件只读骨架代替演示 | `assess-demo-implementation-coverage.mjs` + `assess-component-substance.mjs` |
+| **L3.6 AC 断言绑定** | P0 验收标准字面量 | test expect 含 05 原文（禁止模糊 toContain('成功')） | PRD 文案漏测 | `assess-ac-assertion-binding.mjs` |
+| **L3.7 E2E 演示点击** | 映射表中可点击信号 | spec 中 click/getByText 覆盖「编辑/保存/导入」等 | 有按钮无点击 | `assess-e2e-assertion-depth.mjs`（含 demo signal） |
+| **L4 视觉** | 原型图 / PRD 截图 / `visual-baseline` | `toHaveScreenshot` + 基线图 diff≤N% | UI 与原型偏差 | `assess-visual-regression.mjs`（v1.3.21） |
 
 ## 禁止伪覆盖