From c66dfcac262468080c0066b2a415c298d2c10e3e Mon Sep 17 00:00:00 2001 From: zhangxiang Date: Thu, 8 Oct 2026 17:03:24 +0800 Subject: [PATCH] =?UTF-8?q?docs(qa):=20=E5=9F=BA=E7=BA=BF=E5=88=A4?= =?UTF-8?q?=E7=BA=A2=E5=BD=92=E5=9B=A0=E6=94=B9=E5=88=A4=EF=BC=8C=E4=BD=9C?= =?UTF-8?q?=E5=BA=9F=E3=80=8C=E8=BF=90=E8=A1=8C=E6=9C=9F=E6=BC=82=E7=A7=BB?= =?UTF-8?q?=E3=80=8D=E5=88=9D=E5=88=A4=E5=B9=B6=E8=A1=A5=20lessons=20?= =?UTF-8?q?=C2=A75.33?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 台账 §9.4 初稿把 chromium-mobile 两页 +30/+21px 记为「零源码改动 ⇒ 只能来自 运行期」,参照系用错:旧参照的采集树是 040951c(09-22),当前树含 a366bd1 (09-28 第五轮),参照比树旧了一个修复轮次。 - 实测归因:row-diff.cjs(sharp 逐行比对)定位发散行 y=7440 落在 /products/erp 的 benefits 段;git diff 显示 Q-6 把指标 count-up 从 render 体迁入 useEffect 并加取消 ⇒ 旧参照冻结的是动画中间帧,新参照是稳定终态,属预期改进 - 排除数据侧:prisma/seeds/products.ts 在该窗口零改动 - 三条口径落到 lessons §5.33:归因须对「采集树 vs 当前树」;基线数量须标「例/张」 (本轮 38 张 = 31 例);裸 --update-snapshots 实为 changed 模式,不重写通过项 - §9.5 的 G 项就此关闭,取证脚本随证据目录入库 --- .../2026-10-08-baselines/attribution.md | 8 ++- .../2026-10-08-baselines/row-diff.cjs | 55 +++++++++++++++++++ docs/acceptance/qa-tracker.md | 7 ++- docs/lessons-learned.md | 16 ++++++ 4 files changed, 82 insertions(+), 4 deletions(-) create mode 100644 docs/acceptance/2026-10-08-baselines/row-diff.cjs diff --git a/docs/acceptance/2026-10-08-baselines/attribution.md b/docs/acceptance/2026-10-08-baselines/attribution.md index 378e9f9..34304e8 100644 --- a/docs/acceptance/2026-10-08-baselines/attribution.md +++ b/docs/acceptance/2026-10-08-baselines/attribution.md @@ -44,9 +44,13 @@ - `product-card-visual-chromium-desktop.png`:`bento-product-card-erp` 卡(标题 + 研发中/企业套装徽标 + 指标三格 + 目标口径注 + 能力标签)。中部留白**不是**渲染缺失:`products-content-v3.tsx:137` 的 `

` 在 large 卡里撑高,文本仅占顶部一行——同一形态在**已批准**的 `products-fullpage-visual-chromium-desktop.png` 里逐字一致,故新参照与既有批准基线同形。选择器锚点为 `[data-testid^="bento-product-card-"]` + `role="listitem"` + `data-bento-size` 三重钉住(`:154-157`)。 - `button-default-visual-chromium-mobile.png`:44x44 汉堡按钮(三横线),与 N-15(c) 实测结论一致。 -## 5. 观察项(不阻断,登记备查) +## 5. 观察项与归因更正(2026-10-08 本轮内自我改判) -1. **chromium-mobile 两页 +30 / +21px 未归因**:与桌面族「大幅收缩」形态不同,移动档本来就是单列,网格修复不改高度。本轮 `1396666` 相对封版点 `a0328a6` **零生产源码改动**(29 文件全在 `docs/ specs/ e2e/ README .claude .mcp`),故该位移来自**运行期**(CMS 数据行或日期派生内容)而非代码。影响:新基线吸收了一次未归因的小位移;若后续出现移动档全页判红,先查此处。 +1. **chromium-mobile 两页 +30 / +21px 已归因,且不是运行期漂移**(本条初稿曾误判为「位移只能来自运行期」,已作废): + - 归因错在参照系。旧参照的**采集树**是 `040951c`(2026-09-22 规范模式重生成),最后一次被改动是 `6bb7c55`(2026-09-28 10:48);而当前树含 `a366bd1`(第五轮修复,2026-09-28 10:48:07)与 `a0328a6`。⇒ 判红须对「采集树 vs 当前树」做 diff,而不是「上一轮提交 vs 本轮提交」。本轮「相对 `a0328a6` 零生产源码改动」只保证**门禁绿灯可平移**,不保证**参照与树同源**。 + - 机理已定位:`src/components/detail/detail-product-value.tsx` 在 `a366bd1` 里做了 Q-6 修复——指标数字 count-up 动画原先写在 **render 体内**(每帧 `setState` 再 spawn 一条从 0 开始的 rAF 链、从不取消),改为 `useEffect` 驱动并在卸载/重跑时取消(diff 见 `:70-100`)。旧参照拍到的是**动画竞态中的中间帧**,新参照拍到稳定终态 ⇒ 指标卡文本/高度小幅位移,属预期改进。 + - 现场取证:`node docs/acceptance/2026-10-08-baselines/row-diff.cjs <参照路径> `(sharp 逐行比对)现取首个发散行 = **y 7440**(`product-erp-fullpage` mobile,共 24453/24483 行),该处正是 `/products/erp` 的 `benefits` 价值列表段;裁图对照显示新参照出现发丝分隔线且条目间距收紧。 2. **仓库体积**:新增 25 张 PNG 共 **17,192 KB**(最大单张 `product-erp-upgrade-fullpage-visual-chromium-mobile.png` 2,472 KB),13 张覆盖净变化为负(如 webkit erp 2,303,020 → 2,066,938 字节)。 3. **采集口径**:dev 目标。`docs/testing.md` §确定性约束 1 已实证「快照与 `E2E_TARGET` 无关」(`e2e/fixtures.ts` 剥 `nextjs-portal`),故 production 复核不会因此全红;`e2e/visual-snapshots` 现共 132 张(含 `manual-acceptance/` 2 张)。 4. **只读比对的前置**:跑前 `lsof :3000` 空闲、无 `next-server` 残留 ⇒ 未落入 `reuseExistingServer` 静默复用旧构建的坑(`docs/development/quality-gates.md:163`)。 +5. **残留风险(改判后仍留一条)**:Q-6 族的其他 count-up 消费点若仍有 render 体内动画,基线仍可能拍到中间帧。本轮 125/0 只证明**当前树自洽可复现**,不证明「参照=用户所见」;下一次跨树复核(如 production 目标或换 DPR 档)若出现指标卡判红,按本条查。 diff --git a/docs/acceptance/2026-10-08-baselines/row-diff.cjs b/docs/acceptance/2026-10-08-baselines/row-diff.cjs new file mode 100644 index 0000000..a100033 --- /dev/null +++ b/docs/acceptance/2026-10-08-baselines/row-diff.cjs @@ -0,0 +1,55 @@ +const { execFileSync } = require('node:child_process'); +const fs = require('node:fs'); +const path = require('node:path'); +const sharp = require('sharp'); + +const repo = process.cwd(); +const rel = process.argv[2]; +const outDir = process.argv[3] || '/tmp/vsdiff'; +const oldRef = process.argv[4] || '1396666'; +fs.mkdirSync(outDir, { recursive: true }); + +const oldBuf = execFileSync('git', ['show', `${oldRef}:${rel}`], { maxBuffer: 1 << 28 }); +fs.writeFileSync(path.join(outDir, 'old.png'), oldBuf); +const newBuf = fs.readFileSync(path.join(repo, rel)); +fs.writeFileSync(path.join(outDir, 'new.png'), newBuf); + +async function raw(f) { + const img = sharp(f).ensureAlpha(); + const { data, info } = await img.raw().toBuffer({ resolveWithObject: true }); + return { data, w: info.width, h: info.height, ch: info.channels }; +} + +(async () => { + const a = await raw(path.join(outDir, 'old.png')); + const b = await raw(path.join(outDir, 'new.png')); + console.log(`old ${a.w}x${a.h} new ${b.w}x${b.h}`); + const w = Math.min(a.w, b.w); + const rows = Math.min(a.h, b.h); + const firstDiffRows = []; + for (let y = 0; y < rows; y++) { + let diff = 0; + const oa = y * a.w * a.ch, ob = y * b.w * b.ch; + for (let x = 0; x < w; x++) { + for (let c = 0; c < 3; c++) { + const d = Math.abs(a.data[oa + x * a.ch + c] - b.data[ob + x * b.ch + c]); + if (d > 24) { diff++; if (diff > 40) break; } + } + if (diff > 40) break; + } + if (diff > 40) { + firstDiffRows.push(y); + if (firstDiffRows.length >= 1 && y - firstDiffRows[0] > 400) break; + } + } + if (!firstDiffRows.length) { console.log('no divergence in shared region'); return; } + const start = firstDiffRows[0]; + let end = start; + for (const y of firstDiffRows) end = y; + console.log(`first divergent row = ${start}, last in burst = ${end}, burst rows = ${firstDiffRows.length}`); + const top = Math.max(0, start - 260); + const height = Math.min(b.h - top, 900); + await sharp(path.join(outDir, 'new.png')).extract({ left: 0, top, width: b.w, height }).png().toFile(path.join(outDir, 'crop-new.png')); + await sharp(path.join(outDir, 'old.png')).extract({ left: 0, top, width: a.w, height: Math.min(a.h - top, 900) }).png().toFile(path.join(outDir, 'crop-old.png')); + console.log(`crops written to ${outDir}/crop-{new,old}.png (top=${top}, h=${height})`); +})(); diff --git a/docs/acceptance/qa-tracker.md b/docs/acceptance/qa-tracker.md index 59f6bc7..faf6eca 100644 --- a/docs/acceptance/qa-tracker.md +++ b/docs/acceptance/qa-tracker.md @@ -358,7 +358,10 @@ S-3(about/contact/erp-upgrade 无 revalidate + revalidateTag no-op,涉渲染 ### 9.4 自证循环的处置(为什么这次「绿」仍然可失败) 基线由本轮自采,采集当下的绿本身不含信息量。使其仍具判别力的四点:① 容差未动(`e2e/playwright.config.ts:38-40`,`maxDiffPixels: 200` / `maxDiffPixelRatio` / `threshold: 0.3` 与历轮一致,无放宽);② `changed` 模式不重写通过项(9.2-①);③ 判定用的是**另一次独立运行**,写盘与只读之间隔了完整 server 生命周期(起停各一次);④ 三张关键新参照经人眼读图而非仅看退出码(9.3)。 -**残留风险(登记不阻断)**:chromium-mobile 两页全页仅 +30 / +21px 高度变化,与桌面族「大幅收缩」形态不同,未归因;因本轮相对 `a0328a6` 零生产源码改动,位移只能来自运行期(CMS 数据行或日期派生内容)。若后续移动档全页判红,先查此处。 + +**本小结初稿曾有一条错判,已作废并就地更正(双归零)**:原写「chromium-mobile 两页 +30/+21px 未归因;本轮相对 `a0328a6` 零生产源码改动 ⇒ 位移只能来自运行期(CMS 数据行或日期派生内容)」。参照系用错了——旧参照的**采集树**是 `040951c`(2026-09-22),最后被改动是 `6bb7c55`(09-28 10:48),而当前树含 `a366bd1`(09-28 10:48:07 第五轮)与 `a0328a6`。实测归因:`src/components/detail/detail-product-value.tsx` 的 Q-6 修复把指标 count-up 动画从 **render 体内**(每帧 `setState` 再 spawn 一条从 0 起的 rAF 链、从不取消)迁入 `useEffect` 并加取消 ⇒ 旧参照拍到的是**动画竞态中间帧**,新参照是稳定终态,位移属预期改进。现场取证法:`docs/acceptance/2026-10-08-baselines/row-diff.cjs`(sharp 逐行比对)现取首个发散行 y=7440,正落在 `/products/erp` 的 `benefits` 价值列表段。 +**管理归零(写进检查口径)**:「本轮相对上一轮零源码改动」只支撑**门禁绿灯平移**,**不支撑**「参照与当前树同源」;判红归因必须对「基线采集树 vs 当前树」做 diff。历轮把 11 例笼统记为「网格修复的预期收缩」正是漏了这个参照系,才让 mobile 那 2 例看起来「无因」。 +**改判后仍留的一条风险**:Q-6 族若还有其他 render 体内动画,基线仍可能冻结中间帧;125/0 只证明**当前树自洽可复现**,不证明「参照 = 用户所见」。 ### 9.5 更新后的待授权清单(下一轮从这里接) @@ -367,5 +370,5 @@ S-3(about/contact/erp-upgrade 无 revalidate + revalidateTag no-op,涉渲染 | B | 建 PR / 合并 `main` | **人工可解,脚本不可解** | 本环境仍无 Gitea token(2026-10-08 复探:`env` 无 token、`~/.config/gitea` 与 `~/.gitea` 不存在、`git config` 无 credential);但 `git push` 回显已给出创建入口 `https://git.f.novalon.cn/novalon/novalon-website/pulls/new/qa/seal-2026-09-28`,浏览器登录即可建。**PR 描述文件现状**:`.pr-seal-2026-09-30.md` 过 `scripts/check-pr-checklist.sh`(EXIT=0),但叙述停在 seal 轮,须追加 §8(agentic 工具化 + `nav-keyboard`)与 §9(基线入库、视觉转绿)两轮内容后才可用 | | C | `npm run deploy` | 仍不建议 | 理由 ①(视觉 EXIT=1)已消除;② 需先完成 B、③ `deploy:rollback` 不回滚容器/`public/` 两条仍成立 | | F | `6ff19d1` + 本笔的推送 | 待批 | 快进推 `qa/seal-2026-09-28`;含 17MB 新增参照体积,须知情 | -| G | 移动档 +30/+21px 归因 | 待做 | 只读取证即可(对比 `1396666` 与 `a0328a6` 两树的 mobile 全页 shot),不需要写授权 | +| G | 移动档 +30/+21px 归因 | **已完成(本轮内,且推翻了自己的初判)** | 用 `row-diff.cjs` 定位发散行 y=7440 → `/products/erp` 的 `benefits` 段;根因是 `a366bd1` 的 Q-6 count-up 动画修复(旧参照冻结了动画中间帧)。取证法与教训见 9.4 | | — | AUTH-D2(重 seed)/ D4(写库 E2E 11 例)/ D9(Sentry 投递)/ D10(全量变异)/ D11(证据目录口径) | 状态不变 | 见 §2.3 | diff --git a/docs/lessons-learned.md b/docs/lessons-learned.md index 0f7988b..1fbc544 100644 --- a/docs/lessons-learned.md +++ b/docs/lessons-learned.md @@ -508,6 +508,21 @@ Object.defineProperty(window, 'requestAnimationFrame', { configurable: true, val **来源**:`src/proxy.ts:77-105`、`CLAUDE.md:108`、`docs/acceptance/qa-tracker.md` §2.2(DEC-N21b,2026-09-30 已就地更正)、§2.3(AUTH-D1/AUTH-D3 数字更正)、`docs/acceptance/2026-09-30-seal/final-verdict.md` §2.2。 +### 5.33 「本轮零源码改动」被误用成「参照与树同源」,于是把一次代码改进判成了运行期漂移 + +**事故(2026-10-08,同一轮内自查改判)**:写入视觉基线后要解释 chromium-mobile 两页全页只有 `+30 / +21px` 的高度变化。当时的推理是「本轮 `1396666` 相对封版点 `a0328a6` 零生产源码改动 ⇒ 位移不可能来自代码 ⇒ 只能来自运行期(CMS 数据行或日期派生内容)」,并把它写进了台账。**这个前提是错的**:旧参照的**采集树**是 `040951c`(2026-09-22 规范模式重生成),最后一次被改动是 `6bb7c55`(09-28 10:48),而当前树含 `a366bd1`(09-28 10:48:07,第五轮修复,224 文件)。也就是说参照比当前树**旧了一个修复轮次**,位移完全在代码侧。 + +实测归因链(全部只读):`sharp` 逐行比对定位首个发散行 y=7440(脚本 `docs/acceptance/2026-10-08-baselines/row-diff.cjs`),该处是 `/products/erp` 的 `benefits` 价值列表段;`git diff 040951c..1396666 -- src/components/detail/detail-product-value.tsx` 显示 Q-6 修复把指标 count-up 动画从 **render 体内**(每帧 `setState` 再 spawn 一条从 0 起的 rAF 链、从不取消)迁到 `useEffect` 并加取消 ⇒ **旧参照冻结的是动画中间帧**,新参照是稳定终态。同族证据:`prisma/seeds/products.ts` 在该窗口零改动,排除了「数据变了」这一支。 + +**规则**: + +1. **判红归因的参照系是「采集树 vs 当前树」**,不是「上一轮提交 vs 本轮提交」。采集树用 `git log -1 --format='%h %ci %s' -- <参照路径>` 现取,写在归因句子里;「本轮零源码改动」只支撑**门禁绿灯平移**(§8 封版不变式),**不支撑**「参照与当前树同源」。 +2. **基线数量必须标口径**:`--update-snapshots` 写的是**文件**,台账历轮记的是**用例**,一例可多 shot(`表单输入框` 2 张、`按钮组件` 3 张)⇒ 本轮 38 张文件 = 31 例。不标口径就会出现「20+11=31 却写了 38 张」这种看似失控的假象。 +3. **裸 `--update-snapshots` 的真实模式是 `changed` 而非 `all`**(`node_modules/playwright/lib/program.js:202` 的 `preset: "changed"`,缺省 `missing` 见 `common/index.js:584`)⇒ 它只写「缺失 / 不符」,**不会顺手重写通过的参照**。所以「覆盖了多少张」可以直接当作「判红多少张」,不必担心污染;反之想证明只读,须显式 `--update-snapshots=none` 并在复跑前后各取一次 `git status --porcelain <参照目录>`。 +4. **一次「未归因」的登记成本很低但收益很高**:本轮把 `+30px` 记成运行期漂移的代价,是一条会被下一轮引用的假事实;用一行脚本(逐行比对找发散 y)+ 一次 `git diff <采集树>..<当前树> -- <组件>` 即可证伪。**先花 5 分钟定位,再决定写「未归因」还是「归因为 X」**。 + +**来源**:`docs/acceptance/2026-10-08-baselines/attribution.md` §5、`docs/acceptance/qa-tracker.md` §9.4(含本条的作废声明与更正)、`src/components/detail/detail-product-value.tsx:70-100`、`node_modules/playwright/lib/program.js:202`。 + ## 6. 代码组织 ### 6.1 组件版本膨胀 @@ -561,3 +576,4 @@ Object.defineProperty(window, 'requestAnimationFrame', { configurable: true, val | 2026-09-23 | 增加 §5.29(视觉回归只读比对 21 例恒红的四类装配坑:① 宽松选择器 `input[type=text],input[type=email]` + `.first()` 命中按设计隐藏的**反垃圾蜜罐** ⇒ 期望隐藏字段可见,5/5 project 必失败且基线从未创建;② `[class*="card"]` 在 /products 零匹配,`element(s) not found` 被误读成 UI 回归;③ `VISUAL_TEST_PAGES` 列了 `/products/erp-upgrade`、`/about/brand` 但 5 个 project 全无 PNG ⇒ 只读判红、默认模式静默创建;④ 后台命令组 `{ cmd; echo X=$?; date; }` 的退出码取自 `date`,框架报 exit 0 而真实门禁 EXIT=1。管理归零:失败先按断言/参照/渲染三层分类,`0 例像素不符`即可否掉 UI 假设;不能复验的门禁脚本只记录精确修法不动手 | 2026-09-23 视觉回归只读比对(EXIT=1,21 failed / 104 passed)+ N-15 取证 | | 2026-09-23 | 增加 §5.30(覆盖率门禁 `collectCoverageFrom` 不含 `src/app/**` ⇒ route handler 全在棘轮外,专项审查找出 3 个 P1:`admin/stats` 只验会话即返回跨模型草稿标题、`checkUserPermission` 从不读 User 行使停用账号旧令牌 24h 内仍可用、B-6 的 `isInternalRedirect` 定义成私有函数致姊妹路由 `draft/disable` 开放重定向复活。管理归零:安全抽象必须可导入、修完要 grep 函数名看命中数是否等于应有数、每处修复做「临时移除 guard ⇒ 用例判红 ⇒ 恢复转绿」的 RED 实测、改共享鉴权函数打爆测试桩是信号不是障碍 | 2026-09-23 `src/app/**` 盲区专项审查(N-17..N-21)+ 三项修复与 RED 探针 | | 2026-09-30 | 增加 §5.32(「按文件名推断机制不存在」写出的假事实:DEC-N21b 记「无 middleware.ts ⇒ /admin 无服务端 gating」,实况是 Next 16 已改名 `src/proxy.ts` 且 `CLAUDE.md:108` 早已写明;同族第二例是「85 张基线未提交」而 `git ls-files` 实测 107 张全在库) | `src/proxy.ts:77-105`、`docs/acceptance/2026-09-30-seal/final-verdict.md` | +| 2026-10-08 | 增加 §5.33(把「本轮零源码改动」误用成「参照与树同源」⇒ 将 `+30px` 判成运行期漂移;实际旧参照采集树是 `040951c`(09-22),当前树含 `a366bd1`(09-28 第五轮),根因是 Q-6 count-up 动画从 render 体迁入 `useEffect`,旧参照冻结了中间帧。附三条口径:归因须对「采集树 vs 当前树」、基线数量须标「例/张」、裸 `--update-snapshots` 实为 `changed` 模式不重写通过项) | `docs/acceptance/2026-10-08-baselines/{attribution.md,row-diff.cjs}`、`docs/acceptance/qa-tracker.md` §9.4 |