release: reduce hydration 修复 + §16 排查记录 #48

Merged
zhangxiang merged 2 commits from dev into main 2026-10-20 08:03:29 +08:00
Owner

发布:reduce 偏好 hydration 修复(已上线并实测)

main 将包含 fix(motion) 与 §16 记录。合并不触发部署(Jenkins 无触发器,见 §15.1);
修复已于 2026-10-20 08:02 通过手动路径上线:线上 reduce 实测 hidden 14→3、0 hydration 错误、
/build 200。


PR:§14.2–§14.3 —— 把全量功能 E2E 从 36 红做到残差抖动,并修掉其中一条真 fail-open

承接 #33/#34/#35/#36/#37。本 PR 含两笔:1e80167b(产品与测试侧修复)、7d947fbc(键盘可达性测试的脆性修复 + §14.2/§14.3 台账)。

变更摘要

§14.1 的纯净对照把 36 条红分成"既有红"与"本批引入",本 PR 把后者逐条修掉:

侧 内容 证据
产品(真缺陷) detail-trust-section 渲染绕过门槛(算了 publishableCases 却仍 map caseStudies)⇒ 只要一条过闸,未授权/无 verified 的案例照样上线 变异验证:回退成 caseStudies.map ⇒ 2 条精确转红;恢复 ⇒ 35 例绿
产品(a11y) 4 个文字链接触摸目标 23px < WCAG 2.5.8 的 24px(走 min-h-6 间距刻度);能力面板 role="region" 缺可访问名(补 aria-label) 触摸目标两 spec × 4 project 复跑通过;探针证明加载期无双字标可见窗口
安全姿态(真因) 登录限流是进程内内存桶 10 次/15 分钟/IP,dev server 跨整轮存活 ⇒ @admin 旅程第 11 次登录起必得 429(即"单跑绿、全量红")。额度改为可按环境覆盖,默认仍 10,只在 e2e harness 抬到 500 route.test.ts 双向用例:未设⇒10;设 3⇒第 4 次判限流。9 例 EXIT=0
测试锚点 mobile.spec:45、website-acceptance:139 按真源 navigation.ts 重锚(一级只剩 行业/能力/洞察/关于我们;联系入口是 consult-button) website-acceptance × 4 project 连跑两次各 56 passed
引擎差异 p4 焦点管理:webkit/chromium-mobile 上 Tab 不落到链接(Safari 系需系统级设置)。我先前"窗口焦点"假设被自己的读数否掉,改为同契约按引擎取证,断言不减 webkit + chromium-mobile 2 passed
测试自身竞态 pollBoundingBox 先 poll 到非空再单独读一次,hydration 亚 60ms 重挂即误报"元素消失"⇒ 改在同一次读取里既判非空又取值 探针 probe-logo.mjs 实测;两 spec × 4 project 各 56 passed
键盘可达性 nav-keyboard:56 押死"连按 3 次 Tab"⇒ 冷启动/前序用例改变焦点起点就碎。改为有界键盘行走(≤8 次到不了即失败) 隔离 12 passed;合跑 68 passed;变异(上界改 1)⇒ 立刻判红

残差(不洗成通过):两次干净全量跑分别是 1067/1 与 1065/3,红项集合互不重合,全是 18–25s 超时类且隔离各自绿 ⇒ 定性为 --workers=4 下的并行墙钟抖动;CI 侧 retries=2 + workers=1 覆盖。本地要稳定复现绿用 --workers=1。PR-DESCRIPTION.md 里 npm run test 一项继续保持未勾选。

关联 Issue

N/A:本 PR 是 §14 待办的执行,来源是我自己的合并后补跑与纯净对照。

提交前检查

  • bash scripts/check-pr-checklist.sh 对本描述文件 EXIT=0(读数见「其他说明」)
  • N/A:本 PR 含产品修复(fail-open、触摸目标、region 命名、限流可覆盖)与测试侧修复,无 DB 迁移、无 seed 重跑(生产库未动)

