diff --git a/.gitignore b/.gitignore index ddbae71..0d3fb59 100644 --- a/.gitignore +++ b/.gitignore @@ -74,3 +74,5 @@ backend/gencode # design-distill 保真目检对比图(可重生,见 tools/ds-compare.mjs) design/_compare/ +# fidelity diff 差异图(可重生,见 tools/fidelity.mjs);原型基准 proto/ 仍入库 +design/_fidelity/ diff --git a/client/test/golden/proto/inventory_list_a.png b/client/test/golden/proto/inventory_list_a.png new file mode 100644 index 0000000..6fda788 Binary files /dev/null and b/client/test/golden/proto/inventory_list_a.png differ diff --git a/tools/fidelity.mjs b/tools/fidelity.mjs new file mode 100644 index 0000000..56cc7bd --- /dev/null +++ b/tools/fidelity.mjs @@ -0,0 +1,130 @@ +#!/usr/bin/env node +/** + * fidelity.mjs — 还原保真闸:Flutter golden vs 原型(真·跟原型比,替掉 golden 自比) + * + * 背景:Flutter golden 是「自己渲染→存基准→再渲染→比基准」,结构上永远发现不了 + * 「跟原型长得不一样」。本脚本把每屏的 **原型截图当基准**,与 **Flutter golden** 做 + * pixelmatch diff,超「逐屏校准阈值」即红 —— 这才是真正的保真证据。 + * + * 跨渲染器(原型 Chromium ↔ Flutter Skia)做不到 0% 像素,故: + * ① 两边统一字体:原型注入 Noto Sans SC 覆盖 --font/--font-mono(见 _inject CSS), + * Flutter 侧 ThemeData.fontFamily 已是 NotoSansSC(pubspec 打包)。 + * ② 阈值逐屏校准(密表/外壳噪声不同),抓「缺顶栏/缺卡片/错列」类结构性差异; + * 像素级细节靠 ds-compare 人工 montage 目检兜底。 + * + * 前置:先生成对应 Flutter golden: + * cd client && flutter test --update-goldens test/golden/_golden_test.dart + * + * 用法(仓库根运行): + * node tools/fidelity.mjs # 跑注册表里所有屏 × 所有主题 + * node tools/fidelity.mjs inventory # 只跑某屏 + * node tools/fidelity.mjs inventory --themes a # 指定主题 + * node tools/fidelity.mjs --update # 仅刷新原型基准图(proto/),不判定 + * + * 产物: + * client/test/golden/proto/_.png 原型基准(入库,prototype 变更时刷新) + * design/_fidelity/__diff.png 差异图(gitignore,可重生) + * + * 退出码:任一屏×主题超阈 → 1(可作 pre-commit / CI 闸)。 + */ +import { parseArgs } from 'node:util'; +import { execFileSync } from 'node:child_process'; +import { mkdirSync, existsSync, writeFileSync } from 'node:fs'; +import { homedir, tmpdir } from 'node:os'; +import { join, resolve } from 'node:path'; + +// ── 逐屏注册表 ──────────────────────────────────────────────────────────────── +// width/height = golden 的「逻辑」尺寸(golden 物理像素 = 逻辑 × dpr);两边须一致。 +// prefix = golden 文件前缀 client/test/golden/goldens/_.png。 +// threshold = 该屏校准阈值(差异像素比例上限);首版人工目检「像」后把当时 diff% + 余量记此。 +// 注:屏随 Phase 2 逐个照原型重建后再把其 prefix 入册并校准阈值。 +const SCREENS = { + inventory: { + html: '.superpowers/prototype/screens/inventory.html', + prefix: 'inventory_list', + width: 1280, height: 900, dpr: 2, + waitFor: '.app', + threshold: 0.20, // 旧屏未重建,暂宽松;Phase 2 重建后收紧 + }, +}; + +const { values, positionals } = parseArgs({ + allowPositionals: true, + options: { + themes: { type: 'string', default: 'a,b,c' }, + update: { type: 'boolean', default: false }, // 仅刷新原型基准,不判定 + tolerance: { type: 'string', default: '0.1' }, + help: { type: 'boolean', default: false }, + }, +}); + +if (values.help) { + console.log(`用法: node tools/fidelity.mjs [screen] [--themes a,b,c] [--update] [--tolerance 0.1]\n已注册屏: ${Object.keys(SCREENS).join(', ')}`); + process.exit(0); +} + +const SKILL = process.env.DD_SKILL || join(homedir(), '.claude/skills/design-distill'); +const shoot = join(SKILL, 'tools/shoot-prototype.mjs'); +const diff = join(SKILL, 'tools/diff.mjs'); +for (const t of [shoot, diff]) { + if (!existsSync(t)) { console.error(`[fidelity] 找不到 skill 工具: ${t}(设 DD_SKILL 覆盖)`); process.exit(2); } +} + +const protoDir = 'client/test/golden/proto'; +const diffDir = 'design/_fidelity'; +mkdirSync(protoDir, { recursive: true }); +mkdirSync(diffDir, { recursive: true }); + +// 统一字体注入:把原型的 --font/--font-mono 覆盖为 NotoSansSC(与 Flutter golden 同字体)。 +// 字体经 shoot 临时 http server(root=cwd)按 /client/... 路径供给。 +const injectCss = join(tmpdir(), 'jiu-fidelity-font.css'); +writeFileSync(injectCss, [ + `@font-face{font-family:'NotoSansSC';src:url('/client/assets/fonts/NotoSansSC.ttf');font-weight:100 900;font-display:block;}`, + `:root{--font:'NotoSansSC',sans-serif!important;--font-mono:'NotoSansSC',monospace!important;}`, + `*{font-family:'NotoSansSC',sans-serif!important;}`, +].join('\n')); + +const wantThemes = values.themes.split(',').map((s) => s.trim()).filter(Boolean); +const targets = positionals.length ? positionals : Object.keys(SCREENS); + +let failed = 0, ran = 0; +for (const name of targets) { + const s = SCREENS[name]; + if (!s) { console.error(`[fidelity] 未注册屏: ${name}(有: ${Object.keys(SCREENS).join(', ')})`); failed++; continue; } + for (const theme of wantThemes) { + const proto = join(protoDir, `${s.prefix}_${theme}.png`); + const golden = resolve('client/test/golden/goldens', `${s.prefix}_${theme}.png`); + const out = join(diffDir, `${s.prefix}_${theme}_diff.png`); + + // ① 原型基准图(注入统一字体) + execFileSync('node', [shoot, s.html, proto, + '--width', String(s.width), '--height', String(s.height), '--dpr', String(s.dpr), + '--theme', theme, '--lang', 'zh', '--wait-for', s.waitFor, + '--inject-css', injectCss, '--wait', '1200'], + { stdio: 'inherit' }); + + if (values.update) { console.log(`[fidelity] 🔄 刷新基准 ${proto}`); continue; } + + // ② Flutter golden 必须已生成 + if (!existsSync(golden)) { + console.error(`[fidelity] ⚠ 缺 Flutter golden: ${golden} —— 先 flutter test --update-goldens。判定失败。`); + failed++; continue; + } + + // ③ diff,超「该屏校准阈值」即红 + ran++; + try { + execFileSync('node', [diff, proto, golden, out, + '--threshold', String(s.threshold), '--tolerance', values.tolerance], + { stdio: 'inherit' }); + console.log(`[fidelity] ✅ ${name}·${theme} ≤ 阈值 ${(s.threshold * 100).toFixed(1)}%`); + } catch { + console.error(`[fidelity] ❌ ${name}·${theme} 超阈 ${(s.threshold * 100).toFixed(1)}% — 看 ${out}`); + failed++; + } + } +} + +if (values.update) { console.log(`[fidelity] 基准刷新完成。`); process.exit(0); } +console.log(`\n[fidelity] 跑了 ${ran} 屏×主题,失败 ${failed}。`); +process.exit(failed ? 1 : 0);