diff --git a/docs/lessons-learned.md b/docs/lessons-learned.md index 4686c0d..8c28f1a 100644 --- a/docs/lessons-learned.md +++ b/docs/lessons-learned.md @@ -924,7 +924,7 @@ if [ "$A" -eq 0 ] && [ "$B" -eq 0 ]; then git add … && git commit … && git p ⇒ 通用判据:**跨路由的「等旧页退场再挂新页」不能依赖 framer 的 presence 状态机; 新页面挂载不得以旧页面的动画完成作为前置条件。** -### 5.51 视觉门禁的间歇红有两种签名:dwell 竞态与 CMS 取数退化,都不是像素回归(2026-10-20) +### 5.51 视觉门禁的间歇红有两种签名:装配竞态与整段换版式,都不是像素回归(2026-10-20) **现象**:在 `3fabb77c` 上只读比对 `visual-regression.spec.ts`(本批未碰 `/team`、`/about/brand` 任何文件)得 **121 passed / 4 failed / EXIT=1**;紧接着原样重跑同一批用例,失败集合换了一批 @@ -943,28 +943,30 @@ expected 是已显影正文 ⇒ 内容停在 `opacity:0` 初始态,而不是 目标),但 IO 回调与 framer 的 `whileInView` 提交都要排帧;4 worker 抢 CPU 时 dwell 不够, 中间某屏就被跳过。判别实验:同一批用例 `--workers=1` 重跑 **10 passed / 0 failed / EXIT=0**。 -**修法①**(只覆盖下面签名 1;独立动作,未随本批落地):dwell 提到 ≥250ms 且每步排空一帧 -(`requestAnimationFrame`);或给 `ScrollReveal` 加一个「已显影」可查询标记供用例等待—— -现在 `src/components/ui/scroll-reveal.tsx:80-96` 只透传 `className`,这条写不出来。 -门禁口径:视觉层默认执行方式钉成 `--workers=1`,否则 `test:all` 里这一层可红可绿。 +**修法(2026-10-20 已落地)**:`waitForPageStable` 的 dwell 120ms → 260ms 且每步排空 +两帧;滚动结束后**再等一次「显影落定」**——`main` 下 inline `opacity:0`(framer 未提交的 +初始态)且仍有高度的元素必须归零,超时直接把前 5 个 offender 的标签写进错误里,而不是 +留给像素比对去猜。这条把关的是**状态**,不是时长,所以对 CPU 争用不敏感。 -**补测(同日 22:20–22:35,同一棵树 `9ea8d5f4`)**:把整层改成 `--workers=1` 全量复跑, -得 **124 passed / 1 failed** —— 上面「串行即绿」的说法过强,必须更正。且那一条红 -(`L2 主题切换 › 浅色主题 - 首页视觉` @ `visual-chromium-tablet`)在同一棵树上 -`--repeat-each=3` 隔离复跑是 **3 passed**,在改动前的 `3fabb77c` 上单跑也是 passed。 -⇒ 它是**负载相关的间歇红**,不是 worker 数目的函数。 +**没有采用的方案**:把视觉层默认钉成 `--workers=1`。它能让读数稳定,但把 5 分钟的层拖到 +17 分钟,是用串行掩盖竞态;竞态本身有确定的状态判据,就该按状态等。 **两种签名必须分开归因**(都不是像素回归): 1. **同高、带内空白**(`/team`、`/about/brand`):页高与基线一致,差异只在一条带内, - 带内 actual 是 `opacity:0` 的空白 ⇒ `waitForPageStable` 的 120ms dwell 没把 - `whileInView` 提交完。 + 带内 actual 是 `opacity:0` 的空白 ⇒ 120ms dwell 没把 `whileInView` 提交完(上面的修法覆盖它)。 2. **不等高、整段换版式**(首页 `theme-light-main` @ tablet):actual 比基线**矮 3114px**, 且带内不是空白而是**另一套版式**(浅色无图 hero、`还没有可以公开的成果` 占位区)。 - 根因在 `src/app/(marketing)/page.tsx:60` 的 `await getHomePageCopy().catch(() => null)` - ——CMS 取数在负载下退化即静默回落成常量版式,页面照常 200、只是内容换了。 - 这一类**不能**用「加大 dwell」修,也不该由视觉基线去背。 + **机理未取证,不要照抄一个像样的解释**:当时的怀疑是 `src/app/(marketing)/page.tsx` 里 + `getHomePageCopy().catch(() => null)` 静默降级,但 hero 在代码里是**无条件黑底** + (`home-content-v16.tsx:101` 的 `bg-[#0B0A08]`),null copy 根本产生不出「浅色 hero」 + ⇒ 该解释被自己的代码读回否掉。已确证的只有:同树隔离复跑 3/3 绿、基线与被测代码一致 + ⇒ 环境侧偶发,不是提交引入。 + 收口方式因此改成**把状态显式化**而不是猜:首页现在输出 `data-cms-state`(`ok`/`empty`, + `page.tsx` 判定、`home-content-v16.tsx` 渲染),视觉层截图前先断言它——真退化会以 + 「CMS 数据退化:data-cms-state=empty」按名字失败。 ⇒ 通用判据:**「串行复跑变绿」不足以给并行红背书,先比对签名再归因。** -同高空白带 = 装配竞态;不等高且内容换了一套 = 数据侧退化。判据实验是 -「隔离复跑 N 次是否稳定 + actual/expected 的页高是否一致」,而不是「换一种并发就绿了」。 -动基线之前这两步都要跑完,否则会把竞态或退化固化成参照。 +同高空白带 = 装配竞态,用状态判据修;不等高且内容换了一套 = 先证伪自己的机理解释, +再决定是数据侧还是环境侧。判据实验是「隔离复跑 N 次是否稳定 + 页高是否一致 + +解释能否被代码读回」,而不是「换一种并发就绿了」。动基线之前这几步都要跑完, +否则会把竞态或一次偶发固化成参照。 \ No newline at end of file