release: 视觉门禁状态判据 + CMS 退化可判(#58) #59

Merged
zhangxiang merged 4 commits from dev into main 2026-10-21 16:54:37 +08:00
Owner

发布:视觉门禁改为状态判据 + 首页 CMS 退化可判(#58 全量)

dev → main,四笔 81dc70b8 → 2c974d19。零视觉改动(首页只多一个 data-* 属性、字体只增授权文本);main 对齐 dev 的文档与测试装配,不需要重新部署。


变更摘要

把「视觉门禁会间歇变红」这件事从靠等改成靠判,并让首页的 CMS 退化从静默变成可判。

  1. feat(cms) 首页输出 data-cms-state:page.tsx 统计六路内容来源,全空判 empty
    (页面会整套落到常量版式,但照常 200);getHomePageCopy 原本 catch(() => null) 的静默
    吞掉改为带 tag 的 console.warn,行为不变、只是不再无声。
  2. test(visual) 截图前等显影落定:dwell 120ms→260ms 且每步排两帧;滚动结束后要求
    main 下 inline opacity:0 且仍有高度的元素归零,超时把前 5 个 offender 的标签写进错误;
    截图前断言 data-cms-state。顺带修掉 document.fonts?.ready 只取 promise 不 await 的老问题。
  3. docs(lessons) §5.51 收回一条未证实的机理:上一轮把首页那条红归因到 getHomePageCopy
    的 null 降级,但 hero 在代码里是无条件黑底(home-content-v16.tsx:101),null copy 产生不出
    浅色 hero ⇒ 解释被代码读回否掉。改为如实记录「机理未取证 + 环境侧偶发」。
  4. docs(brand) 字体授权与清单入库:OFL 要求随分发附带;43MB 字源继续留本地。

关联 Issue

N/A:来源是本轮视觉门禁取证(#32/#55/#56/#57 的后续),无协作平台 Issue。

提交前检查

  • bash scripts/check-pr-checklist.sh 对本描述文件 EXIT=0
  • N/A:本 PR 不重跑 seed、不写生产库(单测全 mock;视觉层只打本地 dev server)

全链路检查

  • npm run type-check — EXIT=0(0 error)
  • npm run type-check:e2e — EXIT=0(新增 helper 用的是 page.waitForFunction 的字符串表达式,类型层已通过)
  • npm run lint — 0 error / 84 warning,与改动前同数;新增的 console.warn 属允许方法(no-console 只放行 warn/error)
  • 路由/链接真实 — N/A:未新增 href;data-cms-state 不引入可点击元素
  • 涉及 CMS 内容模型 — N/A:只读判定,不改字段定义、不改 seed,无需 db:seed
  • 视觉/交互改动 — 页面外观零变化:cmsState 只写一个 data-* 属性,不改 class / 结构 / 文案。视觉回归读数见下
  • 暗黑模式 — N/A:未改颜色与主题 token
  • 动效合规 — 动效代码未改;只改测试侧的等待策略,且等待判据用 framer 的内联 opacity 状态,不新增动画
  • 品牌红触达 — N/A:无页面样式变更
  • 数字与宣称口径 — N/A:未改结果型数字;本描述里的读数均为本轮实测
  • 无遗留 console.log / TODO / .only() — 新增的是 console.warn(带 [home] tag),无 .only()

测试分层检查(L0–L3)

  • L0 单元 — 新增 3 例钉住 cmsState:全空 ⇒ empty;任一来源有内容 ⇒ ok;copy 抛错 ⇒ 页面不炸、状态仍 ok、且 console.warn 被调用(钉住「不静默」)。先写失败(3 failed)再实现(9/9 通过)
  • L1 组件 — home-content-v16.tsx 只多一个可选 prop 与根节点属性,默认 ok;既有组件用例不受影响(全量单测见下)
  • L2 E2E — npm run test:e2e:fast:59 passed / 25 skipped / EXIT=0(skip 含 dev 下按既有设计跳过的 16 例 GA4)
  • L3 视觉回归 — 见「实测读数」:默认并行(4 workers)下的红位页已复跑
  • 新增机械守卫带正控制 — 已实跑:把逐屏滚动临时改成只停首屏,waitForRevealsSettled 立即判红并列出 12 个 offender(见「实测读数」);assertCmsStateOk 的失败分支由单测构造的 empty 状态覆盖
  • 已运行相关测试并全绿,无 .only() / 跳过态残留

质量门禁

  • npm run test:unit — 见「实测读数」
  • npm run test:coverage — N/A:本 PR 未触碰阈值;覆盖率读数随全量单测同批产出,未下调任何门限
  • npm run test(Playwright E2E)— test:e2e:fast 59 passed / 25 skipped / EXIT=0;视觉层两次全量见下。未跑 test:e2e:prod(需要先 npm run build,且本 PR 不涉及生产响应头与 GA4)
  • npm run check:contrast / check:headings — N/A:无样式与标题结构变更
  • npm run lighthouse — N/A:无产物与资源变更(data-* 属性不影响 LCP/CLS)
  • npm run test:security:headers — N/A:未触及响应头、CSP 与部署配置
  • 文档已同步 — docs/lessons-learned.md §5.51(机理更正 + 修法落地)
  • 提交信息符合 Conventional Commits — 4 笔,按 docs(brand) / feat(cms) / test(visual) / docs(lessons) 切分
  • 破坏性/共享状态动作已单独授权 — 本 PR 无 DB 写入、无 seed、无部署;合并到 dev 与随之的 release 走既有授权

假绿灯纪律

  • 门禁命令实际执行过并粘贴真实输出 — 下面的表格是复算后的读数,不是「理论上应该没问题」
  • 未通过删测试、放宽断言、skip 用例或下调阈值让门禁变绿 — 相反:删掉的是「靠 dwell 赌」的隐性宽容,换来一条会报名字的状态判据
  • 未把误报当问题「修掉」— 上一轮把一段未取证的机理写进了 lessons,本 PR 主动收回并写明哪一步被证伪

实测读数

命令 结果
npm run type-check EXIT=0 / 0 error
npm run type-check:e2e EXIT=0
npm run lint 0 error / 84 warning(同改动前)
npm run test:unit 149 suites / 1818 tests 全通过,EXIT=0(较改动前 1815 多 3 例,即本 PR 新增)
视觉只读比对(默认 4 workers) 125 passed / 0 failed / EXIT=0,连跑两次(5.9m / 6.6m),两次都无参照被写;第一次跑时另一会话正在并发跑全量验收(额外 CPU 争用)
视觉守卫的正控制 临时把逐屏滚动改成只停首屏(真实条件:below-the-fold 的 whileInView 不触发)⇒ 用例按名字转红:12 个元素仍停在 inline opacity:0(whileInView 未提交):div.max-w-3xl.mb-16 , div.group.relative …。首位 offender 正是 /team「团队文化」那段的 ScrollReveal 容器(team-content-v3.tsx:299),与当初那条空白带同源。改回后转绿

注:本轮有另一个会话在并发跑全系统验收(docs/acceptance/qa-tracker.md §17 为它所写,未并入本 PR)。
视觉读数是在有额外 CPU 争用的条件下取的,这反而让「竞态是否已消除」的结论更有分量。

# 发布:视觉门禁改为状态判据 + 首页 CMS 退化可判(#58 全量) `dev` → `main`,四笔 `81dc70b8` → `2c974d19`。零视觉改动(首页只多一个 `data-*` 属性、字体只增授权文本);`main` 对齐 `dev` 的文档与测试装配,不需要重新部署。 --- ## 变更摘要 把「视觉门禁会间歇变红」这件事从**靠等**改成**靠判**,并让首页的 CMS 退化从静默变成可判。 1. **`feat(cms)` 首页输出 `data-cms-state`**:`page.tsx` 统计六路内容来源,全空判 `empty` (页面会整套落到常量版式,但照常 200);`getHomePageCopy` 原本 `catch(() => null)` 的静默 吞掉改为带 tag 的 `console.warn`,行为不变、只是不再无声。 2. **`test(visual)` 截图前等显影落定**:dwell 120ms→260ms 且每步排两帧;滚动结束后要求 `main` 下 inline `opacity:0` 且仍有高度的元素归零,超时把前 5 个 offender 的标签写进错误; 截图前断言 `data-cms-state`。顺带修掉 `document.fonts?.ready` 只取 promise 不 await 的老问题。 3. **`docs(lessons)` §5.51 收回一条未证实的机理**:上一轮把首页那条红归因到 `getHomePageCopy` 的 null 降级,但 hero 在代码里是无条件黑底(`home-content-v16.tsx:101`),null copy 产生不出 浅色 hero ⇒ 解释被代码读回否掉。改为如实记录「机理未取证 + 环境侧偶发」。 4. **`docs(brand)` 字体授权与清单入库**:OFL 要求随分发附带;43MB 字源继续留本地。 ## 关联 Issue N/A:来源是本轮视觉门禁取证(#32/#55/#56/#57 的后续),无协作平台 Issue。 ## 提交前检查 - [x] `bash scripts/check-pr-checklist.sh` 对本描述文件 EXIT=0 - [x] N/A:本 PR 不重跑 seed、不写生产库(单测全 mock;视觉层只打本地 dev server) ## 全链路检查 - [x] `npm run type-check` — EXIT=0(0 error) - [x] `npm run type-check:e2e` — EXIT=0(新增 helper 用的是 `page.waitForFunction` 的字符串表达式,类型层已通过) - [x] `npm run lint` — 0 error / 84 warning,与改动前同数;新增的 `console.warn` 属允许方法(`no-console` 只放行 warn/error) - [x] 路由/链接真实 — N/A:未新增 href;`data-cms-state` 不引入可点击元素 - [x] 涉及 CMS 内容模型 — N/A:只读判定,不改字段定义、不改 seed,无需 `db:seed` - [x] 视觉/交互改动 — 页面外观零变化:`cmsState` 只写一个 `data-*` 属性,不改 class / 结构 / 文案。视觉回归读数见下 - [x] 暗黑模式 — N/A:未改颜色与主题 token - [x] 动效合规 — 动效代码未改;只改测试侧的等待策略,且等待判据用 framer 的内联 opacity 状态,不新增动画 - [x] 品牌红触达 — N/A:无页面样式变更 - [x] 数字与宣称口径 — N/A:未改结果型数字;本描述里的读数均为本轮实测 - [x] 无遗留 `console.log` / `TODO` / `.only()` — 新增的是 `console.warn`(带 `[home]` tag),无 `.only()` ## 测试分层检查(L0–L3) - [x] **L0 单元** — 新增 3 例钉住 `cmsState`:全空 ⇒ `empty`;任一来源有内容 ⇒ `ok`;copy 抛错 ⇒ 页面不炸、状态仍 `ok`、且 `console.warn` 被调用(钉住「不静默」)。先写失败(3 failed)再实现(9/9 通过) - [x] **L1 组件** — `home-content-v16.tsx` 只多一个可选 prop 与根节点属性,默认 `ok`;既有组件用例不受影响(全量单测见下) - [x] **L2 E2E** — `npm run test:e2e:fast`:**59 passed / 25 skipped / EXIT=0**(skip 含 dev 下按既有设计跳过的 16 例 GA4) - [x] **L3 视觉回归** — 见「实测读数」:默认并行(4 workers)下的红位页已复跑 - [x] 新增机械守卫带**正控制** — 已实跑:把逐屏滚动临时改成只停首屏,`waitForRevealsSettled` 立即判红并列出 12 个 offender(见「实测读数」);`assertCmsStateOk` 的失败分支由单测构造的 `empty` 状态覆盖 - [x] 已运行相关测试并全绿,无 `.only()` / 跳过态残留 ## 质量门禁 - [x] `npm run test:unit` — 见「实测读数」 - [x] `npm run test:coverage` — N/A:本 PR 未触碰阈值;覆盖率读数随全量单测同批产出,未下调任何门限 - [x] `npm run test`(Playwright E2E)— `test:e2e:fast` 59 passed / 25 skipped / EXIT=0;视觉层两次全量见下。未跑 `test:e2e:prod`(需要先 `npm run build`,且本 PR 不涉及生产响应头与 GA4) - [x] `npm run check:contrast` / `check:headings` — N/A:无样式与标题结构变更 - [x] `npm run lighthouse` — N/A:无产物与资源变更(`data-*` 属性不影响 LCP/CLS) - [x] `npm run test:security:headers` — N/A:未触及响应头、CSP 与部署配置 - [x] 文档已同步 — `docs/lessons-learned.md` §5.51(机理更正 + 修法落地) - [x] 提交信息符合 Conventional Commits — 4 笔,按 `docs(brand)` / `feat(cms)` / `test(visual)` / `docs(lessons)` 切分 - [x] 破坏性/共享状态动作已单独授权 — 本 PR 无 DB 写入、无 seed、无部署;合并到 dev 与随之的 release 走既有授权 ## 假绿灯纪律 - [x] 门禁命令实际执行过并粘贴真实输出 — 下面的表格是复算后的读数,不是「理论上应该没问题」 - [x] 未通过删测试、放宽断言、skip 用例或下调阈值让门禁变绿 — 相反:删掉的是「靠 dwell 赌」的隐性宽容,换来一条会报名字的状态判据 - [x] 未把误报当问题「修掉」— 上一轮把一段**未取证**的机理写进了 lessons,本 PR 主动收回并写明哪一步被证伪 ## 实测读数 | 命令 | 结果 | |---|---| | `npm run type-check` | EXIT=0 / 0 error | | `npm run type-check:e2e` | EXIT=0 | | `npm run lint` | 0 error / 84 warning(同改动前) | | `npm run test:unit` | 149 suites / **1818 tests** 全通过,EXIT=0(较改动前 1815 多 3 例,即本 PR 新增) | | 视觉只读比对(默认 4 workers) | **125 passed / 0 failed / EXIT=0**,连跑两次(5.9m / 6.6m),两次都无参照被写;第一次跑时另一会话正在并发跑全量验收(额外 CPU 争用) | | 视觉守卫的**正控制** | 临时把逐屏滚动改成只停首屏(真实条件:below-the-fold 的 `whileInView` 不触发)⇒ 用例按名字转红:`12 个元素仍停在 inline opacity:0(whileInView 未提交):div.max-w-3xl.mb-16 , div.group.relative …`。首位 offender 正是 `/team`「团队文化」那段的 `ScrollReveal` 容器(`team-content-v3.tsx:299`),与当初那条空白带同源。改回后转绿 | > 注:本轮有另一个会话在并发跑全系统验收(`docs/acceptance/qa-tracker.md` §17 为它所写,未并入本 PR)。 > 视觉读数是在**有额外 CPU 争用**的条件下取的,这反而让「竞态是否已消除」的结论更有分量。
zhangxiang added 4 commits 2026-10-21 16:54:32 +08:00
OFL 要求分发时附带许可与版权声明;这两份文件也是「用了哪几套字、各自的子集口径」
的唯一记录。原先把整个 fonts/ 目录屏蔽,连它们一起挡在了仓库外。

.gitignore 由目录级 `fonts/` 改为 `fonts/*` + 三条反选:
FONT-MANIFEST.md / LICENSES.md / OFL-*.txt 入库,8 个 ttf/woff2 继续留本地
(站内实际引用的字体在 public/fonts,已入库)。
CMS 读数全空时首页会整套落到常量版式,页面照常 200,外观与「后台就是没内容」
不可区分。视觉基线对此只能给出一团无从归因的像素差——2026-10-20 那次间歇红
就是被这样当成了竞态。

- `page.tsx` 统计六路内容来源,全空判 `cmsState='empty'`,非空为 `ok`;
  同时把 `getHomePageCopy` 原本 `catch(() => null)` 的静默吞掉改成带 tag 的
  `console.warn`(行为不变,只是不再无声)。
- `home-content-v16.tsx` 在根节点渲染 `data-cms-state`;默认 `ok`,不影响其它调用方。
- 单测新增三例:全空 ⇒ empty;任一来源有内容 ⇒ ok;copy 抛错 ⇒ 页面不炸、
  状态仍 ok、且 warn 被调用(钉住「不静默」这条)。

视觉层据此在截图前断言该标记(下一笔)。
旧 helper 只靠固定 120ms 步长等 whileInView 提交,4 worker 抢 CPU 时中间某屏会被
IO 回调漏掉,截图留下一条 opacity:0 的空白带(lessons §5.51 签名 1)。这是装配竞态,
不该靠「多等一会儿」赌,也不该把整层钉成 --workers=1 用串行遮掉。

- 每步 dwell 提到 260ms 并排两帧(rAF×2)后再进下一屏。
- 滚动结束后等**状态**而不是时长:`main` 下 inline `opacity:0` 且仍有高度的元素必须
  归零;8s 超时则把前 5 个 offender 的标签写进错误,让红按名字出现。
  判据用 inline style 而非计算样式——framer 未开始时写 `opacity:0`、完成后写 `1`,
  两者只差这一笔;同时排除 display:none 与零高度节点,避免误判折叠菜单。
- 顺带修掉 `document.fonts?.ready` 只取 promise 不 await 的老问题(等于没等字体)。
- 截图前断言首页的 `data-cms-state`:CMS 退化按名字失败,不留给像素比对去猜。
上一版把首页那条间歇红(actual 矮 3114px、整段换成另一套版式)归因到
`getHomePageCopy().catch(() => null)`。读回代码就知道这条解释站不住:
hero 是无条件 `bg-[#0B0A08]`,copy 为 null 只影响文案,产生不出「浅色无图 hero」。

改成如实记录:机理未取证,已确证的只有「同树隔离 3/3 绿、基线与被测代码一致 ⇒
环境侧偶发」。同时把修法写成可验证的状态判据(已落地):dwell + 排帧、
显影落定等待、截图前断言 data-cms-state;并写明没有采用 --workers=1 的理由
(用串行掩盖竞态、把 5 分钟的层拖到 17 分钟)。
zhangxiang merged commit 2c974d1971 into main 2026-10-21 16:54:37 +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#59