全链路检查

  • npm run type-check EXIT=0(复算于本笔 HEAD)
  • npm run type-check:e2e EXIT=0 —— 它在本批内两次抓到真问题(我自己的重复键 env、以及 e2e 既有缺陷)
  • npm run lint:N/A 复跑于本笔 ⇒ 沿用 #33 的 0 error 读数;本批未新增 error 级问题(新代码只加 min-h-6/aria-label/测试文件)
  • 路由/链接真实:本批未新增路由;触摸目标修复只改 4 个已有 <a> 的最小高
  • 涉及 CMS 内容模型:N/A(本 PR 未改 schema;schema 契约在 #33 §12.12)
  • 涉及视觉/交互改动:已在新起服务上复核(触摸目标与 Logo 几何两 spec × 4 project;min-h-6 使首页相关区块增高 1px ⇒ 基线随之重采并只读复跑 125/125)
  • 暗黑模式:N/A(未引入颜色;aria-label 与 min-h-6 不涉及色值)
  • 动效合规:N/A(未改动效;check:motion 在 #33 已归零且判据按用途在消费点)
  • 品牌红触达与面积:N/A(未改样式语义,三闸读数未动)
  • 数字与宣称口径:本 PR 恰恰修了一条口径被绕过的缺陷(门槛算而不施)
  • 无遗留 console.log/TODO/.only():新增 console.error 只有门槛封条与 [revalidation-failed] 两类有意信号;check:dead EXIT=0

测试分层检查(L0–L3)

  • L0 单元:route.test.ts 新增限流双向用例;detail-trust-gate.test.tsx 3 例(含 fail-closed 与逐条隐藏)
  • L1 组件:jest detail-trust-gate + detail.test 35 例 EXIT=0;变异验证证明断言有牙
  • L2 E2E:test:e2e:fast 59 passed;website-acceptance × 4 project 两次各 56 passed;nav-keyboard 隔离 12 passed、合跑 68 passed
  • L3 视觉回归:min-h-6 增高后重采并只读复跑 125 passed / 0 failed(逐名清单机制同批上线)
  • 新守卫带正/负对照:限流用例双向前后;键盘"有界行走"变异(上界 1)立刻判红
  • 全量 test:functional:未 100% 通过(1065–1067 passed / 1~3 残差超时抖动,隔离各自绿)⇒ 已在 §14.3 与 #36 的未勾项上登记,不写成本 PR 已闭

质量门禁

  • npm run test:unit/test:coverage:1804 例 EXIT=0,All files 89.48/88.01/88.14/89.48 ≥ 阈值,阈值未下调
  • npm run test(全量 Playwright):N/A 于"本 PR 是否声明它通过"——本 PR 明确不声明,残差已登记(见上一节末项)
  • npm run check:a11y:EXIT=0(check:contrast/check:headings/check:brand-token);本 PR 的两处 a11y 修复让两条触摸目标 spec 由红转绿
  • npm run lighthouse:EXIT=0(#33 重建装配上取得;本 PR 未改渲染路径之外的样式,除 1px 增高)
  • npm run test:security:headers:EXIT=0;本 PR 未碰响应头/CSP,但动了限流默认值的读取方式(默认值不变,有单测钉)
  • 文档同步:qa-tracker.md §14.2/§14.3、lessons-learned.md(§5.44–§5.47 已在 #33/#36 落)
  • 提交信息符合 Conventional Commits,两笔各自可独立评审(产品+测试修复 / 键盘脆性+台账)
  • 破坏性/共享状态动作:无 seed 重跑、无生产库写入、无 force push、无部署;对照临时文件已清场

假绿灯纪律

  • 所有读数实际执行并留档(含被否证的假设:「窗口焦点」前置无效、「双字标可见」不存在)
  • 未以放宽断言/加 retry/删用例换绿:三处改的是取证方法(有界键盘行走、同一次读取取值、按引擎等价取证),断言强度逐条写明未降
  • 未把误报当问题修掉:残差抖动如实登记为"未 100% 通过",没有改成 test.skip 或提高 timeout 来掩盖
  • 结论以 origin/* 与实测为准:dev 与分支同 sha 已核
  • 未验证项显式列出(见「其他说明」),UI 改动经几何断言与基线复跑复核

其他说明

复算读数(本笔 HEAD 7d947fbc):tsc 0、type-check:e2e 0、check:package-keys 0、check:visual 0、check:dead 0、check:motion 0、jest 1804 例 0、test:e2e:fast 59 passed、website-acceptance ×4 56 passed ×2、nav-keyboard 12 passed(变异 1 例红)。

未验证/未通过项(不沉默)

  1. 全量 test:functional 在 --workers=4 下仍有 1~3 条超时类残差(跨轮集合不重合、隔离绿);CI 以 retries=2 + workers=1 覆盖,本地稳定复现请用 --workers=1。
  2. 生产侧 ContentModel.fields(DEC-N4 新字段声明)与 navigation 行的同形核对属部署期动作。
  3. dev→main 未做:Jenkinsfile 的部署阶段挂在 when { branch 'main' },合 main = 无人值守线上发布。
  4. 视觉基线逐张人工读图追认:本批仍只做了抽样(尺寸/像素分布 + 逐名清单已入库,供分批追认用)。
# 发布:reduce 偏好 hydration 修复(已上线并实测) main 将包含 `fix(motion)` 与 §16 记录。**合并不触发部署**(Jenkins 无触发器,见 §15.1); 修复已于 2026-10-20 08:02 通过手动路径上线:线上 reduce 实测 hidden 14→3、0 hydration 错误、 /build 200。 --- # PR:§14.2–§14.3 —— 把全量功能 E2E 从 36 红做到残差抖动,并修掉其中一条真 fail-open 承接 #33/#34/#35/#36/#37。本 PR 含两笔:`1e80167b`(产品与测试侧修复)、`7d947fbc`(键盘可达性测试的脆性修复 + §14.2/§14.3 台账)。 ## 变更摘要 §14.1 的纯净对照把 36 条红分成"既有红"与"本批引入",本 PR 把后者逐条修掉: | 侧 | 内容 | 证据 | |---|---|---| | 产品(真缺陷) | `detail-trust-section` 渲染绕过门槛(算了 `publishableCases` 却仍 `map caseStudies`)⇒ 只要一条过闸,未授权/无 verified 的案例照样上线 | 变异验证:回退成 caseStudies.map ⇒ 2 条精确转红;恢复 ⇒ 35 例绿 | | 产品(a11y) | 4 个文字链接触摸目标 23px < WCAG 2.5.8 的 24px(走 `min-h-6` 间距刻度);能力面板 `role="region"` 缺可访问名(补 `aria-label`) | 触摸目标两 spec × 4 project 复跑通过;探针证明加载期无双字标可见窗口 | | 安全姿态(真因) | 登录限流是**进程内内存桶** 10 次/15 分钟/IP,dev server 跨整轮存活 ⇒ `@admin` 旅程第 11 次登录起必得 429(即"单跑绿、全量红")。额度改为可按环境覆盖,**默认仍 10**,只在 e2e harness 抬到 500 | `route.test.ts` 双向用例:未设⇒10;设 3⇒第 4 次判限流。9 例 EXIT=0 | | 测试锚点 | `mobile.spec:45`、`website-acceptance:139` 按真源 `navigation.ts` 重锚(一级只剩 行业/能力/洞察/关于我们;联系入口是 `consult-button`) | website-acceptance × 4 project 连跑两次各 56 passed | | 引擎差异 | `p4 焦点管理`:webkit/chromium-mobile 上 Tab 不落到链接(Safari 系需系统级设置)。我先前"窗口焦点"假设**被自己的读数否掉**,改为同契约按引擎取证,断言不减 | webkit + chromium-mobile 2 passed | | 测试自身竞态 | `pollBoundingBox` 先 poll 到非空**再单独读一次**,hydration 亚 60ms 重挂即误报"元素消失"⇒ 改在同一次读取里既判非空又取值 | 探针 `probe-logo.mjs` 实测;两 spec × 4 project 各 56 passed | | 键盘可达性 | `nav-keyboard:56` 押死"连按 3 次 Tab"⇒ 冷启动/前序用例改变焦点起点就碎。改为**有界键盘行走**(≤8 次到不了即失败) | 隔离 12 passed;合跑 68 passed;变异(上界改 1)⇒ 立刻判红 | **残差(不洗成通过)**:两次干净全量跑分别是 1067/1 与 1065/3,红项集合互不重合,全是 18–25s 超时类且隔离各自绿 ⇒ 定性为 `--workers=4` 下的并行墙钟抖动;CI 侧 `retries=2 + workers=1` 覆盖。本地要稳定复现绿用 `--workers=1`。`PR-DESCRIPTION.md` 里 `npm run test` 一项**继续保持未勾选**。 ## 关联 Issue N/A:本 PR 是 §14 待办的执行,来源是我自己的合并后补跑与纯净对照。 ## 提交前检查 - [x] `bash scripts/check-pr-checklist.sh` 对本描述文件 EXIT=0(读数见「其他说明」) - [x] N/A:本 PR 含产品修复(fail-open、触摸目标、region 命名、限流可覆盖)与测试侧修复,无 DB 迁移、无 seed 重跑(生产库未动) ## 全链路检查 - [x] `npm run type-check` EXIT=0(复算于本笔 HEAD) - [x] `npm run type-check:e2e` EXIT=0 —— 它在本批内两次抓到真问题(我自己的重复键 env、以及 e2e 既有缺陷) - [x] `npm run lint`:N/A 复跑于本笔 ⇒ 沿用 #33 的 0 error 读数;本批未新增 error 级问题(新代码只加 `min-h-6`/`aria-label`/测试文件) - [x] 路由/链接真实:本批未新增路由;触摸目标修复只改 4 个已有 `<a>` 的最小高 - [x] 涉及 CMS 内容模型:N/A(本 PR 未改 schema;schema 契约在 #33 §12.12) - [x] 涉及视觉/交互改动:已在新起服务上复核(触摸目标与 Logo 几何两 spec × 4 project;`min-h-6` 使首页相关区块增高 1px ⇒ 基线随之重采并只读复跑 125/125) - [x] 暗黑模式:N/A(未引入颜色;`aria-label` 与 `min-h-6` 不涉及色值) - [x] 动效合规:N/A(未改动效;`check:motion` 在 #33 已归零且判据按用途在消费点) - [x] 品牌红触达与面积:N/A(未改样式语义,三闸读数未动) - [x] 数字与宣称口径:本 PR 恰恰修了一条**口径被绕过**的缺陷(门槛算而不施) - [x] 无遗留 `console.log`/`TODO`/`.only()`:新增 `console.error` 只有门槛封条与 `[revalidation-failed]` 两类有意信号;`check:dead` EXIT=0 ## 测试分层检查(L0–L3) - [x] L0 单元:`route.test.ts` 新增限流双向用例;`detail-trust-gate.test.tsx` 3 例(含 fail-closed 与逐条隐藏) - [x] L1 组件:`jest detail-trust-gate + detail.test` 35 例 EXIT=0;变异验证证明断言有牙 - [x] L2 E2E:`test:e2e:fast` 59 passed;`website-acceptance` × 4 project 两次各 56 passed;`nav-keyboard` 隔离 12 passed、合跑 68 passed - [x] L3 视觉回归:`min-h-6` 增高后重采并只读复跑 125 passed / 0 failed(逐名清单机制同批上线) - [x] 新守卫带正/负对照:限流用例双向前后;键盘"有界行走"变异(上界 1)立刻判红 - [x] 全量 `test:functional`:**未 100% 通过**(1065–1067 passed / 1~3 残差超时抖动,隔离各自绿)⇒ 已在 §14.3 与 #36 的未勾项上登记,不写成本 PR 已闭 ## 质量门禁 - [x] `npm run test:unit`/`test:coverage`:1804 例 EXIT=0,All files 89.48/88.01/88.14/89.48 ≥ 阈值,**阈值未下调** - [x] `npm run test`(全量 Playwright):N/A 于"本 PR 是否声明它通过"——本 PR 明确**不声明**,残差已登记(见上一节末项) - [x] `npm run check:a11y`:EXIT=0(`check:contrast`/`check:headings`/`check:brand-token`);本 PR 的两处 a11y 修复让两条触摸目标 spec 由红转绿 - [x] `npm run lighthouse`:EXIT=0(#33 重建装配上取得;本 PR 未改渲染路径之外的样式,除 1px 增高) - [x] `npm run test:security:headers`:EXIT=0;本 PR 未碰响应头/CSP,但**动了限流默认值的读取方式**(默认值不变,有单测钉) - [x] 文档同步:`qa-tracker.md` §14.2/§14.3、`lessons-learned.md`(§5.44–§5.47 已在 #33/#36 落) - [x] 提交信息符合 Conventional Commits,两笔各自可独立评审(产品+测试修复 / 键盘脆性+台账) - [x] 破坏性/共享状态动作:无 seed 重跑、无生产库写入、无 force push、无部署;对照临时文件已清场 ## 假绿灯纪律 - [x] 所有读数实际执行并留档(含被否证的假设:「窗口焦点」前置无效、「双字标可见」不存在) - [x] 未以放宽断言/加 retry/删用例换绿:三处改的是**取证方法**(有界键盘行走、同一次读取取值、按引擎等价取证),断言强度逐条写明未降 - [x] 未把误报当问题修掉:残差抖动如实登记为"未 100% 通过",没有改成 `test.skip` 或提高 timeout 来掩盖 - [x] 结论以 `origin/*` 与实测为准:dev 与分支同 sha 已核 - [x] 未验证项显式列出(见「其他说明」),UI 改动经几何断言与基线复跑复核 ## 其他说明 **复算读数(本笔 HEAD `7d947fbc`)**:`tsc` 0、`type-check:e2e` 0、`check:package-keys` 0、`check:visual` 0、`check:dead` 0、`check:motion` 0、`jest` 1804 例 0、`test:e2e:fast` 59 passed、`website-acceptance ×4` 56 passed ×2、`nav-keyboard` 12 passed(变异 1 例红)。 **未验证/未通过项(不沉默)** 1. 全量 `test:functional` 在 `--workers=4` 下仍有 1~3 条超时类残差(跨轮集合不重合、隔离绿);CI 以 `retries=2 + workers=1` 覆盖,本地稳定复现请用 `--workers=1`。 2. 生产侧 `ContentModel.fields`(DEC-N4 新字段声明)与 `navigation` 行的同形核对属部署期动作。 3. dev→main 未做:`Jenkinsfile` 的部署阶段挂在 `when { branch 'main' }`,合 main = 无人值守线上发布。 4. 视觉基线逐张人工读图追认:本批仍只做了抽样(尺寸/像素分布 + 逐名清单已入库,供分批追认用)。
zhangxiang added 2 commits 2026-10-20 08:03:24 +08:00
线上 /about 白屏排查(§16):30 条路由 + 6 种环境里唯一可复现的缺陷是
webkit/chromium + prefers-reduced-motion:reduce ⇒ pageerror #418,main 内 14 个元素
opacity 恒 0(正常环境只有 3 个首屏以下的滚动入场项)。

根因:useReducedMotion 用 window.matchMedia 作 useState 初值 ⇒ SSR false、客户端首帧 true;
scroll-reveal / template / page-transition 又用它决定 initial/variants/甚至早返回不同树结构,
与 SSR HTML 不一致;且 reduce 时 whileInView 被清空 ⇒ 元素停在 initial 的 opacity:0。

修法(结构恒定,减少动效改用「时长 0」表达):
- hook 首帧恒 false,挂载后 effect 同步真实偏好;
- ScrollReveal/StaggerReveal 的 initial/whileInView/variants 不再按 reduce 清空;
- template.tsx 与 StaggerChildren 去掉早返回裸结构,改空 variants。

回归守卫 e2e/reduced-motion-hydration.spec.ts(/about 与 /):断言 reduce 自证生效、
无 hydration 错误、h1 与末段标题 opacity=1。变异验证:hook 改回 matchMedia 初值 ⇒ 2 红,恢复 ⇒ 2 绿。

另:runbook 明确禁止对 dist/_next/static 用 --delete(回访者旧 HTML 会引用上一代 chunk);
本轮已从备份 --ignore-existing 合并回旧代 101 个文件。复算:tsc/type-check:e2e 0、
jest 35 套件 462 例 0、check:visual 0、check:motion 0、视觉 chromium-desktop 25/25。
同时登记本轮的编排事故:第一次重传用 set -- $pair 分词,zsh 不分词 ⇒ 5 条 rsync 全失败,
但未开 set -e 仍继续 docker build,等于用旧文件重建了一次镜像(无可见症状)。
已改为逐条判退出码重传并重建,用 BUILD_ID 与 reduce 实测确认线上确是新代码。
教训同 §5.44:命令都返回了 ≠ 命令都成功了。
zhangxiang added 1 commit 2026-10-20 08:03:24 +08:00
同时登记本轮的编排事故:第一次重传用 set -- $pair 分词,zsh 不分词 ⇒ 5 条 rsync 全失败,
但未开 set -e 仍继续 docker build,等于用旧文件重建了一次镜像(无可见症状)。
已改为逐条判退出码重传并重建,用 BUILD_ID 与 reduce 实测确认线上确是新代码。
教训同 §5.44:命令都返回了 ≠ 命令都成功了。
zhangxiang merged commit c394347dd0 into main 2026-10-20 08:03:29 +08:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: novalon/novalon-website#48