# Lessons Learned(项目经验教训) > 记录跨任务、跨阶段的工程经验教训,避免重复踩坑。按类别组织,定期更新。 ## 目录 - [1. 技术选型与依赖](#1-技术选型与依赖) - [2. 构建与部署](#2-构建与部署) - [3. 样式与设计](#3-样式与设计) - [4. 性能优化](#4-性能优化) - [5. 测试](#5-测试) - [6. 代码组织](#6-代码组织) --- ## 1. 技术选型与依赖 ### 1.1 外部字体服务导致白屏 - **问题**:依赖 Google Fonts 等外部字体服务,网络加载失败时页面白屏。 - **根因**:字体加载阻塞首次渲染(FOUT/FOIT 未妥善处理)。 - **方案**:所有字体使用本地文件(`src/app/fonts/`),禁止外部字体 CDN。 - **来源**:`2026-03-04` 部署事故,`project_memory.md` Hard Constraints。 ### 1.2 React 19 + Next.js 16 HMR 兼容性 - **问题**:开发模式下 HMR 报错 `module factory is not available`,需要频繁清除缓存。 - **根因**:React 19 与 Next.js 16 的 HMR 模块缓存机制不兼容。 - **方案**:禁用 `optimizeCss` 实验性功能;若持续影响开发,改用生产模式(`npm run build && npm run start`)。 - **来源**:`docs/HMR-ERROR-SOLUTIONS.md`。 ### 1.3 webpackBuildWorker 导致静态资源 404 - **问题**:启用 `experimental.webpackBuildWorker: true` 后,客户端静态资源 404。 - **根因**:webpack 构建工作线程与 Next.js 静态导出不兼容。 - **方案**:强制禁用该功能,在 `next.config.ts` 中不启用或显式设为 `false`。 - **来源**:`project_memory.md` Hard Constraints。 --- ## 2. 构建与部署 ### 2.1 直接复制参考网站代码 - **问题**:从参考网站直接复制 HTML/CSS/JS 到项目中,导致样式冲突和技术债务。 - **根因**:参考网站的样式体系(Bootstrap/其他框架)与项目 Tailwind 体系冲突。 - **方案**:仅参考设计理念和布局,所有代码手动基于 Tailwind 实现。 - **来源**:`project_memory.md` Lessons Learned。 ### 2.2 静态导出限制 - **问题**:`output: 'export'` 模式下,`next/image` 需要 `unoptimized`,某些 API 路由不可用。 - **根因**:Next.js 静态导出对 Server Components 和 API Routes 的限制。 - **方案**:移除 `output: 'export'`,改用 `standalone` 或混合模式;图片使用 `unoptimized` 或 `` 标签。 - **来源**:`CLAUDE.md` Build Output 章节。 - **现状(2026-09-23 核对)**:方案已落地——`next.config.mjs:4` 为 `output: 'standalone'`,`/api/*` 与 `/admin/*` 由 Node 运行时承载(`nginx-static-production.conf:194-229`)。**但 `images.unoptimized: true` 的理由已换成新的一种**:产物经 Nginx 静态托管 + CDN 分发、无 Node 进程接管 `/_next/image`,改回 `false` 会让图片全量 404(`next.config.mjs:8-14` 已写明)。因此「unoptimized = 静态导出的限制」这句旧因果**不可再引用**,`CLAUDE.md` 与 `AGENTS.md` 的相应措辞已按此更正。 --- ## 3. 样式与设计 ### 3.1 光晕效果遮挡内容 - **问题**:Case Studies 区域卡片悬停光晕(halo effect)尺寸过大,遮挡文字。 - **根因**:光晕半径 256px + 不透明度 100%,超出卡片边界。 - **方案**:尺寸降至 192px,不透明度降至 0.08(降低 92%)。 - **来源**:`project_memory.md` Lessons Learned;后续推广为全局规则:所有光晕效果不透明度降低 30-50%。 ### 3.2 未使用的大文件残留 - **问题**:项目中残留 4.2MB 的 AoyagiReisho 书法字体文件,增加页面加载时间。 - **根因**:早期设计尝试引入书法字体,切换方案后未清理。 - **方案**:定期检查 `public/fonts/` 和 `src/app/fonts/` 中未使用的字体文件,及时删除。 - **来源**:`project_memory.md` Lessons Learned。 ### 3.3 品牌红使用过度 - **问题**:品牌红色(#C41E3A)在页面中占比超过 10%,视觉冲击过强。 - **根因**:缺乏品牌色使用规范约束。 - **方案**:制定品牌红贯穿规则——每页至少 3 处触达点,但面积 ≤ 10%;禁止作为段落文字色、大面积背景色。 - **来源**:`CONTEXT.md` 朱砂点睛章节。 ### 3.4 `aria-hidden` 不豁免 WCAG 1.4.3 对比度 - **问题**:装饰序号 / 客户名首字占位等纯装饰文字用 `text-text-muted/10`(≈10% alpha)淡化,axe-core 仍持续报 `color-contrast`,A-12 无法清零。 - **根因**:仓库长期误以为「`aria-hidden`(或 `role="none"`、CSS `opacity`)可让装饰文字豁免对比度」。实测 axe-core 4.11.4 的 `color-contrast` 规则只看 DOM 中可见文字的颜色,不看语义豁免;变体矩阵(aria-hidden / role=none / opacity:0.1 / SVG `` / `::before`)中只有后两种非文本编码能通过。 - **方案**:装饰文字改用项目唯一在册的大字档令牌 `text-text-hint`(#7C8CA5 / 深色 #94A3B8,对各级卡片底色 ≥3:1,满足 AA 大字标准),不再靠低 alpha 淡化;并在 `scripts/utils/check-color-contrast.ts` 的 REQUIRED_GROUPS 中加入「大号装饰文本 × 各级卡片底色」契约组,把该口径固化为门禁。 - **来源**:2026-09-21 验收 A-12 残留清零,变体探针脚本实测。 --- ## 4. 性能优化 ### 4.1 高并发下内存溢出 - **问题**:200 VUs 并发时服务崩溃,单实例无法处理高并发请求。 - **根因**:缺乏负载均衡、缓存策略和资源限制。 - **方案**:多实例部署(Docker Compose 3 实例)+ PM2 进程管理 + Nginx 负载均衡。 - **来源**:`docs/PERFORMANCE_OPTIMIZATION.md`。 --- ## 5. 测试 ### 5.1 测试框架冗余 - **问题**:项目存在三个独立的测试框架(e2e/, e2e-tests/, test-framework/),维护成本高。 - **根因**:早期多次试验不同测试方案,未及时清理废弃框架。 - **方案**:统一到 Playwright + Jest 体系,废弃 Python Playwright 和独立测试框架。 - **来源**:`docs/OPTIMIZATION_REPORT.md`。 ### 5.2 测试覆盖率门槛 - **问题**:早期测试覆盖率低(Lines 29%),无法有效保障质量。 - **根因**:缺乏测试文化,工具函数和 hooks 未覆盖。 - **方案**:设置覆盖率门槛(branches 35%, functions/lines/statements 45%),分阶段提升至 80%;后续通过 TDD 流程提升至 85%+。 - **来源**:`docs/test-coverage-improvement-plan.md`,`CLAUDE.md` 测试命令。 ### 5.3 E2E 断言文本必须与渲染文本保持一致 - **问题**:`e2e/nav-dropdown.spec.ts` 中 hover 测试失败,断言查找 `睿新ERP管理系统` 与 `行业方案`,但实际渲染为 `ERP 管理系统` 与 `行业解决方案`。 - **根因**:UI 文案迭代后,E2E 测试的文本断言未同步更新,导致测试假阴性(功能正常但测试报错)。 - **方案**: 1. 将 UI 文案断言改为稳定标识(如 `data-testid`、角色/aria 属性)或语义化选择器,减少对文案的强依赖。 2. 若必须使用文本,在修改文案时同步搜索并更新 `e2e/` 中的对应断言。 3. 建立「文案变更检查清单」,将 E2E 文本断言纳入审查范围。 - **来源**:2026-07-26 dogfood 后续验证,`e2e/nav-dropdown.spec.ts` 修复。 ### 5.4 视觉回归基线需在 UI 变更后主动更新 - **问题**:dogfood 修复后(列表卡片链接、案例筛选、联系表单反馈、新闻占位图等),视觉回归测试大面积失败。 - **根因**:上述修复属于有意的 UI/交互变更,导致已有快照与当前渲染不一致;若不更新基线,后续所有构建都会报告假阳性。 - **方案**: 1. 任何涉及视觉/布局的修复完成后,运行 `npx playwright test visual-regression.spec.ts --update-snapshots` 更新全项目视觉基线。 2. 更新前通过浏览器截图/人工复核确认差异符合预期,避免将未发现的回归写入基线。 3. 将快照变更作为独立提交或 PR 变更的一部分,方便评审时比对视觉差异。 - **来源**:2026-07-26 更新 105 张视觉回归快照。 ### 5.5 Playwright `storageState` 路径必须以配置文件为基准 - **问题**:全量 E2E 运行时 firefox/webkit 下所有测试瞬间失败,报错 `Error reading storage state from ./e2e/storageState.json: ENOENT`。 - **根因**:`e2e/playwright.config.ts` 中 `storageState` 被写成 `./e2e/storageState.json`,而 `npm run test` 实际在 `e2e/` 目录下执行(`cd e2e && npx playwright test`),导致 Playwright 去查找 `e2e/e2e/storageState.json`。 - **方案**: 1. 配置文件中的相对路径应基于配置文件自身目录,使用 `path.resolve(__dirname, 'storageState.json')`。 2. 修改 `storageState`、快照目录、报告目录等路径时,必须同时验证 `npm run test` 与从项目根目录直接运行 `npx playwright test --config=e2e/playwright.config.ts` 两种方式。 3. 将 `storageState.json` 纳入版本控制并作为 E2E 环境准备检查项。 - **来源**:2026-07-27 全量 E2E 回归失败排查,`e2e/playwright.config.ts` 修复。 ### 5.6 Firefox 中连续全页导航易触发 Playwright locator 超时 - **问题**:`e2e/p2-functional-e2e.spec.ts` 中「Footer 导航链接可点击」在 Firefox 中反复超时,报错 `waiting for "http://localhost:3000/" navigation to finish`,即使页面已渲染完成。 - **根因**:Playwright 的 locator API 会在页面存在未完成的导航时阻塞;Firefox 对 `window.location.href` 全页导航的处理比 Chromium 更慢,连续两次 `page.goto('/')` + 点击 StaticLink 触发全页导航后,locator 评估极易进入等待导航的竞态。 - **方案**: 1. 将涉及两次独立全页导航的测试拆分为两个独立 test case,减少单次测试内的导航次数。 2. 在 Firefox 等容易触发竞态的浏览器中,对必须触发的全页导航链接点击,改用 `page.evaluate(() => element.click())` 绕过 locator 的导航状态检查。 3. 优先使用 `data-testid` 或语义选择器定位,点击后通过 `page.waitForURL()` 显式等待目标 URL,而非依赖 locator 的隐式等待。 - **来源**:2026-07-27 `e2e/p2-functional-e2e.spec.ts` Footer 链接测试修复。 ### 5.7 封版阶段依赖升级需独立评估,避免 `--force` 一次性修复 - **问题**:`npm audit fix --force` 无差别升级依赖到最新版本,导致 `@lhci/cli` 被降级到使用 git+ssh 拉取 Lighthouse 的古老版本,且 `eslint-config-next@16` 与当前 `eslint@8` 不兼容。 - **根因**:`--force` 会执行 major version 升级,引入 breaking change 风险。 - **方案**: 1. 封版阶段不执行 `--force` 修复,仅执行向后兼容的 `npm audit fix`。 2. major version 升级应作为独立专项任务,在封版前或上线后安排。 3. 修复前备份 `package-lock.json`,并制定回退策略。 - **来源**:2026-08-12 封版验收阶段 1-B。 ### 5.8 性能测试脚本必须与 API 接口契约对齐 - **问题**:`stress-test.js` 向 `/api/contact` 发送 JSON body,但接口期望 `formData`,且 IP 限流每小时 5 次/IP,导致 66.7% 请求失败。 - **根因**:测试脚本编写时未审查 API 接口的具体实现(`request.formData()` 和 `isRateLimited`)。 - **方案**: 1. 新增/修改 API 后同步审查性能测试脚本,确保请求体格式、认证/限流机制与接口契约一致。 2. 将对依赖外部服务的接口(如 `formsubmit.co`)的压测排除在压力测试之外。 3. 重写后的脚本仅对本地静态页面进行 GET 压力测试,避免外部依赖干扰。 - **来源**:2026-08-12 封版验收阶段 5,stress-test.js 修复。 ### 5.9 测试摘要文件需在迭代中保护,避免被失败运行覆盖 - **问题**:k6 测试运行时预览服务器被停止,后续重新运行写入的摘要文件包含无效数据(0% 通过率),覆盖了之前成功的运行结果。 - **根因**:k6 的 `handleSummary` 输出路径与 `--summary-export` 路径不一致,且无版本保护机制。 - **方案**: 1. 使用 `--summary-export` 指定稳定路径(如 `tests/performance/`),与脚本内 `handleSummary` 路径统一。 2. 每次运行前备份前一次摘要文件。 3. 服务器重启后重新运行性能测试前,确认端口可用性。 - **来源**:2026-08-12 封版验收阶段 5,k6 摘要文件保护。 ### 5.10 触摸目标阈值不能把 AAA 当 AA 断言 - **问题**:`mobile-accessibility.spec.ts` / `mobile-performance.spec.ts` 以「WCAG 2.1 AA」为名断言所有交互元素 ≥44×44px,修复后仍有 30+ 个 24–43px 的元素无法通过,门禁长期红色。 - **根因**:44×44 是 SC **2.5.5 Target Size(AAA)**;AA 对应的是 WCAG 2.2 SC **2.5.8 Target Size(Minimum)= 24×24**,且带 Spacing / Equivalent / Inline / Essential 例外。测试把标准档位写错,导致断言比规范严两档。 - **方案**:抽出共享扫描 `e2e/touch-targets.ts`,输出两份清单——AA 2.5.8(<24px)作为**硬门禁**断言为 0,AAA 2.5.5(<44px)作为**建议清单**只打印不失败;并按 2.5.8 的 Inline 例外用 `closest('p,li,h1..h6') && display==='inline'` 排除正文内联链接。 - **来源**:2026-09-21 验收 A-12 触摸目标项,W3C Understanding SC 2.5.8 / 2.5.5 对照。 ### 5.11 `mobile-*` spec 会被桌面 project 复用,视口须在 spec 内钉住 - **问题**:`mobile-accessibility.spec.ts` / `mobile-performance.spec.ts` 带 `@mobile` 标签,但同时在 `chromium` / `firefox` / `webkit` 桌面 project 下执行——同一份断言在桌面 project 量到的是桌面布局(实测小目标 17 处 vs 移动 11 处,可聚焦元素 62 vs 11),两次结果互相矛盾却被当成「移动端口径」。 - **根因**:只有 `chromium-mobile` project 在 `playwright.config.ts` 里设了 `devices['iPhone 14']`;spec 文件名与注释声称移动端,却没有自己的视口约束,project 决定视口这一隐式约定在跨 project 复用时失效。 - **方案**:`mobile-*` spec 在文件内显式 `test.use({ ...devices['iPhone 14'] })`,让四个引擎量同一条移动布局;凡依赖视口的断言(断点类名、抽屉是否挂载、触摸目标尺寸)都必须在 spec 内声明视口,不依赖 project 隐式配置。 - **来源**:2026-09-21 验收 A-12 复跑,四个引擎测量结果对比。 ### 5.12 Next.js 的 `` 在路由 commit 之后 2–5 帧才落地 - **问题**:GA4 SPA pageview 用同步 `document.title` 上报,实测抓到空串或上一页标题,污染 GA4 报表的页面维度。 - **根因**:App Router 的 metadata 提交晚于路由 commit;生产实测 chromium-mobile 第 2 帧、桌面 chromium 第 3–5 帧才写入新标题。单帧 `requestAnimationFrame` 等待只是「碰巧在桌面通过」,移动端仍读到旧值。 - **方案**:`GoogleAnalytics.tsx` 改为带预算的帧循环(`MAX_TITLE_SETTLE_FRAMES = 10`):标题一旦变化立即发送,超过预算则兜底发送(绝不丢计数),新导航开始前先补发未送出的上一条 pageview。 - **来源**:2026-09-21 验收 A-17,`e2e/ga4-event-tracking.spec.ts` TC-GA4-004 实证 + `GoogleAnalytics.test.tsx` 竞态用例。 ### 5.13 品牌审计失败要先判定「测试过期」还是「真实泄漏」 - **问题**:`p1-brand-visual-audit.spec.ts` 断言首页不含 `novalon` / 竞品字样而失败,初判为「文案改版后的过期测试」。 - **根因**:并非过期——CMS page copy 缺字段时代码回落到 `FALLBACK_FOUNDER_QUOTE`,而回落常量里写着未品牌化的团队名,属于真实对外可见的品牌泄漏。同时 `prisma/seed.ts` 也存了同一条文案,数据库行可能仍保留旧值。 - **方案**:先 `curl` 已构建 HTML 确认字面来源(是渲染值还是回落值),再改常量与 seed;对「疑似过期」断言必须给出证据链(现网渲染结果 + 期望口径来源)后才允许改测试,并在提交信息里留痕。 - **来源**:2026-09-21 验收 P1 品牌视觉审计,`home-content-v15.tsx` / `prisma/seed.ts` 修复。 ### 5.14 视觉基线不能带上 `next dev` 的 devtools 指示器,且「装了守卫」必须被验证 - **问题**:83/115 视觉用例失败,且**页面高度完全不同的用例共享同一个差异簇** `{x:19-56, y:743-780}`(约 38px 圆盘)。 - **根因**:`next dev` 注入 `<nextjs-portal>`,其 shadow DOM 在视口左下角渲染 Next 徽标指示器;`next start` 没有它。更糟的是指示器的**形态随当次 dev 会话累积的告警数变化**——无告警时是 38px 圆盘,有告警时展开成红色 "Issues" 胶囊(本分支 dev 下 CSP 禁 `eval`,React 开发模式必然告警)。于是同一份代码在两次 dev 采集之间也会差一簇。因为该元素 `position: fixed`,全页截图按初始视口坐标落位,所以「不同高度页面出现同一坐标簇」成为它的判别特征。 - **踩过的坑**:第一版守卫把 `MutationObserver` 挂在 `document.documentElement` 上——init script 运行得比 `documentElement` 创建还早(Playwright 官方文档明确),`observe(null)` 直接抛 `TypeError`;这个报错只在 `pageerror` 里可见,测试本身照常「通过」,于是重跑 115 例全绿的基线里其实仍带着 "Issues" 胶囊。改成挂 `document` 后,用单页 `-actual.png` 左下角裁剪复核才确认剥离生效。 - **方案**:`page.addInitScript` 在页面脚本之前挂 `MutationObserver(document)` 移除 `nextjs-portal`,使快照与 `E2E_TARGET`、与 dev 会话告警数都无关;**新增守卫后必须用一张实际截图验证它生效**,不能只看「测试通过」。(该逻辑现已上移到 `e2e/fixtures.ts` 的 `context` 夹具,功能与视觉 project 共用,见 §5.16。) - **来源**:2026-09-21 验收视觉回归,`node_modules/next/dist/next-devtools/dev-overlay/components/devtools-indicator` + dev 页面 `document.querySelectorAll('*')` 探测到 `nextjs-portal`(0×0 host、带 shadowRoot)+ 新旧基线同坐标裁剪比对。 ### 5.15 `npm run test` 把视觉与写库用例并发跑,基线会被瞬时数据污染 - **问题**:`/news`、`/home` 快照在列表区多出一张「UJ-03 测试新闻 <时间戳>」卡片(日期即当天),而 SQLite 中查无此行;`curl` 却能在服务端 HTML 里读到它。 - **根因**:`test` 脚本单次调用同时跑功能 project 与视觉 project,`fullyParallel: true` 下 CMS 工作流用例「建条目 → `POST /api/cms/revalidate` → 删条目」与视觉截图并发。用例结束后数据行已清,但生产 server 的 ISR/预渲染缓存仍保留含测试条目的那一版页面(响应头 `x-nextjs-cache: HIT`),视觉用例随即截到它。 - **方案**:`npm run test` 拆为两阶段串行——`test:functional`(4 个功能 project)跑完再跑 `test:visual:all`(5 个视觉 project);`test:e2e` 指向功能阶段。CI 早已按 L4 功能 / L4.4 视觉分 stage,本地口径与之对齐。 - **来源**:2026-09-21 验收,`sqlite3 "file:prisma/dev.db?mode=ro"` 计数 38 行 / news 仅 2 条,与 `curl -sI localhost:3000/news` 响应头互证。 ### 5.16 dev 指示器的 shadow DOM 会被 Playwright 穿透,`locator('footer')` 因此解析到 2 个元素 - **问题**:功能 E2E 68 例失败里 56 例是同一条 `strict mode violation: locator('footer, [data-testid="footer"]') resolved to 2 elements`,第二个元素是 `<footer class="error-overlay-footer" data-nextjs-error-overlay-footer="true">`(文案 "Was this helpful?")。 - **根因**:Playwright 的 CSS 引擎默认穿透 open shadow root,`nextjs-portal` shadow DOM 里的那个 footer 因此进入 `locator('footer')` 的结果集。它是否出现取决于当次 dev 会话有没有累积到告警(本项目 dev 下 CSP 禁 `eval`,必然告警),所以同一断言在 chromium 桌面 project 通过、换个 project 就失败——与 §5.14 同源,只是症状从像素变成严格模式。 - **方案**:在测试侧剥离,且必须全局生效。`e2e/fixtures.ts` 扩展 `context` 夹具,用 `addInitScript` 注入「`MutationObserver` 观察 `document` + 立即清一次」的脚本移除所有 `nextjs-portal`;22 个 `e2e/*.spec.ts` 的 `import { test }` 全部从 `@playwright/test` 改为 `./fixtures`(`export * from '@playwright/test'` 保证 `expect` 等仍可用)。观察对象只能是 `document`——`document.documentElement` 在文档脚本开始前为 `null`。 - **反方案(已回滚)**:先试的是在源头关掉——`next.config.mjs` 按 `NEXT_DEV_INDICATORS=off` 设 `devIndicators: false`。局部 157 例转绿一度让它看起来成立,但探针实测**设置该环境变量后 `nextjs-portal` 数量仍是 1、`locator('footer')` 仍解析到 2 个**:官方文档里 `false` 只隐藏「指示器」本身,compile / runtime 报错仍会呈现,而本项目 dev 下 CSP 禁 `eval` 的 React-dev 报错恰好把 overlay 常驻挂住。局部跑绿是 `reuseExistingServer`(dev 目标下为 true)复用了不带该变量的旧 dev server 造成的假象。附带纠正一条写错的依据:Playwright 官方文档写明 init script 运行于 `document.documentElement` **创建之前**,所以观察器只能挂 `document`——挂在 `documentElement` 上会抛 `TypeError`,而不是「静默没装上」。 - **来源**:Playwright 官方文档「How it works › Shadow DOM」(CSS 选择器默认穿透 open shadow root)+ `node_modules/next/dist/docs/01-app/03-api-reference/05-config/01-next-config-js/devIndicators.md`(说明"只隐藏指示器")+ 本机两条实测:带 `NEXT_DEV_INDICATORS=off` 时 portals 仍为 1;改用 fixtures 后 p2/p3/website-acceptance/nav-dropdown 由 68 → 0 失败。 ### 5.17 first visible ≠ 可交互:hydration 前派发的指针事件被丢弃且不会重放 - **问题**:nav-dropdown(hover 展开)、website-acceptance(汉堡菜单、表单校验)在**空载单跑**下也确定性失败——动作调用成功、状态永不变,然后 `expect` 轮询到 15s timeout。 - **根因**:客户端组件的 `onClick` / `onMouseEnter` 要等 hydration 才挂上,而 SSR HTML 一进 DOM 元素就已 visible。这段窗口内派发的指针事件按普通事件丢弃,hydration 后不重放。 - **实测**:`/contact` 的 `[data-testid="submit-button"]` 在 first visible 后 **1735ms** 才出现 `__reactProps$` 键;早点击得到 0 条 `[data-testid="error-message"]`,hydration 后同一动作得到 5 条。主导航「产品」按钮 first visible 时同样未 hydration。 - **方案**:`e2e/hydrated.ts` 提供 `expectHydrated(locator)`(`expect.poll` + React DOM 的 `__reactProps$` 前缀探针),在 hover / click 之前调用。只给「必须有客户端反应」的用例加,纯 SSR 渲染断言不加,避免把等待成本摊到全站。 - **来源**:本机 CDP 探针实测(在 first visible 后轮询 `Object.keys(el).some(k => k.startsWith('__reactProps$'))`,测得 1735ms;修复前后同一动作 0 → 5 条错误)+ Playwright 官方文档 `expect.poll` / 自动等待机制说明。探针脚本为一次性工具,不入库;复现方式为在 `nav-dropdown` / `website-acceptance` 里去掉 `expectHydrated` 后观察 timeout 失败。 ### 5.18 StrictMode 双跑 + 「只跑一次」守卫,使 Cookie 同意条在 dev 目标下永不渲染——这才是 A-12 逃过全部门禁的原因 - **问题**:给 A-12 补 axe 对比度门禁时,新用例在 `expect(banner).toBeVisible()` 就失败。不是断言写错:dev 页面上同意条对首次访客也不出现(实测 4.5s 后 `[data-testid="cookie-consent-banner"]` 计数 0)。 - **根因**:`CookieConsent` 用 `consentCheckedRef` 保证 effect 只跑一次,而定时器分支返回 `() => clearTimeout(timer)`。React 18 StrictMode(`reactStrictMode: true`)在 dev 下按 effect → cleanup → effect 连跑:第一次的 cleanup 清掉了 2s 定时器,第二次被守卫拦下,于是**再没有人挂上定时器**。production 不双跑所以线上正常——dev 坏、prod 好,而 E2E 默认目标正是 dev。叠加 `storageState.json` 预置 `novalon-cookie-preferences`(连 prod 目标也 suppress 同意条),那条 3.31:1 同时穿过了 `check:contrast`、全站 axe 与 Lighthouse:A-11 说的「门禁双重失效」实际是三重的。 - **踩过的坑**:第一版用例用 `a[href="/privacy"]` + `.first()` 定位,命中的其实是 footer 里的同名链接,于是扫的是一个永远合规的对象;同意条需要专属 `data-testid="cookie-consent-banner"`,axe 用 `.include()` 限定作用域。 - **方案**:删除该 ref 守卫、让 effect 可重入(分支本身幂等:迁移过的第二次会走 `stored` 分支,只重复一次 `updateConsentDetailed`)。门禁改为:清 localStorage → 等条出现 → `AxeBuilder.include(banner).withRules(['color-contrast'])` → 按 **axe 节点数**归零,不再按 impact 过滤。 - **教训**:新增或加强门禁时必须同时验证它的**灵敏度**。把链接 class 临时改成 `text-text-hint`(#7C8CA5)再跑一次,确认它报 `实际 1` 并回滚——绿色在证明它能变红之前不算证据。 - **来源**:一次性 CDP 探针实测(修复前 `[data-testid="cookie-consent-banner"]` 计数 0 / 修复后 1,且 `/privacy` 链接 `CookieConsent.tsx:152` 位于条内)+ 上文变异复核。探针脚本为一次性工具、不入库;复现方式即 §「教训」所述:把条内链接 class 临时改成 `text-text-hint` 观察门禁报 `实际 1` 后回滚。 --- ### 5.19 修好「同意条永不渲染」之后,视觉基线才暴露出与引擎速度相关的截图竞态 - **问题**:§5.18 的 StrictMode 守卫移除后,`npm run test` 的视觉阶段 115 例里 34 例失败,且**全部落在 `visual-firefox-desktop` 与 `visual-webkit-desktop`**(各 17 例),chromium 桌面 / 平板 / 移动三端全绿。产品代码一行未改。 - **根因**:Cookie 同意条由挂载后 2s 定时器渲染。firefox / webkit 两个 project 使用 `storageState.firefox.json`(`5a4d310` 为消除 `newContext` 阶段浏览器兼容噪声而设的**空** state),拿不到预置偏好 ⇒ 定时器到点就把条画进首屏;chromium project 用 `storageState.json`(已预置 `novalon-cookie-preferences`)⇒ 条永不出现。慢引擎"来得及拍到"、快引擎"赶不上",于是同一份代码在不同 project 下截出不同的图——竞态来自夹具,不是产品。 - **定位方法**:先算差异簇的包围盒而不是猜。结果是整宽横带 `{x:37-1243, y:726-781}`(视口底边上方 19–74px),与 §5.14 的左下角 38px 圆盘完全不同;webkit 的包围盒恰好是 chromium 的 1.99 倍(`deviceScaleFactor`),据此排除"引擎渲染差异"。再裁剪 `*-actual.png` 该区域直接看到同意条文案。 - **方案**:`visual-regression.spec.ts` 用 `page.addInitScript` 预置偏好(时间戳取常量,避免随采集日漂移),把基线口径钉成「用户已表达 Cookie 偏好」。不重采任何基线、不依赖各 project 的 storageState 是否等价;修完 115 例全绿且未使用 `--update-snapshots`。 - **教训**:修复一个「组件在测试环境永不渲染」的缺陷,会让所有以「它不渲染」为隐含前提的门禁同时失去确定性;跨引擎 project 的夹具状态必须等价,否则基线测的是夹具差异。 ### 5.20 `-[var(--color-*)]/<alpha>` 是一个「静默不生成 CSS」的族,而「点亮死样式」属于设计决策而非机械替换 - **问题**:验收 R-3 顺带举了两个不生成 CSS 的写法(`hover:bg-[var(--color-brand)]/20`、`text-[var(--color-brand)]/30`)。实测它不是孤例,而是一个**族**:`src` 下 `<utility>-[var(--color-*)]/<alpha>` 共 **22 处 / 17 个唯一类**,编译产物里 **17/17 全部不存在**。 - **根因**:Tailwind v3 无法把 `/alpha` 修饰符套到纯 hex 的 CSS 变量上。`tailwind.config.js:12-15` 早已写明这一点,并因此把常用色改成 `rgb(var(--x-rgb) / <alpha-value>)`——但那次修复只覆盖 **theme 令牌**写法(`bg-brand/10` 可编译),**任意值**写法 `bg-[var(--color-brand)]/10` 不走 `<alpha-value>` 通道,依旧解析失败且不报错。 - **判定方法**:拿编译后的 CSS 做包含判定。dev 下全站共用一个 chunk,且 JIT 按**源文件扫描**决定是否产出(与组件是否被渲染无关),所以「源码里有这个类名、CSS 里没有对应规则」即为死样式。对照组证明检测器不误判:`.border-brand/30`、`.bg-[var(--color-brand)]`(无 alpha)、`.bg-accent-blue-soft` 都在,`bg-[var(--color-brand)]/40` 不在。 - **踩过的坑**:CSS 里 `:` 同样是转义字符(`.hover\:bg-...`)。第一次探测没把 `:` 放进转义集合,把**已经修好**的 `hover:bg-brand/20` 误报成「仍缺失」;补上 `:` 后确认 `.hover\:bg-brand\/20` 与 `.hover\:border-brand\/20` 均已产出。教训与 §5.14 同源:探针自身的缺陷会伪装成产品缺陷。**第二个坑更贵**:把死样式「点亮」等于凭空新增一条生效规则,必须重算配色——按评审建议换成 `hover:bg-brand/20` 后,半透明底与页面底色合成(`alpha*fg + (1-alpha)*pageBg`,注意是**替换**徽标自身底色而非叠加),浅色主题下 `text-brand-ink` 实测 **4.18:1 < AA 4.5:1**。而 `axe` 忽略 `:hover`、`check:contrast` 只断言声明的令牌配对,两道门禁都看不见这个回归,最终改用 12% 的 `bg-brand-soft`(浅色 4.80:1 / 深色 6.60:1;未 hover 的基线为 5.35 / 6.27)。 - **影响分级(按渲染证据,不按推测)**:抓 12 条路由的 HTML,17 个死类里只有 `via-[var(--color-brand)]/80`(`/privacy`、`/terms` 首屏渐变)真的出现在渲染结果中,其余都落在**没有任何路由渲染**的组件(仅被 barrel `index.ts` 再导出的死代码)。据此只修 2 处「活组件 + 仅 hover」:`NewsDetailClient.tsx:49` → `hover:bg-brand-soft`、`service-card.tsx:33` → `hover:border-brand/20` —— hover 态不进视觉基线,零基线冲击,且意图(悬停染红)无歧义。 - **未顺手修的原因**:把 `/privacy`、`/terms` 的 `via` 「修好」等于把 80% 半透明中点画进**已审批**的基线,在当前两停渐变中间挖出一道暗坑——这是设计意图问题,不是令牌化问题。另 3 处(`bg-[var(--color-bg-section)]/60`、`bg-[var(--color-brand-bg)]/50`、`hover:bg-[var(--color-brand-bg)]/30`)需要先在 `globals.css` + config 补 `--*-rgb` 通道才可能编译,属令牌系统扩展。 - **教训**:①「样式是否生效」的证据只能在**编译产物**里找,源码存在类名 ≠ 生效;②死样式的收口边界是设计意图与像素影响面——先量化「是否被路由渲染 / 是否仅 hover / 是否需要新增 rgb 通道」再决定点亮、删除还是留给人判断,不要为了令牌数好看而顺手改。 - **来源**:一次性 CSS 包含判定探针(编译 CSS + 12 条路由 HTML,含上述对照组;探针为一次性工具、不入库,复现方式是对照 `border-brand/30` 与 `bg-[var(--color-brand)]/40` 在 `/_next/static/chunks/src_app_*.css` 中的有无);`tailwind.config.js:12-15` 对本机理的既有记载;`ACCEPTANCE_REVIEW_2026-09-21` §R-3 原始举例。 --- ### 5.21 `try { expect(...) } catch { console.log(...) }` 会让门禁永久无法失败,而错误前提的断言第一版就是假绿 - **问题**:2026-09-22 最终树全量运行的日志里出现 `Error checking header svg: expect(received).toBeGreaterThan(expected) / Expected: > 0 / Received: 0`,但同一时刻该用例报 **✓ 通过**(`p1-brand-visual-audit.spec.ts:419` 「Logo SVG 文件不应包含 "NOVALON" 英文文本」)。也就是说:**门禁断言真的失败了,测试结果却是绿的**。 - **根因(两层,独立成立)**: 1. 该 spec 有 3 处把断言写在 `try` 里、`catch` 只 `console.log`(`:501`、`:549`、`:750`),断言失败被降级成日志;另有 `:507-518` 的兜底——「没找到任何 Logo 元素」时只要页面存在任意 `img`/`svg` 就通过。 2. 被吞掉的断言 `:476` `expect(svgTextContent.length).toBeGreaterThan(0)` **前提本身就是错的**:纯 `<path>` 图标 SVG 没有 `<text>` 节点,`textContent` 合法为空。于是「SVG 里有中文品牌名」这条检查在现行 Logo 形态下永远为假,只能靠 catch 跳过、再由 `img` 分支(`/logo.svg`)判定通过。 - **判定方法(低成本,可复用)**:把「`allure-results/*attachment.txt` 或 stdout 里出现 `Error checking`」与「同一 test 的最终状态」配对——**日志里有断言失败 + 测试为 ✓ ⇒ 假绿**。这比对断言代码本身快得多,且能覆盖「断言写在循环/选择器分支里、实际从未执行」的情况。 - **影响**:`p1-brand-visual-audit.spec.ts` 正是 §7-4「品牌文案 vs `FORBIDDEN_TEXT=/novalon/i`」裁定的执行门禁(CONTEXT.md:195 裁定改文案不改测试)。门禁本身可被 DOM 结构变化静默旁路,意味着该裁定的留痕只在那次运行里有效,**不构成持续守卫**。这与验收 A-11「断言通过而实际失败」同类,只是失效点从阈值搬到了 catch。 - **处理(2026-09-22 已闭合)**:先等权威产物落盘,避免把刚建立的「②E2E 归零」变回混合树,再改 spec。共 10 处:删掉错误前提的 `expect(svgTextContent.length).toBeGreaterThan(0)`,改为「Logo 图形资产内出现的 `<text>` 只能是已批准的拉丁字标 `NOVALON`」(依据:本文件 :173 对首页 Hero 英文品牌名的既予豁免 + 8d3bd72 `unify calligraphy logo` 刻意保留该节点);去掉 5 处吞断言的 `catch`(`:346/:501/:549/:587/:749`);5 处 `expect(true).toBeTruthy()` 换成真实断言或**诚实 skip**(桌面视口不渲染移动端按钮时 `test.skip`,而不是伪造通过);给三个「循环 + 候选选择器」型用例加**计数断言**(`hovered>0`、`withAlt>0`、`checked>0`),使「一次都没校验成」必然变红;截图用例改为断言 PNG 字节数并挂报告附件。`npx playwright test p1-brand-visual-audit.spec.ts` 在 chromium / chromium-mobile / firefox / webkit 四个 project 下 **124 passed**(`/tmp/brand-fix1.log`)——同一个数字,但这次背后是真的断言。 - **教训**:①`catch` 里只记日志的 `expect` 等价于**没有断言**——e2e 里若确需对多个候选选择器容错,应显式收集每轮失败并在末尾统一 `expect.fail`,让「一个都没校验成」必然变红;②写内容型断言前先在真实 DOM 上量一次前提(图标 SVG 常无文本节点),否则第一版就永久假绿;③「全量 0 failed」只是必要条件,不是门禁可信的充分条件——须同时扫过日志里的软失败文本,否则放行条件②会在一个无法失败的 spec 上被打勾。 - **来源**:`/tmp/e2e-final3.log`(`Running 1080 tests`,同 test 的 ✓ 行与 `Error checking header svg` 相邻);`e2e/allure-results/*-attachment.txt` 三处同名日志;`e2e/p1-brand-visual-audit.spec.ts:419/476/501/507-518/549/750`;`ACCEPTANCE_REVIEW_2026-09-21` §7-4 与 A-11;`CONTEXT.md:195` 的品牌文案裁定。 --- ### 5.22 验收口径必须是「可数的量」:10% 透明度水印数字被四道门禁同时漏过 - **问题**:放行条件⑤要求「A-12 关闭后两个引擎各复跑一次并留 axe **节点计数 = 0** 的证据」。按该口径重写扫描脚本(`docs/acceptance/2026-09-21-axe/axe-contrast-evidence.mjs`,现 `scripts/accessibility/axe-node-count.mjs`:sitemap 全站 29 URL × chromium/firefox × light/dark = 116 次页面扫描,内置反假绿熔断——读回 `data-theme` 与 `getComputedStyle(body).backgroundColor` 必须等于该主题令牌值,否则 `bgMismatch/themeMismatch` 直接判失败)后,首轮实测 **`passed=false`,4 个「引擎×主题」组合各 4 个 `color-contrast` serious 节点**,全部落在同一处:`/products/erp-upgrade` 的步骤大数字 `text-6xl font-bold text-brand-ink/10`(`erp-upgrade-content-v2.tsx:300`)。 - **根因(为什么四道门禁都看不见它)**:口径各异 ⇒ 没有任何一道覆盖「任意 alpha 组合 × 真实底色 × 节点计数」这条轴。 1. `check:contrast` 只断言 **REQUIRED_GROUPS 里声明的令牌配对**,`text-brand-ink/10` 不在册; 2. `check:headings` 与品牌审计 spec 只看文本内容,不看像素; 3. Lighthouse 的 URL 白名单只有 7 个入口页,`/products/erp-upgrade` **根本不在其中**(零覆盖); 4. `e2e/mobile-accessibility.spec.ts:67` 断言的是 critical/serious **规则条数** = 0,而规则数 ≠ 节点数(1 条规则命中 4 个节点仍记 1),且只跑一种主题、一台设备。 这与 §3.4 是**同一个契约的复发**:该处已记载「`aria-hidden` 不豁免对比度,axe 只看可见像素」,本例只是换了个页面、换了个令牌再次发生。 - **修复**:`text-brand-ink/10` → `text-brand-ink/80`,与站内同类元素的既有实现同档(`about-content-v4.tsx:172` 的步骤号正是 `text-brand-ink/80`)。修复后 dev 探针实测该页:`color-contrast` 违规节点 **0**、通过节点 118,计算色值 `rgba(196,30,58,.8)`(浅底 `rgb(255,255,255)`)/ `rgba(248,113,113,.8)`(深底 `rgb(10,14,20)`)。`aria-hidden="true"` 保留——它解决读屏冗余,与视觉对比度是两条正交契约。备选方案是 §3.4 的在册大字装饰令牌 `text-text-hint`(灰、≥3:1),但它会去掉该模块的品牌红触达,故未采用。 - **教训**:①验收口径要写成**可数的量**(节点数、URL 数、主题数),「规则命中数 = 0」「分数 ≥ 0.9」都是弱口径;②任何 `text-*/<alpha>` 都必须在真实底色上量一次合成值,令牌配对门禁天然看不见未登记的组合;③新增营销页必须同时进 Lighthouse URL 白名单与视觉回归路由表,否则它处于「有单测、无门禁」的盲区——`/products/erp-upgrade` 两处都不在(已列为待决项);④同一契约修复后要以**全站扫描**而不是局部复测来收尾,否则「A-12 已关闭」只是局部真。 - **来源**:`docs/lessons-learned.md` §3.4(同一契约的首次记录);`docs/acceptance/2026-09-21-axe/axe-evidence.json` 首轮 `summary.*.contrastNodes=4`;`config/test/lighthouserc.json:9-16` URL 列表;`scripts/utils/check-color-contrast.ts` REQUIRED_GROUPS 口径;`e2e/mobile-accessibility.spec.ts:67`;`e2e/visual-regression.spec.ts:26-39` 路由表。 --- ### 5.23 「没测所以为 0」与「进程没被收所以端口被占」:两类会把验收证据变成假绿的自伤缺陷 - **缺陷 A:证据脚本在零路由时仍打印 PASSED = true。** 为闭合 §5.22 的口径缺口(sitemap 只有 29 条,而 A-12 的口径是全站),我加了清单生成器 `docs/acceptance/2026-09-21-axe/crawl-sitemap.mjs`(现 `scripts/accessibility/crawl-routes.mjs`,2026-09-23 已连 `axe-contrast-evidence.mjs` 一起门禁化并接进 `Jenkinsfile`;预渲染产物 `.html` ∪ sitemap ∪ 站内链接 BFS = 36 条公开路由),但 `axe-contrast-evidence.mjs:13`(现 `scripts/accessibility/axe-node-count.mjs`)解析 `<loc>` 的正则**硬编码了生产域名** `https://www.novalon\.cn([^<]*)`,而我生成的 loc 是 `http://localhost:3100/...` ⇒ 一条都没匹配上 ⇒ `routeCount=0 / rows=[] / summary={}`,而 `passed` 是对 `summary` 里各项「= 0」的 `every` 判断,空对象上恒真 ⇒ 输出 **PASSED = true**,并且已经把上一份有效的 29 页证据覆盖掉(有效版本已在覆盖前另存为 `axe-evidence-sitemap29.json`)。 - **修复**:①解析改为 origin-agnostic(`new URL(loc).pathname`);②`urls.length === 0` 直接 `exit 2` 并打出「扫描等于没测」;③`passed` 增加覆盖前置 `rows.length === urls.length * 4`(页数 × 引擎 × 主题),使「计数为 0」只可能来自「真的测过且为 0」。 - **教训**:任何以「计数 = 0」为通过条件的门禁,都必须同时断言**分母**(跑了多少页 / 多少条路由 / 多少个用例)。这与 §5.21 的 `catch` 吞断言、§5.22 的规则数 ≠ 节点数是同一族:**空集合上的 `every` 永真**。自己新写的探针要先做正/负对照(本次负对照:喂 localhost 清单必须报错退出而不是报绿)。 - **缺陷 B:门禁脚本自起的服务器没被回收,毒化下一轮 E2E。** 验收报告 §9 已预警 `check-heading-hierarchy.ts` / `accessibility-test.js` 起 `npm run preview` 后留下 PPID=1 的 `next-server` 占 :3000 达 39 分钟。本轮第一方复现并付了代价:chain1 末尾(GA4 生产目标复跑 + 三项静态门禁复跑)在 :3000 留下一个 `next-server (v16.3.0)`,chain2 的完整 `npm run test` 因此经由 `reuseExistingServer: !CI` **静默复用了它**(`e2e/playwright.config.ts:134`),1080 例跑出 **53.6 分钟、805 passed / 263 failed**,其中失败主体是 **205 个 `page.goto` 超时**(不是断言失败);同一时刻隔离复跑那 2 例仍 4 passed。两小时后回看,这批数字与「产品有 263 例回归」毫无关系。 - **根因有两层**:`process.exit()` **不会执行 `finally`**,所以原来写在 `finally` 里的 `server.kill()` 在正常路径上根本不运行;即便运行,它杀的也只是 `npm` 包装进程,真正 LISTEN 的 `next-server` 孙进程被 init 收养。 - **修复**:两处 `spawn(..., shell: true)` 加 `detached: true` 使其成为进程组组长,收服改用 `process.kill(-pid, 'SIGTERM')`(杀整组),并把 `stopServer()` 显式提到两处 `process.exit()` 之前;`scripts/utils/check-heading-hierarchy.ts`、`scripts/accessibility-test.js` 同步。串行证据链另加**端口预检/后置检**(`PREFLIGHT_LISTENERS` / `POST_*_LISTENERS`),非 0 时该步产物不得引用。 - **教训(管理归零)**:`reuseExistingServer: true` + 任何会残留监听进程的步骤 = 后续证据失去「测的是当前代码」这一前提。共享机器上跑证据链,**每一步前后都要打印端口占用数**;跑完整套件前若 :3000 非空闲,必须先确认那个服务是不是自己刚起的、构建是否比当前树更新。 - **来源**:`docs/acceptance/2026-09-21-axe/axe-evidence-sitemap29.json`(有效的 29 页版)与被覆盖后 `routeCount=0` 的产物对比;`/tmp/e2e-final6.log`(53.6m / 805 / 263 / 205×`page.goto` 超时);`/tmp/e2e-isolate-rerun.log`(4 passed);`lsof -iTCP:3000` 实测 pid 61088 `next-server (v16.3.0)`;`e2e/playwright.config.ts:130-134`;验收报告 §9「门禁脚本的进程回收缺陷」。 --- ### 5.24 「清单只取 sitemap」让边界页长期无人测量;扩目录当场挖出 404 水印与缺失的兜底页 **背景**:放行条件⑤ 要求「全站对比度关闭后,两个引擎各复跑一次并留 axe 节点计数 = 0」。前几轮的路由清单直接取自 `/sitemap.xml`(29 条),而 `src/app/sitemap.ts` 只列**希望被收录**的页面 —— 404、错误兜底、被注释掉的 `/cases` 天然不在其中。§5.22 已经证明过一次「新页没进清单 ⇒ 门禁测不到」,这次把清单来源补成 **sitemap ∪ 预渲染产物 ∪ 站内链接 BFS**(`docs/acceptance/2026-09-21-axe/crawl-sitemap.mjs`,现 `scripts/accessibility/crawl-routes.mjs`),得到 35 条可达路由。 **扩目录后第一次扫描就不再是 0**(chain3,`axe-evidence.json` `routeCount=35 / rows=140 / passed=false`): | 路由 | 双引擎 × 双主题 | 报错 | 根因 | |---|---|---|---| | `/_not-found` | 4/4 各 1 节点 | `color-contrast`(h1) | `src/app/not-found-content.tsx:14` 的「404」用 `text-brand-ink` + **`opacity-20`**,有效 alpha 只有 20%,任何配色都过不了 AA。与 §5.22 的 `/products/erp-upgrade` 水印数字同族,只是那次用 `-[var(--color-brand-ink)]/10`(Tailwind 根本不产出 CSS,反而"躲过"了 axe),这次用 `opacity-*` 是真渲染了 | | `/_global-error` | 4/4 各 1 节点 | `html-has-lang`;深色下 `bgMatchesToken=false` | 项目**没有** `src/app/global-error.tsx`,根布局抛错时 Next.js 用内置文档壳顶替 root layout:`<html id="__next_error__">` 无 `lang`,且本站主题走 `html[data-theme='dark']` 属性(`globals.css:396` 明确说明不是 `.dark` class),内置壳读不到 ⇒ 深色落到浏览器默认画布 `rgb(10,10,10)`。官方文档 `error.md` 同样写明「global-error 与内置 500 页自带文档、不含全局样式,OS 主题开关要在自己的组件里做」 | **修复**:404 标题改 `text-brand-ink/80`(沿用 §5.22 先例:120px 属大号文本,AA 需 3:1,/80 在浅色 `#FFFFFF` 与深色翻转通道 `#F87171` 下均达标且能编译);新增 `src/app/global-error.tsx` 自带 `<html lang="zh-CN">` + `<title>`(错误边界是 Client Component,不能用 `metadata` 导出)+ 与 `globals.css` 同值的 OS 主题内联样式(CSP `style-src 'unsafe-inline'` 允许)。注意本版本 Next 的 props 是 **`retry`**(`node_modules/next/dist/docs/.../error.md` 的示例即 `retry: () => void`),不是旧文档里的 `reset` —— 写之前必须读随包文档,否则又是一个"按训练记忆编造 API"。补 3 例单测断言 `lang`、`retry` 接线、digest 展示。 **同轮还归零了三例「隔离必过、满负载必挂」的 E2E**(chain3:`1048 passed / 4 failed`,端口预检为 0,所以不是 §5.14/§5.23 那类孤儿服务复用;单跑 33 例全过): 1. `p4-performance-a11y.spec.ts:41` 把 `await page.waitForTimeout(1500)` 写在计时区间**内** ⇒ 5000ms 预算实际只剩 3500ms 给导航,dev 服务首次访问要现场编译,必然破线(实测 /about 6069ms)。修复:`startTime` 前加一次 `waitUntil: 'commit'` 预热、把 settle 等待移到计时之外。修后同一断言下首页 **107ms**、关于 232ms。 2. `p3-compatibility.spec.ts:114` 先 `isVisible()` 再 `boundingBox()` 是**两次独立解析**,节点被替换时第二次返回 null。修复:`expect.poll(() => boundingBox()).not.toBeNull({timeout: 10000})`。 3. `uj-11-home-conversion.spec.ts:172`(firefox)`scrollIntoViewIfNeeded` 撞 `Element is not attached to the DOM`;`p2-functional-e2e.spec.ts:253` 点页头 mega dropdown 里的 `/services/*` 链接,高负载上下拉在 click 前收起、点击落到底下的 `/services` 触发器。修复:滚动前先 `expect(...).toBeVisible({timeout:15000})`;正文链接改为限定 `main a[href*="/services/"]` + `waitForURL`,并打印分母(`main 区 /services/* 链接数=`)以免"没找到所以绿灯"。 **教训(口径)**: - **门禁覆盖 = 清单来源**。`sitemap.xml` 是"给搜索引擎看的",不是"给用户可达的"。要证明「全站节点计数 = 0」,清单必须至少并上预渲染产物(`dist/standalone/dist/server/app/**/*.html`)与站内链接 BFS,否则 404 / 错误页 / 孤儿页永远在测量之外。 - **`opacity-*` 与 `text-*/<alpha>` 是两条不同的暗化通道**,前者一定会渲染(因此一定会被 axe 看见),后者在 Tailwind v3 + 纯 hex 变量下可能静默不产出。审计水印类文本时两条都要查,只看类名里的 `/NN` 会漏。 - **负载竞态不要用 `retries` 掩盖**:这三例的共性是把"等稳定"写成固定 `waitForTimeout`,而把"读一次"写成裸 API 调用。改成显式的 auto-retry 断言 + 预热,既保留断言强度又消除抖动;顺带让性能断言终于测的是页面加载而不是编译器。 - **修完一批还会冒出下一批,直到触到产品根因**。chain4 修掉那三例后(隔离复跑同样全过),同一轮又出现三例新失败:移动端 LCP 2736ms(同一个"编译计入计时"成因的第四个实例)、`website-acceptance.spec.ts:121` 与 `mobile.spec.ts:101` 找不到 `[data-testid="mobile-navigation"]`。后者不是竞态而是**真产品缺陷**:`header.tsx:184` 的 `onClick={() => setIsOpen(!isOpen)}` 读的是渲染闭包里的 `isOpen`,与抽屉 `AnimatePresence` 的退出动画(0.2s + 0.25s)叠加时,高负载下连点会算成"没变化"⇒ 用户按汉堡按钮打不开抽屉。改成函数式 `setIsOpen((prev) => !prev)` 后 chain6 功能 1052 / 0 failed、视觉 115 / 0 failed。教训:**两个 spec 在同一控件上失败**是"共同上游缺陷"的强信号,不要各自加等待哄过去;仓里另两处同型 `set(!x)`(`admin/login/page.tsx:80`、`admin/notifications/page.tsx:167`)不在失败链路上,按范围裁定另计。 - **扩目录的第二类噪声:框架内置文档会被当成"本站页面"扫进来**。`_global-error.html` 是 Next 为根错误路径预渲染的**内置 500 文档**(实测 `<html id="__next_error__">`,无 `lang`、零应用标记,深色下 `pageBg=rgb(10,10,10)` 即浏览器默认画布),而本站的 `src/app/global-error.tsx` 编译产物在 `dist/.../chunks/ssr/src_app_global-error_tsx_*.js`(文案可 grep 到),二者不是一回事。按名字硬编码排除就是"为了让计数归零而缩清单",所以按**内容**判定:`/<html[^>]*id="__next_error__"/` 命中才跳过,并打印 `skippedInternalDocs=<n>`;框架一旦把本站组件预渲染到该路径,条件不再命中、路由自动回到清单。对照 `/_not-found`:它的 HTML 里就是本站的 `text-brand-ink` h1,属本站资产,改 `/80` 后 `contrastNodes` 由 1 → 0(chain4 实测)——"同前缀不等于同类"。 **来源**:`docs/acceptance/2026-09-21-axe/axe-evidence.json`(`routeCount=35`、`passed=false`、8 条 bad rows)、`/tmp/e2e-final7.log`(chain3 4 failed 与逐页 load time)、`/tmp/repro-4.log`(隔离复跑 33 例全过)、`node_modules/next/dist/docs/01-app/03-api-reference/03-file-conventions/error.md`、`src/app/globals.css:396-421`。 ### 5.25 门禁里「恒不成立的断言」比没有断言更危险:3 条 Lighthouse 死审计 + 一次 2 秒 type-check 的自证 **背景**:chain6 的 `npm run lighthouse` 以 `EXIT=0` 通过,但同一份日志每轮都稳定打印 21 条 `"…" is not a known audit. expected: >=1 found: 0`。因为是 `warn` 级,它永不判红,于是「4 类目 + 5 项 CWV + 57 项 a11y 断言全过」这句结论里混进了 3 项**从来没测过任何东西**的条目。 **取证(两个独立信源,缺一不可)**: | 信源 | 做法 | 结果 | |---|---|---| | 运行时报告 | 把 chain6 全部 21 份 `*.report.json` 的 `audits` 键取并集(175 个 id),再拿 `lighthouserc.json` 里 62 个非 `categories:` 断言键去比对 | 只有 `autocomplete-valid` / `presentation-role-conflict` / `svg-img-alt` 三条不在并集里;同批的 `color-contrast`、`heading-order`、`target-size`、`aria-conditional-attr`、`skip-link` 全在 ⇒ 不是"页面恰好没问题",是审计项不存在 | | 审计注册表 | `@lhci/cli@0.15.1` 实际用的是它自带的 `lighthouse@12.6.1`(**不是**顶层 `lighthouse@13.4.1`,这层版本裂差就是本地包搜不到该审计的原因),其 `core/audits/accessibility/` 共 64 个审计文件 | 三者均无对应文件 | **为什么不能"删掉了事"**:用与 ⑤ 门禁同款的 `runOnly: {type:'tag', values:['wcag2a','wcag2aa','wcag21a','wcag21aa']}` 做正/负对照(`docs/acceptance/2026-09-21-axe/probe-axe-rule-coverage.mjs`,每条规则各造一个必然违规的最小节点):`autocomplete-valid`、`svg-img-alt` 在 axe 通道里确会被执行并抓到违规(各 1 node)⇒ 覆盖并未丢失;但 `presentation-role-conflict` 属 `best-practice` tag,**当前 axe 门禁的 tag 集合根本不跑它** ⇒ 删掉死断言就等于悄悄拆掉一道门。处理:`lighthouserc.json` 删 3 条 + `axe-contrast-evidence.mjs` 增加规则级 `runOnly: {type:'rules', values:EXTRA_RULES}` 第二次运行,并按页断言 `extraRulesChecked === 3`(`extraRulePagesUnderCovered` 计数)+ 节点数 0 —— 覆盖从"看起来有"变成"确实有且可数"。**2026-09-23 门禁化补充**:脚本已平移为 `scripts/accessibility/axe-node-count.mjs`(清单生成器为 `scripts/accessibility/crawl-routes.mjs`)并接进 `Jenkinsfile`,判定从「打印 PASSED」改为退出码;规则级通道另加一份写死的三条下限清单 `CANONICAL_EXTRA_RULES` 与绝对分母 `Σ = 路由 × 4 组合 × 3 规则`——只从运行列表里删规则会当场判红,不再靠"运行列表本身就是断言对象"这种自我豁免。 **同轮的另一次自证**:chain6 `EXIT_TYPECHECK=0` 只花 2 秒,对一个 200+ 文件的 Next 项目不合理。先怀疑空跑,再用正/负对照定性:临时放一个 `const probe: number = "not a number"` ⇒ `tsc` 报 `error TS2322`(冷缓存 11.1s),删除后 2.9s 干净;`tsconfig.compilerOptions.incremental=true` 命中 `.tsbuildinfo` 才是快的原因 ⇒ 门禁有效,结论保留。**"很快"和"很慢"都只是怀疑的起点,不是结论;能造一个必然失败的正对照,就不要靠推断给门禁背书。** **顺带纠一个数**:`AGENTS.md` §5 记的「lint 实测 105 条 warning」已过期,chain4/chain6 均为 **106**(56 `no-console`/25 `no-explicit-any`/12 `react-hooks/set-state-in-effect`/10 `no-img-element`/其余 3 条零散,含 1 条 `Unused eslint-disable directive` 死抑制),已按实测改文并注明日期。文档里的数字一旦不再被复算,就会从"证据"退化成"传说"。 **来源**:`lighthouse-reports/*.report.json`(`lighthouseVersion 12.6.1`)、`node_modules/@lhci/cli/node_modules/lighthouse/core/audits/accessibility/`、`docs/acceptance/2026-09-21-gates/lighthouse.txt`(chain4+chain6 合计 42 条 warning)、`docs/acceptance/2026-09-21-axe/probe-axe-rule-coverage.mjs`、`/tmp/lint-final4.log` 与 `/tmp/lint-final6.log`。 ### 5.26 文档会写出不存在的机制:本轮四处「读起来很像真的」的假事实 **背景**:2026-09-23 做文档—代码一致性回扫(本轮只改文档,不改代码),逐条 grep 取证后发现四类同族缺陷。它们的共同点是**句式完整、带文件名和行号,但指向的东西不存在或早已换掉**——比空洞的文档更危险,因为它会被当成依据。 | 文档断言 | 实测 | 定性 | |---|---|---| | `docs/testing.md`:Playwright `webServer.env` 注入 `NEXT_DEV_INDICATORS=off`,`next.config.mjs` 据此设 `devIndicators:false` | 两个字符串在 `next.config.mjs` 与 `e2e/playwright.config.ts` 中**都不存在**(后者 `webServer.env` 只有 `CMS_REVALIDATE_SECRET`);真实现是 `e2e/fixtures.ts` 移除 `<nextjs-portal>`。`NEXT_DEV_INDICATORS` 唯一出现处是 lessons-learned §5.16 的**反方案历史记录** | 把"当年试过的反方案"抄成了"现行机制" | | `CLAUDE.md`:`npm run preview` = "Serve dist/ on port 3000 (**npx serve**)" | `package.json` 里 `preview` 与 `start` 同为 `next start -p 3000`;`serve` 不在依赖里 | export 时代的描述残留到 standalone 时代 | | `AGENTS.md` §8 / `CLAUDE.md` Build Output:「静态导出为主」「images unoptimized = 静态导出限制」 | `next.config.mjs:4` 为 `output: 'standalone'`;unoptimized 的真实理由写在同文件 `:8-14` 的注释里(Nginx+CDN 直服,无 Node 接管 `/_next/image`) | 约束的**结论**仍对,**因果**已换 | | `package.json`:`check:axe` / `check:axe:routes` → `scripts/accessibility/{axe-node-count,crawl-routes}.mjs` | 记录当刻 `scripts/accessibility/` **目录不存在**,可运行版仍在 `docs/acceptance/2026-09-21-axe/`(`axe-contrast-evidence.mjs` / `crawl-sitemap.mjs`)。**同日已闭合**:两脚本平移为 `scripts/accessibility/{axe-node-count,crawl-routes}.mjs`,判定改为退出码,并接进 `Jenkinsfile`「♿♿ 全站 axe 节点计数」阶段(详见 §5.25 末与 `docs/testing.md` 的 ⑤ 节) | 反向漂移:脚本先声明、实现还没搬。当时两条未被 `check:a11y` / `test:all` 引用,所以门禁没坏,但**文档一旦把 `check:axe` 列为已通过即为假绿** | **同轮的口径缺陷**:`AGENTS.md` §5 把「E2E 测试:`npm run test` 全部通过」当门禁,而该命令的 webServer 是 `npm run dev`,`ga4-event-tracking.spec.ts` 的 4 个 `@critical` 用例 × 4 project = **16 个实例是 skipped**(GA ID 只在 `.env.production`)。`skipped-tests-final-tree.json` 里这一组 `count:16`,占当轮 28 个 skip 的主体。「全绿」因此并不等于「全断言」。 **教训(管理归零)**: 1. 文档里每个带**文件名 / 脚本名 / 环境变量名 / 配置项名**的句子,都要能被一条 grep 或一次 `node -e "require('./package.json')"` 证伪;写不出取证命令的句子降级为"待核实"。 2. 反方案与历史记录**不得**被后一轮编辑改写成正方案(§5.16 是历史,`docs/testing.md` 把它写成了现行机制)。做法:历史只留在 `docs/lessons-learned.md`,机制描述只留在 `CLAUDE.md` / `docs/testing.md`,且引用同一处行号。 3. 「skipped 不算失败」≠「skipped 算覆盖」。任何按标签聚合的门禁(`@critical` / `@smoke`)在报告里都要连带披露 **skipped 明细与它属于哪个 E2E 目标**。 4. `package.json` 里指向不存在文件的 script 是**代码—代码**矛盾,比文档过期更早该修;本轮只在文档侧标注,不动 `package.json`(越界即需授权)。 **来源**:`package.json`(`scripts.*` 全量核对)、`next.config.mjs:4-14`、`e2e/playwright.config.ts:130-139`、`e2e/fixtures.ts:5-13`、`e2e/ga4-event-tracking.spec.ts:118-124`、`src/components/analytics/GoogleAnalytics.tsx:81,119`、`.env.production`、`node_modules/next/dist/server/next.js`(`getServer()` 的 standalone 警告)、`node_modules/next/dist/docs/01-app/03-api-reference/05-config/01-next-config-js/output.md`、`docs/acceptance/2026-09-21-gates/{skipped-tests-final-tree.json,ga4-production-run.txt}`、`docs/acceptance/2026-09-21-axe/axe-evidence.json`。 ### 5.27 门禁会在「错误的产物」上给出可信的绿:standalone 缺静态资源 + 子代理测试把门跑红 **背景**:2026-09-23 验收复核。两条同族事故都发生在「门禁已经接上、脚本也确实执行、退出码也确实被判定」之后 —— 也就是 §5.25/§5.26 那类「有没有跑」的问题都排除了,仍然出错。 **(a) 产物没装配,浏览器门禁对着裸 HTML 出数。** `next build` 在 `output: 'standalone'` 下**不**把 `dist/static` 与 `public` 放进 `dist/standalone`。镜像用 `Dockerfile` 的 `COPY` 补齐,CI 的 axe 阶段也自己做了拷贝(注释里写明「缺了它们对比度会『意外达标』」),但**本地跑法一步都没有**:`npm run lighthouse` 与手工 `check:axe` 直接起未装配的 `server.js` ⇒ `/_next/static/**` 全 404,页面落在默认黑白底上。后果分两级: - `check:axe` **诚实报红** —— 因为它带 `bgMismatch` 判据(底色必须等于当前主题令牌值)。 - `npm run lighthouse` 在同一条件下 **exit 0、perf 99-100、a11y 全绿** —— 因为它没有任何「样式是否加载」的前置断言。 同一份缺陷,一个抓到、一个放行。修复是新增 `postbuild` 脚本按 `Dockerfile:53-57` 同构装配;修复后对比度失败节点从 10 个(a11y 92-97)变为 **0 个(a11y 9/9 = 100)**。 **(b) 补测试的子代理把门禁本身跑红了。** 为闭合覆盖率缺口新增的 `src/components/sections/hero-particle-field-engine.test.tsx`,在一个「模拟无 rAF 的老宿主」用例的 `finally` 里写: ```js Object.defineProperty(window, 'requestAnimationFrame', { configurable: true, value: savedRaf }); ``` `defineProperty` 的属性描述符里 **`writable` 缺省为 `false`**(这不是 `Object.assign`/普通赋值的语义),于是全局 `requestAnimationFrame` 从「可写数据属性」变成「只读数据属性」;随后 `afterEach` 中 `rafSpy.mockRestore()` 走赋值还原,抛 `TypeError: Cannot assign to read only property`。表现极具迷惑性: - 输出仍是 `Test Suites: 1 failed` + `Tests: 1652 passed, 1652 total` —— 那 25 个用例**根本没跑**,但汇总行读起来像全绿。 - `npm run test:coverage > f 2>&1; echo exit=$?` 才看到 **EXIT=1**。管道里 `tail` 之后拿到的 0 是管道的退出码,不是 jest 的。 定位路径(可复用):① 单独跑该套件 → `0.956s / Tests: 0 total`,证明不是跨文件污染而是套件内部;② 用 `-t "用例名片段"` 逐例筛选 → 只有那一例失败、其余 24 例 skipped 仍绿,锁定到单个 `it`;③ 用 `jsdom` 裸实例对照 `pretendToBeVisual` 下该属性的描述符,确认「可写」才是常态,从而指向 `defineProperty` 的默认值。 **教训(管理归零)**: 1. **浏览器侧门禁必须断言自己的前置条件**。`bgMismatch` 这类「样式真的加载了吗」的哨兵,价值不低于它检查的那条规则;`lhci` 那类只断言分数的门禁,缺这个哨兵就会在错误产物上报绿。装配步骤要落在 `postbuild` 这种**不可绕过的钩子**里,而不是写在文档里靠人照抄。 2. **子代理交付的测试必须逐档隔离复跑**,且以 **EXIT 码**为准,不看 `Tests: N passed` 汇总行。`Test Suites: 1 failed` 与 `Tests: 1652 passed` 可以同时成立。 3. 凡在测试里改写**全局对象**属性(`window.*`、`navigator.*`、`Math.*`),还原一律走 `Reflect.getOwnPropertyDescriptor` + 原样 `defineProperty`,或干脆用 `jest.spyOn` 让框架负责还原;手写 `defineProperty` 时必须显式给出 `writable`/`get`/`set` 中与原描述符对应的每一项。 4. 复验端口必须换新端口。本轮两次踩到「上一版 server 仍占着端口」,`pkill -f "PORT=3101 node ..."` 匹配不到(`pkill` 看不到 env 前缀),结果拿到修复**前**的假 404。做法:记录 PID 并按 PID 收服,复验换端口。 **来源**:`package.json`(`postbuild`)、`Dockerfile:5-9,53-57`、`Jenkinsfile:350-355`、`scripts/accessibility/axe-node-count.mjs`(`bgMismatch` 判据)、`config/test/lighthouserc.json`、`src/components/sections/hero-particle-field-engine.test.tsx:364-382`、`docs/acceptance/2026-09-23-gates/final-verdict.md` §1/§3(N-9、N-12)。 ### 5.28 「探针看不见」不等于「没有问题」:一条 CSP 违规对两个审计一显一隐,而自造探针的正向对照自己就是假的 **背景**:2026-09-23 收尾复测中,`/contact` 是 9 个 URL 里唯一 Lighthouse best-practices 非满分的页(96),失败项只有 `inspector-issues`。定位过程中连踩三个方法学坑,每一个都足以把结论做成假的。 **坑一:同一个缺陷,两个审计看见的程度不同。** 同一份报告里 `errors-in-console` 是 **score 1 / items 0**(判为干净),而 `inspector-issues` 是 **score 0 / items 1**(`{"issueType":"Content security policy"}`)。CSP 违规走 DevTools 的 issue 通道,**不进控制台**,所以任何"看控制台"的门禁对它天然失明。更糟的是 `inspector-issues` 的 `subItems.items` 是空数组——**它不告诉你是哪条指令、哪个资源被拦**,光凭报告无法定因。 **坑二:自建探针采到「0 违规」,但探针在这一类上是聋的。** 用 Playwright 挂 `securitypolicyviolation`(`document` + `window` 双挂、`addInitScript` 注册)跑修复后的页面得到 0 条——这个 0 当时**不能**当结论,因为同一脚本里的正向对照也采不到:`page.evaluate(() => (0,eval)('1+1'))` 和 `addScriptTag({content: "(0,eval)(...)"})` 注入的代码经 CDP 进入,**Chromium 不对调试器注入的代码施加 `'unsafe-eval'` 判定**,既不抛错也不报违规。校准实验同时证明监听器**对子资源类是有效的**(`connect-src`、`script-src-elem` 两条违规被 document/window 都采到)。⇒ **正向对照必须在同一违规类别上成立**;跨类别采到事件,不等于这一类可采。最终结论因此建立在**发现问题的同一仪器**(`inspector-issues`)的前后 A/B 上,而不是自造探针的 0。 **坑三:真凶是第三方库的"能力探测",不是本站代码。** 根因是 Zod 4.4.3 的 `allowsEval`(`node_modules/zod/v4/core/util.js:145-162`):用 `new Function("")` 试探能否 eval,`try/catch` 吞掉异常,但浏览器仍就地点报一次违规。库在源码注释里把这件事写得很明白:*"strict CSPs report the caught `new Function` as a `securitypolicyviolation` even though the throw is swallowed"*。命中面与观测严丝合缝:全仓只有 1 个**活的**客户端模块在浏览器侧求值 zod ⇒ 9 个 URL 里只有它报。**排除法**同样重要:`https://www.google.com/g/collect`(不在 `connect-src` 白名单)在 gtag.js 里出现 17 次,看起来极像元凶,但真实浏览器加载的三条 GA4 hit 全部落在已放行的 `www.google-analytics.com` 并返回 **204**——「源码里出现的域名」≠「实际请求」,`ad_storage:'denied'` 压制了 Ads 侧目的地。修法用库认可的开关 `z.config({ jitless: true })`;它之所以**零行为变化**,是因为 CSP 下该探测本就返回 false、依赖它的 JIT 快路径(`schemas.js:971-972`)修复前后同样关闭——这一条是读源码确认的,不是猜的。 **教训(管理归零)**: 1. 报告「0 违规 / 0 问题」之前,必须先证明**同类**探针能采到非零;否则该 0 只能记作「未证」,不得记作「已验」。 2. 修一个由第三方库探测噪声引起的问题,**必须用发现它的同一仪器做前后 A/B** 来证明因果;换仪器(自造探针、curl、静态 grep)只能作旁证。 3. 收紧 CSP 后要**点名验证每一个第三方 hit 目的地**:从真实浏览器读 `requestfailed` 与状态码,而不是从库源码里数域名。GA4 这类"被吞掉失败"的链路,静默丢数据不会报错。 4. 一个缺陷若同时存在多个观测面(console / issue / 网络),门禁至少要有一个观测面覆盖它。本轮的 CSP 违规只有 `inspector-issues` 看得见,而它恰恰不在 `lhci` 的断言清单里——是人工读报告才抓到的。 **来源**:`node_modules/zod/v4/core/util.js:145-162`、`node_modules/zod/v4/core/schemas.js:970-972`、`node_modules/zod/v4/core/core.d.ts:66-70`(`jitless` 为公开带类型配置)、`lighthouse-reports/contact-2026_09_23_04_54_06.report.json`(修复前)、`src/app/(marketing)/contact/contact-content-v3.tsx:32`、`src/components/analytics/GoogleAnalytics.tsx:97`、`next.config.mjs:31`、`docs/acceptance/2026-09-23-gates/final-verdict.md` §3(N-11、N-13)。 ### 5.29 一条恒红的用例比一条恒绿的更诚实,但仍会被人读成「UI 坏了」 **背景**:2026-09-23 收尾时对最终树补跑视觉回归**只读比对**(`npm run test:visual:all -- --update-snapshots=none`,规范模式 dev server,5 project × 25 例)。结果 **EXIT=1,21 失败 / 104 通过**。第一读是「视觉层判红 ⇒ UI 可能坏了」,逐条读日志后完全反转:**没有任何一例是像素不符**,21 例全是测试装配自身的缺陷,且其中 20 例**从未绿过**。 **坑一:宽松选择器 + `.first()` 命中反垃圾蜜罐。** `visual-regression.spec.ts:148` 写的是 `input[type="text"], input[type="email"]`,而 `/contact` 表单里 DOM 顺序最靠前的那个 `type="text"` 是 `<input type="text" tabindex="-1" name="website" aria-hidden="true" aria-label="honeypot">` —— 一个**按设计隐藏**的机器人陷阱。于是断言变成「期望这个隐藏字段可见」⇒ `Received: hidden`,5/5 project 恒定失败,`input-default.png` 也因此从未被创建。**一般规则**:任何表单页上用裸类型选择器 + `.first()` 都在赌DOM 顺序;反垃圾/占位/预加载字段专门就是"存在但不可见"的,天然赢这个赌。写选择器时排除 `[aria-hidden="true"]`,或直接给被测控件加 `data-testid`(同档 `:154` 创始人语录用例已经是这么做的)。 **坑二:`element(s) not found` 与「UI 回归」是两件事。** `:130` 卡片用例在 `/products` 上找 `[class*="card"]` —— 该页没有任何 class 含这个子串(Tailwind 的类名是形状描述,不是语义标签)。这类失败长得像"组件不见了",实为**断言对象根本不存在**;把它记成 UI 缺陷会直接误导修复方向。 **坑三:页面清单与基线集合可以长期不一致。** `VISUAL_TEST_PAGES` 列了 `/products/erp-upgrade` 与 `/about/brand`,而这两个名字在**全部 5 个 project 目录**下都没有 PNG ⇒ 只读模式判红、默认模式(`updateSnapshots` 缺省为 `'all'`)**会静默创建**。最糟的中间态正是"列了但从不比对":看起来覆盖面 16 页,实际 14 页。 **坑四(同族复发,我自己的 harness)**:这一轮用后台命令跑,包装体是 `{ npm run ...; echo "VISUAL_EXIT=$?"; date; } > log 2>&1`。**命令组的退出码取自最后一条命令(`date`)**,于是框架通知我「completed (exit code 0)」,而真实门禁是 EXIT=1。唯一救回来的是我在日志里显式写了 `VISUAL_EXIT=$?`。**规则**:包装门禁命令时末位必须是 `exit $rc`;否则**判据只能取日志里的结果行,绝不能取通知里的 exit code**。这与 §5.27(管道吞退出码)、§5.28(探针的 0 未经同类对照)是同一族错误的第三种形态。 **教训(管理归零)**: 1. 门禁判红后**先分类再定性**:把失败按「断言层 / 参照层 / 渲染层」分开数,`0 例像素不符`这一条就把"UI 回归"整个假设否掉了。本轮因此能同时给出两个不矛盾的结论——**现存参照层面全绿(含 `/contact` 全页,等于独立确认了 N-11 的 `jitless` 改动无视觉外溢)**,装配层面 21 例坏测试待修。 2. **不做无法复验的门禁改动**:修选择器只会把「断言失败」换成「参照缺失」,仍红,而写参照需要授权 ⇒ 于是只记录精确修法与判据,不动脚本。这与"禁止半截实现"不冲突:交不出绿的时候,交**可执行的修法 + 归零判据**(复跑后失败数须从 21 归零,而不是换一个错误类别)。 3. 恒红用例其实比恒绿用例**便宜**:它不需要人看图就知道有问题。真正危险的是本轮 Lighthouse 那类情形(§5.28)——CSS 全 404 还 exit 0。 **来源**:`docs/acceptance/2026-09-23-gates/visual-readonly-finaltree.log`、`e2e/visual-regression.spec.ts:27-42,130,148`、`src/app/(marketing)/contact/contact-content-v3.tsx`(蜜罐字段)、`e2e/playwright.config.ts:21-25`(`snapshotDir` / `outputDir` 决定只读比对确实不写基线)、`docs/acceptance/2026-09-23-gates/final-verdict.md` N-15。 ### 5.30 覆盖率门禁的 `collectCoverageFrom` 划到哪,缺陷就活在哪儿 **背景**:2026-09-23 收尾阶段对 `src/app/**` 做了一次专项审查(subagent 扫描 + 主代理逐条读源码复核)。选它的理由很朴素:`config/test/jest.config.js` 的 `collectCoverageFrom` 只覆盖 `src/components/**`、`src/hooks/**`、`src/lib/**/*.ts`,**不含 `src/app/**`** ⇒ 全部 route handler 与页面都在棘轮之外,改坏了也不会有任何门禁变红。结果这一处找出 **3 个 P1**。 **三个缺陷是同一个形状的三个副本。** 项目里已经有正确的守卫抽象 `requirePermission()`(`src/lib/permissions.ts:71-86`,失败会真的 return response),但另有 **7 个 handler 复制粘贴** `authenticateRequest` + 内联角色数组检查。复制的那份里:`admin/stats` 掉了角色检查,只要"有会话"就返回**跨全部模型**的最近内容标题(含草稿);`auth/refresh` 补了账号状态校验(B-7),但**每个请求真正走的是另一条路**(`checkUserPermission` 从不读 `User` 行)⇒ 停用账号后旧令牌还能用满 24h;`cms/draft/enable` 为 B-6 写了 `isInternalRedirect()`,但把它定义成**文件内私有函数**,于是姊妹路由 `cms/draft/disable` 原样 `new URL(body.redirect)` 向外 307。**一个修好的缺陷因为修法不可复用,在旁边复活了。** **教训(管理归零)**: 1. **安全抽象必须可导入**。给某条路由打补丁时,若校验逻辑是新写的私有函数,同一目录树里的姊妹路由 100% 不会受益。要么提到 `src/lib/**`,要么当场改完所有调用点。 2. **"某个已修缺陷的同类还在别处"是可查的**:`grep` 那个修复引入的函数名,命中数 < 应有命中数就是线索。本轮 `isInternalRedirect` 命中 1 处(应为 2),一眼可见。 3. **修复必须带 RED 实测**,且**先看它能不能变红**。三处修复各做了一次"临时移除 guard ⇒ 相应用例判红 ⇒ 恢复转绿"的探针:`disable` 的 4 条载荷在修复前实测收到 `307`(证明开放重定向真实可利用,而非理论风险),`permissions` 的 3 条用例在删掉状态校验后 `3 failed, 20 passed`。**没做这一步,"我修好了"和"我改了段看起来像修好的代码"无法区分。** 4. **改共享鉴权函数会打爆测试桩,这是信号不是障碍**:在 `checkUserPermission` 前置一次 `prisma.user.findUnique` 后,恰好 4 个既有断言变红——因为 `permissions.test.ts` 的 prisma 桩里没有 `user`。正确处置是**补桩 + 加新用例**,而不是把校验挪到一个不查库的位置。 5. **数值口径要绑定被执行的那批文件**:修后 `test:unit` 是 133 套件 / 1691 例,而文档里的 1677 来自 `test:coverage`(套件集不同)。**两个数不可相减**,否则会把"配置差异"读成"本轮净增 14 例"。 **来源**:`config/test/jest.config.js`(`collectCoverageFrom`)、`src/lib/permissions.ts:71-86`、`src/app/api/auth/refresh/route.ts:23-25`、`src/app/api/cms/draft/{enable,disable}/route.ts`、`src/app/api/admin/stats/route.ts:9-10,49-59`、`src/lib/auth.ts:7`、`docs/acceptance/2026-09-23-gates/final-verdict.md` N-17..N-21。 ### 5.31 「谁来测门禁」:安全头检查里三条永远不会成立的断言,和一个声明测产物却实则打线上的脚本 **背景**:2026-09-23 验收尾声,本轮已经反复出现"门禁在错误的对象上给出可信的绿"(N-9 CSS 全 404、N-13 CSP 看不见、N-17 裸 `return` 伪装通过、N-15 恒红坏用例)。于是把同一套问题**对准门禁脚本本身**——因为 `scripts/**` 按构造没有任何自动化保护。派 subagent 扫 `scripts/**` + `Jenkinsfile`,主代理逐条读源码复核,命中四处恒不成立。 **四个坑(全在 `scripts/utils/check-security-headers.ts`,它是 `test:all` 的一环)**: 1. **算完就丢**:`checkCookies` 老老实实算了 `hasHttpOnly` / `hasSecure` / `hasSameSite` 三个标志,最后一行 `status: 'pass' as const`——**写死的字面量**。于是 `cookieFailed` 恒为 0。 2. **算了但没人看**:汇总判定 `hasFailures = headerChecks.some(c => c.status === 'fail')`,**压根不看 cookieChecks**。第 1 条即使改对,也仍然进不了退出码。这两条是"死断言"最省事的形态:**数据被完整地采集、展示、然后被判定逻辑遗忘**。 3. **两个分支完全相同的三元**:`return val ? 'warn' as const : 'warn' as const;`。它不会报错,只会永远返回 warn。 4. **最重要的判据反而最宽松**:缺 CSP 只 `warn`,而同文件里 `X-Content-Type-Options` 缺失判 `fail`。**同类判据的严重度不一致,往往就是漏判的位置**。 **外加一条结构性问题**:脚本 `parseArgs()` 的默认值是**线上域名**,`package.json` 调用时不带 `--url`,而 `Jenkinsfile` 在那一行前面打印的是「检查**本分支构建产物**的安全响应头」。**声明与行为相反**——CI 验的是已部署站点,改 `next.config.mjs` 里的头不会让 CI 变红。这条不是我推出来的,是**正向对照逼出来的**:把修好的门禁第一次指向本地 standalone 产物,它红了,唯一红项是 HSTS——因为 **HSTS 由 Nginx/CDN 在边缘注入**,Node 产物根本没有。也就是说这个门禁**结构上就不可能在分支产物上通过**,所以它的默认值只能指向线上,所以那个打印永远是假的。 **教训(管理归零)**: 1. **每个门禁修完,至少跑一次"它必须变红"的输入**。本轮做法是拿 `python -m http.server` 起一个没有任何安全头的本地服务:负向 ⇒ `EXIT=1 / 4 项 fail`;再指真实产物:正向 ⇒ `EXIT=0 / 0 失败`。**只有负向能证明第 1、2、4 条真的被修好了**——否则"我改了判定逻辑"和"判定逻辑仍然看不见任何东西"在输出上一模一样。 2. **正向对照和负向对照缺一不可,且顺序常常反直觉**。本轮先做负向(以为稳了),是**正向**暴露出 HSTS/边缘注入这个更深的问题。凡"改完在干净对象上仍判红",先怀疑门禁的**作用对象假设**(它以为自己在测什么),而不是先怀疑干净对象脏了。 3. **审计一个门禁,先看它的输入从哪来**:默认 URL 指向线上、默认端口指向 :3000(可能被别的服务占着)、默认目录为空时 `violations=0` 直接通过。**空输入 = 空转通过**是这类脚本最常见的形状;`crawl-routes.mjs` 那种 `paths.length === 0 → exit 2` 的写法才是对的。 4. **脚本存在 ≠ 脚本在跑**。`lighthouse-runner.js`(连 `module.exports` 都没有)、`coverage-trend.js`(读的字段在另一个文件里,必抛)等三个脚本没被任何 npm script / Jenkinsfile 引用。要么接入要么删掉——留着会让人以为有保护。 **来源**:`scripts/utils/check-security-headers.ts:60-68`(原 `status: 'pass' as const`)、`:137`(原同分支三元)、`:284`(原 `hasFailures` 只看 headerChecks)、`:34`(默认线上 URL)、`package.json:48,56`、`Jenkinsfile:293-294`、`next.config.mjs`(HSTS 不在应用头里)、`scripts/accessibility/crawl-routes.mjs`(正确的空输入写法)、`docs/acceptance/2026-09-23-gates/final-verdict.md` N-22/N-23/N-24。 ### 5.32 「按文件名推断机制不存在」写出的假事实,本仓自己的文档已经否定过它 **事故**:`docs/acceptance/qa-tracker.md` §2.2 的 DEC-N21b 长期记着「`/admin` 无服务端 gating(仅客户端跳转),HTML 外壳无会话也下发」,证据栏写的是**「无 `middleware.ts`」**。2026-09-30 封版复核:该文件不存在,但 Next 16 已把该约定**更名为 `src/proxy.ts`**(在 HEAD 内、已跟踪、`2297f01` 迁入),`:77-105` 对 `matcher: ['/admin/:path*']` 做 Edge HS256 校验并在缺令牌/验签失败时重定向登录页 ⇒ 所谓缺陷的**前提不成立**。 三条本可当场拦住的证据,登记时都没被用: 1. **本仓 `CLAUDE.md:108` 白纸黑字写着**「中间件命名为 `proxy.ts`(Next 16 起 `middleware.ts` 更名)」——假事实与自家权威文档直接冲突。 2. **构建产物会自报**:`npm run build` 的路由表末尾打印 `ƒ Proxy (Middleware)`,等于服务自己声明有这个装配。 3. **文件名不是搜索键**:按能力找(`matcher`、`NextResponse.redirect`、`/admin`),而不是按记忆中的文件名找。 **同族第二例(同轮发现)**:台账与 `AGENTS.md` 记「磁盘上 85 张视觉基线相对 HEAD 处于 modified、'视觉通过'依赖未提交状态」。实况是 `git ls-files e2e/visual-snapshots` = **107 张全部已入库、工作树干净**;真实缺口是 20 张缺参照 + 11 张已过时参照。**文档里的文件计数与「是否已提交」必须以 `git ls-files` / `git status` 现取**,不能沿用上一轮的叙述。 **规则**:任何「某机制不存在 / 某能力缺失」的断言,落笔前必须给三样东西——① 该框架版本对应该机制的**当前约定文件名**(版本改名是常态);② 一次按**能力关键词**的检索结果;③ 一条产物级或运行时的正向证据。三者缺一,就只能写成「待复核」,不得写成缺陷。 **来源**:`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`。 ### 5.34 「🎉 部署成功」之后线上是破站:HTML 全 200,而它引用的 CSS/JS 全 404 **事故(2026-10-08 17:31)**:`./scripts/deploy.sh deploy` 打完 `DEPLOY_EXIT=0`、五个页面全 200、脚本自己输出「✅ 生产环境验证通过 / 🎉 部署成功」。但用 `curl` 取首页 HTML 里**实际引用**的 `/_next/static/chunks/*.js|*.css` 与 `/favicon.ico`,全部 **404**(`server: nginx` 应答,`try_files $uri =404`)⇒ 真实用户打开的是无样式、无脚本的破站。恢复耗时约 4 分钟,且是**我在脚本判绿之后另做复核**才发现的——不是门禁抓到的,是人抓到的。 **根因是两种产物形态 + 一次 `--delete`**:远端 nginx 的站点根就是上传后的 `dist/`(`nginx-static-production.conf:132` `root /var/www/novalon;`,而该 mount 指向宿主 `.../novalon-website/dist`),`location /_next/static/` 因此要求磁盘上有 **`dist/_next/static/**`**;但 `next build` 出的是 `dist/static/**`(无 `_next` 前缀),`postbuild` 只补 **standalone 容器**形态。历史上那份「web root 镜像」是旧发布流程手工产出的(`dist_backup_20260905_113209/` 顶层确有 `_next/static` 与合并进来的 `fonts/ images/ *.svg`),本次 `rsync -avz --delete` 把它抹掉 ⇒ 第一次「干净部署」即红。 **三条规则**: 1. **部署后验证必须从页面实际引用的 URL 取样,而不是只查页面路径**。已固化进 `verify_remote`:抓首页 HTML → 取前 5 个 `/_next/static/*.{js,css}` + `/favicon.ico` → 逐个断言 200,任一非 200 即 `return 1`。并做**负对照**:把取样 URL 换成不存在者,实测输出 `RED 404` 且 `failed=1`——不能失败的门禁不是门禁(同 §5.23、§5.30 的「空集合 `every` 为真」族)。 2. **`rsync --delete` 的目标目录若被别的流程写入,本脚本必须自己重新生成那部分内容**。否则镜像/派生文件会在第一次部署时被静默删除,而删除动作在日志里完全不可见。修法是把生成步骤放进上传之前(`deploy.sh` 步骤 1.5),并对前置条件缺失(`dist/static` 不存在)**终止部署**而非继续。 3. **改任何一侧产物形态前,先确认另一侧的契约**:`standalone`(容器内 `COPY dist/standalone`、`dist/static`、`public`)与 nginx web root(`_next/static` + 根级 public)不是同一棵树。`Dockerfile.prod` 两侧 md5 一致(`0ccd495490694a6bf71d4ff17270d2ed`)排除了镜像构建漂移,问题只出在上传目录。 **区分「我引入」与「既有」的取证法(值得复用)**:`nginx access.log` 里按 URL grep 历史状态码——本次现取 **2026-10-07**(部署前一日)`/_next/static/chunks/*.js` 为 **200**,一句话就把回归定性成自己引入的,不必猜。同理,`docker inspect <容器> --format '{{range .Mounts}}...'` 看**真实挂载**,比读仓内 compose 可靠:仓里 `docker-compose.server.yml` 已把 uploads 改成 `/app/public/uploads`,服务器跑的仍是旧的 `/app/uploads`,因为 `deploy.sh` 从不同步 compose/Dockerfile(登记为发布链漂移,见 `docs/deployment.md` §七)。 **管理归零**:① 发布类脚本的「成功」判据必须包含**资源级**断言,已写进 `verify_remote`;② 生产发布前新增一道**预生产演练**——取真 `prod.db` 副本、用同一份产物在本地端口起 `node dist/standalone/server.js` 打 14 条路由(本次全 200,才继续上线);③ 回滚路径要连容器一起回(`cmd_rollback` 只恢复 `dist/`,会留下「旧静态 + 新服务端」的 Server Reference ID 不匹配),正确手工步骤已写进 `docs/deployment.md` §七。 **来源**:`docs/acceptance/qa-tracker.md` §10(时间线、恢复命令、Playwright 三页 0 失败资源证据)、`scripts/deploy.sh`(步骤 1.5 与资源断言)、`/home/novalon/docker-app/novalon-nginx/nginx-static-production.conf:132,136-142`、`dist_backup_20260905_113209/` 目录形态、`nginx access.log` 2026-10-07 状态码。 ### 5.35 把「命令报错」读成「查无此项」:一次 `2>/dev/null` 让整条 PR 路径被判为不可执行 **事故(2026-10-08,同日自纠)**:台账连续两轮(§8.5 B、§9.5 B)写着「本环境**无 Gitea token** ⇒ PR 不可执行」,并把「建 PR」降级为「只能由人在浏览器点」。探测命令是: ```bash env | grep -i -E "gitea|token" # 空 ls -d ~/.config/gitea ~/.gitea # 不存在 git config --get-regexp -i "gitea|credential" 2>/dev/null # ← 空 ``` 第三条**根本没执行成功**:`git config` 不认识 `-i`,它打印的是 `error: unknown switch 'i'` 到 **stderr**,而 `2>/dev/null` 把这条唯一线索丢掉了,stdout 为空 ⇒ 我把它当成「配置里没有 credential 条目」这个**负事实**写进了台账。实际凭据链完整:`credential.helper=osxkeychain`(由 **Xcode 的系统级** `/Applications/Xcode.app/Contents/Developer/usr/share/git-core/gitconfig` 提供,不是用户配置,所以最容易被漏),keychain 里有 `git.f.novalon.cn` 条目,`GET /api/v1/user` 现取 **HTTP 200** ⇒ PR 其实一直可脚本化,最终建成 **#29**。 **规则**: 1. **探测负命题时禁止丢弃 stderr**,且必须显式看退出码。写「查无 X」的结论前,先跑一次不带 `2>/dev/null` 的同命令,确认它是**成功返回空**而不是**失败**。与 §5.23(空集合上 `every` 为真)、§5.28(正向对照自己就是假的)同族:**未证伪的探测不是证据**。 2. **凭据发现要用凭据协议本身**,而不是 grep 变量名与猜文件路径:`git credential fill`(喂 `protocol/host` 看它能否吐出 username/password)、`git config --show-origin --get-regexp credential`(`--show-origin` 是关键——本例的 helper 来自 Xcode 系统配置,不带 origin 就看不出来源)。环境变量与 `~/.config/*` 只是众多来源中的两个。 3. **被写进台账的「不可执行」是最高成本的假事实**:它会让后续会话直接跳过一条真实可行的路径。本例中它让「发布无治理痕迹(无 PR)」这个缺口多活了两轮。凡结论形如「X 做不到」,都要留**可复跑的证伪命令**(这里是 `curl -u … /api/v1/user`)。 **来源**:`docs/acceptance/qa-tracker.md` §9.5 B 与 §8.5 B(已就地作废)、§10.7(PR #29 与 API 回读)、`git config --show-origin --get-regexp credential` 现取输出。 ## 6. 代码组织 ### 6.1 组件版本膨胀 - **问题**:组件目录存在多个版本迭代(detail-v2/, detail-v3/),造成混淆和冗余。 - **根因**:多次重构未清理旧版本,缺乏组件生命周期管理。 - **方案**:重构完成后立即删除旧版本目录;使用 `_archive/` 归档历史版本,并排除在 TypeScript 编译之外。 - **来源**:`CLAUDE.md` Archiving Convention。 ### 6.2 文档与代码不同步 - **问题**:`docs/` 目录中部分文档(如组件指南、API 文档)与实际代码不一致。 - **根因**:文档更新未纳入代码审查流程。 - **方案**:文档变更必须与代码变更在同一 PR 中审查;`CONTEXT.md` 作为共享语言文档,与领域模型同步更新。 - **来源**:`AGENTS.md` 文档同步要求。 --- ## 7. App Router 路由行为 ### 7.1 `loading.tsx` 会吞掉子动态路由的 `notFound()` - **问题**:`/services/[id]`、`/products/[id]`、`/solutions/[id]`、`/news/[slug]` 等动态路由对未知 slug 调用 `notFound()` 后,仍然返回 HTTP 200(软 404)。 - **根因**:`(marketing)/loading.tsx` 在路由组层级创建了 Next.js Loading/Suspense 边界,该边界会捕获子页面抛出的 `NEXT_NOT_FOUND` 错误,导致 `not-found.tsx` 无法被渲染,HTTP 状态也保持为 200。 - **方案**:移除 `(marketing)/loading.tsx`;如需加载状态,改为在页面内部使用 `<Suspense>` 包裹特定慢加载区块,而不是在路由组层级全局添加 `loading.tsx`。 - **验证**:`curl -I http://localhost:3000/services/unknown` 返回 `404 Not Found`;`e2e/p5-edge-cases.spec.ts` 404 相关用例全部通过。 - **来源**:2026-07-25 dogfood 修复,`dogfood-output/report.md`。 --- ## 更新记录 | 日期 | 更新内容 | 来源 | |------|---------|------| | 2026-07-07 | 初始创建,从 project_memory.md 和 docs/ 中提取 | 现有文档 + 记忆文件 | | 2026-07-25 | 增加 App Router `loading.tsx` 与 `notFound()` 交互的经验教训 | dogfood 修复 | | 2026-07-26 | 增加 E2E 文本断言同步、视觉回归基线更新两条经验教训 | dogfood 后续验证 | | 2026-07-27 | 增加 Playwright storageState 路径、Firefox 全页导航竞态两条经验教训 | 全量 E2E 回归失败排查 | | 2026-09-21 | 增加 §3.4(`aria-hidden` 不豁免对比度)与 §5.10–§5.13(触摸目标 AA/AAA 档位、mobile project 视口、`<title>` 帧延迟、品牌审计判过期需证据)| 2026-09-21 验收复核(A-12 / A-17 / P1 品牌审计)| | 2026-09-21 | 增加 §5.14–§5.15(视觉基线不得绑定 dev/prod server、视觉与写库用例并发的缓存污染)| 2026-09-21 验收视觉回归 83 例失败根因 | | 2026-09-21 | 增加 §5.16–§5.18(dev 指示器 shadow DOM 穿透污染严格定位、hydration 前指针事件被丢、StrictMode 双跑使 Cookie 同意条在 dev 下永不渲染)| 2026-09-21 验收功能 E2E 68 例失败与 A-11/A-12 门禁三重失效根因 | | 2026-09-22 | 增加 §5.19(同意条 2s 定时器 × 跨引擎空 storageState ⇒ 视觉基线竞态,34 例只失败在 firefox/webkit project);§5.16 的方案由 `devIndicators:false` 改写为 `e2e/fixtures.ts` 全局夹具并记录该反方案为何无效 | 2026-09-21 验收复跑:功能 1052 通过 / 视觉 34 例竞态定位 | | 2026-09-22 | 增加 §5.21(品牌审计 spec 的 catch 吞断言 + 错误前提,及其闭合:10 处改写 + 4 project 124 通过)与 §5.22(`/products/erp-upgrade` 的 `text-brand-ink/10` 水印数字被四道门禁同时漏过 ⇒ 双引擎双主题 axe 节点计数首轮 4/4/4/4,修复为 `text-brand-ink/80` 后归零;口径教训:节点数 ≠ 规则数,新页必须进 Lighthouse URL 表与视觉回归路由表)| 2026-09-21 验收放行条件②⑤复跑与门禁可信度审查 | | 2026-09-22 | 增加 §5.23(两类自伤缺陷:证据脚本在 `routeCount=0` 的空集合上判 `every` 为真而打印 PASSED=true ⇒ 计数型门禁必须同时断言分母;门禁脚本 `process.exit()` 跳过 `finally` 且只 kill 包装进程 ⇒ `next-server` 孤儿占住 :3000,被 `reuseExistingServer` 静默复用,把 1080 例套件拖成 53.6 分钟 / 805 通过 / 263 失败(205 个是 `page.goto` 超时)⇒ 证据链每步前后打印端口占用数)| 2026-09-22 最终树串行证据链 chain2 失败复盘 | | 2026-09-22 | 增加 §5.24(⑤ 的路由清单由 sitemap 29 扩成 sitemap ∪ 预渲染产物 ∪ BFS = 35,扩目录首轮即 `passed=false`:`/_not-found` 的 h1 用 `opacity-20` 破 AA、`/_global-error` 因缺 `global-error.tsx` 由 Next 内置壳顶替而无 `lang` 且深色丢令牌;另归零三例「隔离必过 / 满负载必挂」的 E2E —— p4 把 `waitForTimeout` 计入加载耗时、p3 两段式 `isVisible`→`boundingBox`、uj-11 与 p2 的 hover 下拉点击竞态。口径教训:门禁覆盖 = 清单来源,sitemap 只覆盖"想被收录的页")| 2026-09-22 chain3 全站 axe 扩目录扫描 + 4 例 E2E 隔离复跑 | | 2026-09-22 | 增加 §5.21(`p1-brand-visual-audit.spec.ts` 三处 `catch` 吞断言 + `:476` 对纯 `<path>` 图标 SVG 的错误前提,实测「断言失败但用例 ✓」;给出「日志软失败 × 用例状态」配对的低成本检假绿法);§5.20 补记第二个坑:把死样式点亮后 `hover:bg-brand/20` 浅色合成 4.18:1 破 AA,而 axe / `check:contrast` 均看不见,最终改 `bg-brand-soft`,并把修正后的类名与行号写回 | 2026-09-22 最终树全量运行日志复核 | | 2026-09-22 | 增加 §5.25(Lighthouse 门禁里 3 条恒不成立的死断言 `autocomplete-valid`/`presentation-role-conflict`/`svg-img-alt`:以 21 份报告的 175 个审计 id 并集 + `@lhci/cli` 自带 `lighthouse@12.6.1` 的 64 个 a11y 审计文件双源定性;删断言前先做 tag 覆盖探针,发现 `presentation-role-conflict` 属 `best-practice` tag、现有 axe 门禁根本不跑 ⇒ 处理为「删死断言 + 在 axe harness 加规则级 `runOnly` 并断言每页 `extraRulesChecked===3`」;另记录一次 2 秒 `type-check` 的正/负对照自证与 `AGENTS.md` lint 计数 105→106 的纠偏)| 2026-09-22 chain6 Lighthouse 日志复核 + chain7 复验 | | 2026-09-23 | 增加 §5.26(文档同步轮:四处「句式完整但指向不存在之物」的假事实——`NEXT_DEV_INDICATORS=off` 反方案被写成了现行机制、`npm run preview` 仍写作 `npx serve`、"images unoptimized ⇒ 静态导出限制"的因果过期、`package.json` 的 `check:axe*` 曾指向当时缺失的 `scripts/accessibility/`(同日已平移落地并接进 CI ♿♿ 阶段);外加 skipped≠覆盖的 E2E 目标口径缺陷与「带文件名的句子必须可被一条 grep 证伪」的归零清单)| 2026-09-23 文档—代码一致性回扫(只改文档;同一轮内 `scripts/accessibility/` 由并发作业补上,故本节的每条断言都注记了复核时刻)| | 2026-09-23 | 增加 §5.27(两条「门禁在错误对象上给出可信绿」的同族事故:① standalone 产物不含 `dist/static`,本地 `npm run lighthouse` 与手工 `check:axe` 在全站 CSS 404 的裸 HTML 上出数 —— axe 因 `bgMismatch` 哨兵诚实报红,Lighthouse 无此前置断言故 exit 0 且 perf 99-100,修复为 `postbuild` 不可绕过钩子,修后对比度失败节点 10→0、a11y 92-97→9/9 全 100;② 补覆盖率的子代理测试用 `Object.defineProperty` 还原全局 `requestAnimationFrame` 时漏写 `writable`(该描述符缺省即 `false`),使属性变只读、`afterEach` 的 `mockRestore()` 抛错 ⇒ 套件 failed to run 而汇总行仍打印 `Tests: 1652 passed`。给出「单独跑套件看 `Tests: 0 total`、再用 `-t` 逐例收窄」的定位路径,与「子代理产物必须逐档隔离复跑且以 EXIT 码为准」的归零条款)| 2026-09-23 系统性复核收尾(N-9 / N-12,证据见 `docs/acceptance/2026-09-23-gates/final-verdict.md`)| | 2026-09-23 | 增加 §5.28(`/contact` 的 CSP 违规定位三坑:① 同一缺陷对 `errors-in-console`(1/0 items)与 `inspector-issues`(0/1 item)一显一隐,issue 通道不进控制台;② 自造 Playwright 探针采到「0」但正向对照同为 0——CDP 注入的代码不受 `'unsafe-eval'` 判定,而 `connect-src`/`script-src-elem` 类经校准证明确可采,故**正向对照须同类**、未经对照的 0 记为「未证」;③ 真凶为 Zod 4.4.3 `allowsEval` 的 `new Function` 探测(库源码注释自述该现象),以带类型的公开开关 `z.config({jitless:true})` 修掉并经 `inspector-issues` 同仪器 A/B 确认 BP 96→100,同时排除「`www.google.com/g/collect` 被拦」的假定因——GA4 实测三条 hit 全落在已放行的 `www.google-analytics.com` 且返回 204)| 2026-09-23 收尾复测 N-11/N-13(`docs/acceptance/2026-09-23-gates/final-verdict.md` §3、`lighthouse-reports/contact-2026_09_23_04_54_06.report.json` 与修复后重跑)| | 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 | | 2026-10-08 | 增加 §5.34(`deploy.sh` 打印「🎉 部署成功」后线上实为破站:HTML 全 200 而首页引用的 CSS/JS/图标全 404。根因 = nginx web root 需要 `dist/_next/static/**`,而 `next build` 出 `dist/static/**`、`postbuild` 只补 standalone 形态,历史镜像被 `rsync --delete` 抹掉。三条规则:部署后验证须从页面实际引用的 URL 取样并做负对照;`--delete` 目标若被别的流程写入则本脚本须自行重新生成;改产物形态前先确认另一侧契约。附「用 nginx access.log 历史状态码区分我引入 vs 既有」与「`docker inspect` 看真实挂载而非读仓内 compose」两条取证法) | `docs/acceptance/qa-tracker.md` §10、`scripts/deploy.sh` 步骤 1.5 + 资源断言、`docs/deployment.md` §七 | | 2026-10-08 | 增加 §5.35(把「命令报错」读成「查无此项」:`git config --get-regexp -i …` 因非法开关报错、被 `2>/dev/null` 吞掉,于是把「本环境无 Gitea token ⇒ PR 不可执行」写成连续两轮台账假事实;凭据其实在 Xcode 系统级 `credential.helper=osxkeychain` 里,API 现取 200,PR #29 已建成。三条规则:负命题探测禁止丢 stderr 且要看退出码、凭据发现要用 `git credential fill` / `--show-origin`、写进台账的「不可执行」是最高成本假事实且须附可复跑证伪命令) | `git config --show-origin --get-regexp credential`、`docs/acceptance/qa-tracker.md` §8.5 B / §9.5 B / §10.7 | | 2026-10-17 | 增加 §5.38(`npm run lint \| tail` 把真实的 `LINT_EXIT=1 / 2 errors` 吞成 0;本仓 memory 已立过同条仍复犯 ⇒ 门禁命令一律重定向到文件再读退出码,`for s in …; do npm run $s \| tail` 形式会把一整批闸的退出码统一替换成 0)| `docs/acceptance/qa-tracker.md` §11.2 D-1 | | 2026-10-17 | 增加 §5.39(注释写在 JSX children 位即成文字节点:type-check、1747 例单测、`npm run build` 三道全绿而页面上看得见 `/* … */`;唯一静态防线是 `react/jsx-no-comment-textnodes`。新增回归断言配「敏感性证明」——先断言被污染的两段 DOM 真渲染了,再用变异确认只有这一条转红)| `src/app/(marketing)/solutions/solution-detail-content-v3.test.tsx`、qa-tracker §11.2 D-2 | | 2026-10-17 | 增加 §5.40(仪器只在被复用时才坏:`results` 累加器挂 module 层 ⇒ 第二次 `checkGrammar` 的 `.find("R10")` 取到第一份读数,棘轮负对照被读成不判红;同族第二例是自证夹具把「营销面违规」与「豁免全命中」两个互斥前提写进同一份数据,使腐化那一维永远测不到 ⇒ 拆成三个各测一维的情景,含一个全绿情景防恒红)| `scripts/check-visual-grammar.mjs`、`scripts/check-accents.mjs` | | 2026-10-17 | 增加 §5.41(僵尸令牌:CSS 声明退役而 tailwind 映射未删 ⇒ 类照生成、`var()` 静默取空;R5/R7 各看一侧所以两条都绿。删映射并新增 R11 反向守卫(外部所有者按名豁免且豁免腐化亦判红),负对照实测 `EXIT=1 / 悬空 2 条` ⇒ 还原 11/11。附两条仪器纪律:豁免名单单一真源、先怀疑夹具再怀疑判据)| `tailwind.config.js`、`scripts/check-visual-grammar.mjs` R11、`docs/acceptance/2026-10-17-ia-e2e/` | | 2026-10-17 | 增加 §5.42(自伤型验证:为清 ISR 缓存手删 `dist/**` 连带删掉已编译的 `news/page.js`,页面 500 而「uj03 命中 0」被读成清除成功;重建后才发现库里真有 2 条因中途失败而未清理的测试行。三条纪律:重置 ISR 只靠重建或 revalidate、「命中 0」必须配页面健康的正对照、破坏性清理后要清点留下的半成品数据。附正面收获:`/products` 移动端孤儿由守卫抓到,判红是对的)| `docs/acceptance/qa-tracker.md` §11.5 | | 2026-10-17 | 增加 §5.43(`e2e/**/*.ts` 不在 tsconfig include ⇒ type-check EXIT=0 而 spec 里重复 `const revalidateSecret` 让整档无法加载;改 e2e 后必须 `npx playwright test <spec> --list` 才算验证「能加载」)| `e2e/user-journey.spec.ts`、qa-tracker §11.5 DEC-N6 | | 2026-10-17 | 增加 §5.44(守卫自己抄了一份令牌值:axe 底色哨兵硬编码 `rgb(10,14,20)` 而暗色底早在基线前就暖化成 `20 18 16` ⇒ 哨兵恒红且伪造出「样式未加载」的错误诊断。三条纪律:先归因再修闸、把副本换成真源而不是改抄本、换完必须重做负对照。附 `scripts/**.mjs` 不在 tsconfig 覆盖内、退出码分档在崩溃时兑现价值)| `scripts/accessibility/axe-node-count.mjs`、`docs/acceptance/2026-10-17-ia-e2e/probe-bg-negative.mjs` | ### 5.36 判据的适用对象没写进判据:diff 包围盒对全页截图必然假红 视觉基线第一批(只换字标)用「diff 包围盒不得越过页眉底边 y=96」追认,跑完报 15 张越界、diff 延伸到 y=20165,看起来像"改动漏进正文"。真相是全页截图里页眉下方是一块连续内容,**页眉 1px 的高度抖动就让 正文逐行错位**,包围盒必然铺到页底;该判据只对元素级截图成立。 处置:改成**平移感知**判据 `deliverables/logo-redesign-2026-10-13/check-baseline-shift.cjs` —— 先估计正文带 的垂直位移 k(行亮度签名,|k|≤48 逐像素密搜+远场粗搜精修),**候选必须由像素残差复验**(行签名是每行 一个均值的弱信号,合成样本里它给出过等价混叠峰,把该绿的判成红),再在 k 对齐后逐像素比正文重叠带: 残差 ≤0.4% 判绿、以上判"平移解释不了"。`--selftest` 四样本两绿两红(合成图必须做得像截图:白底行+文本带, 逐行随机噪声测的是搜索步长不是判据)。元素级整帧含字标的基线(`header-navigation`)没有"正文"可守 ⇒ 按名登记豁免,并反向断言"名单里的名字一张都没变=登记表过期=报红"。 **规则:判据要在文件头写清它成立的对象类型;对某类对象系统性成立的假设,就是一条会误报的判据。** ### 5.37 令牌孪生通道漏改:`check:contrast` 与视觉基线一起假绿 P1 色板迁移改了 `globals.css` 68 处 hex,第二批重跑基线却报 **125 passed / 0 张重写**。这个"0"不是 "色板无影响",而是**色板只落了一半**:43 条 `-rgb` 三元组中 22 条从未迁移(`:root` 11+深色块 11, 色相仍 H 210–217 冷蓝),而 Tailwind 把 29 个颜色键映成 `rgb(var(--X-rgb))` ⇒ **渲染主通道走的是没改的那条**。 同时 `check:contrast` 44/44 全绿(它读 hex)。⇒ 两条纪律: ① 迁移后"0 重写/0 命中"要先怀疑自己漏改,而不是当成"改动无效"或"改动安全"; ② 一个语义有多条表示通道时,守卫必须按定义逐通道对账 —— 已新增常驻闸 `npm run check:token-twins` (按 selector **块内**配对;第一版按全文件最后一个同名 hex 配对,跨明暗两块错配报出 26 条假红; 0 条声明判红、孤儿判红)。修完 43/43 一致,`check:contrast` 44/44、`check:brand-token` 仍绿。 并记一条仪器量程:`e2e/visual-regression.spec.ts` 未设 per-pixel `threshold`,Playwright 缺省 0.1, `#64748B → #6E675D` 的逐通道距离 (10,13,46)/255 正落在阈值附近 ⇒ **视觉基线在设计上看不见弱文字转暖**, 它守版式与图形不走样;色板到位由 `check:token-twins`+`check:contrast` 分工担保。 另:104 张基线(≈138 MB)压在单个 commit 会被 Gitea 的 HTTP 413 拦下,按 project 拆成 5 个 commit 再逐笔 `git push origin ${sha}:refs/heads/<br>` 才推得动(详见 §5.35 同族的"命令报错不等于查无此项")。 ### 5.38 管道吞退出码又复犯一次,而这次它吞掉的是「两个 error」 `npm run lint | tail -6` 之后 `echo $?` 读的是 `tail` 的退出码。本仓 memory 里 (`feedback-scratch-probe-pitfalls`)已明写过这条,仍在同一轮里踩中:真实输出是 **`83 problems (2 errors, 81 warnings)`、`LINT_EXIT=1`**,而我打印出来的是 `LINT=0`。 纪律:**门禁类命令一律重定向到文件再读退出码**,不许接管道。 ```bash npm run --silent lint > /tmp/lint.txt 2>&1; echo "EXIT=$?" # 对 npm run --silent lint | tail -6; echo "EXIT=$?" # 错:拿到的是 tail 的 ``` 同一条 `for s in a b c; do npm run --silent $s | tail -4; done` 形式尤其危险: 它把每个闸的退出码统一替换成 0,一整批"绿灯"里没有一个是真的。 ### 5.39 合法 JSX 里的注释会渲染成页面文字:type-check、1747 例单测、build 三道全绿也拦不住 上一笔为了修「注释占了 ternary 分支根位导致 Turbopack 报 `Expected '</', got 'ident'`」, 把注释从分支根位挪进了 JSX children —— 但没包 `{/* … */}`,于是它变成**文字节点**: ```jsx <div className="w-14 h-px bg-brand" /> /* 这段解释会在页面上被读者看见 */ <span className="text-xs …">Solutions</span> ``` `npm run type-check` EXIT=0、1747 例单测全绿、`npm run build` EXIT=0、视觉基线也不认得它。 唯一拦住它的是 ESLint 的 `react/jsx-no-comment-textnodes`(severity=error), 而它的 EXIT=1 恰好被 §5.38 那个管道吃掉。⇒ 三条教训合成一条: **"编译通过 + 测试通过" 对"内容是否被正确渲染"这一维根本不敏感**; 新增守卫时断言要配**敏感性证明**——`solution-detail-content-v3.test.tsx` 里那条 `container.textContent` 不含 `/*` 的断言,先断言被污染的两段 DOM 确实渲染了 (`Solutions` / `推荐产品组合` / `+`),否则"找不到注释"可能只是"那段根本没出现"; 再用变异验证(把注释改回裸文本 ⇒ 仅这条转红、其余三条仍绿)。 ### 5.40 仪器只在被复用时才坏:module 层累加器让第二次读数是第一次的 `check-visual-grammar.mjs` 把 `const results = []` 和 `rule()` 放在 **module 作用域**, `checkGrammar()` 只往里 push、不重置。主流程调一次 ⇒ 毫无症状。当我为了自证 R10 棘轮 而**第二次**调用 `checkGrammar` 时,`.find(x => x.id === "R10")` 命中的是数组里**第一份**读数 (喂的是 0 处抬升的坏样本),于是"上限+1 判红"这一维被读成不判红,自证 EXIT=1。 判据:任何"被喂样本"的函数**不得依赖调用间可变状态**。累加器收进函数作用域后复跑通过。 同族缺陷在本轮还有一次:自证夹具把「营销面有违规」和「三条豁免都有命中」两个**互斥前提** 写进同一份数据,导致"豁免腐化"那一维永远为假 —— 拆成三个各测一维的情景(含一个全绿情景, 防的是判据写错成恒红也会"抓到所有负例")。 ### 5.41 僵尸令牌:删了 CSS 声明却没删 tailwind 映射,类名照生成、值静默为空 `--shadow-brand / --shadow-brand-hover / --shadow-glow` 三枚从 `globals.css` 退役后, `tailwind.config.js` 里 `boxShadow.brand/'brand-hover'/glow` 三行映射**原样留着**。 后果不是报错:`shadow-brand` 这个类仍被生成,展开成 `box-shadow: var(--shadow-brand)`, 而该自定义属性无人声明 ⇒ 运行时取空、**静默什么都不画**。 `check:grammar` 的 R5(令牌已退役)和 R7(业务代码零消费)当时**都是绿的**—— 因为它们各看一侧,谁都不看 tailwind↔CSS 这条缝。这与 §5.37 是同一族: 一个语义有多条表示通道时,守卫必须按定义逐通道对账。 处置:删掉三行映射,并新增 R11「tailwind 引用的 `var(--*)` 必须在 `globals.css` 有声明」, 外部所有者的变量(`--radix-accordion-content-height`)按名登记豁免、且**豁免腐化亦判红** (登记了却没被引用 = 红)。R11 负对照已执行:把两枚退役映射塞回 tailwind ⇒ `EXIT=1 / 悬空 2 条`,还原 ⇒ 11/11 成立;实测引用 144 个变量、悬空 0。 写 R11 时自己踩了两个小坑,都值得记: ① 豁免名单写在规则里、夹具里再手抄一遍 ⇒ 改一处另一处悄悄失效(把名单提到 module 层共用); ② 夹具不带那条外部所有者引用 ⇒ 「豁免腐化」先判红,把"已声明不误报"这一维污染成假红, 差点被读成判据坏。**先怀疑夹具,再怀疑判据**。 ### 5.42 自伤型验证:为了清缓存手删构建产物,然后把自己的破坏读成"问题已消失" 为了去掉一份冻结在磁盘上的 ISR 产物(`dist/standalone/dist/server/app/news.html` 里 还带着早已删除的 `uj03-test-news-*` 行),我对构建输出目录做了 `rm -rf`—— 连带删掉了**已编译的页面模块** `…/(marketing)/news/page.js`。 于是发生三件连起来才看得出全貌的事: 1. standalone 服务打 `Error: Cannot find module '…/news/page.js'`(×6), 依赖 `/news` 的旅程因页面 500 而红。 2. 我当时的"清除验证"是数产物里的 `uj03` 命中数,得到 **0**,看起来像"缓存已干净"。 真相是 **500 的错误页里当然不含那一行**。 这条 0 是自伤的副作用,却被读成了修复成功 —— 与 §5.34(部署判据只看 HTML 200、 不看它引用的资源)同族,但方向更坏:**它把"页面挂了"读成"数据干净了"**。 3. 重建 `npm run build` 后 `news.html` 里 `uj03` 又出现 2 次 —— 才暴露库里真有 2 条残留: 是 UJ-03 因为我破坏的产物而**中途失败、teardown 没跑完**留下的半成品数据。 ⇒ 三条纪律: - **重置 ISR 只能靠重新构建或调用 revalidate,不许手删 `dist/**`**。 `dist` 里既有可丢弃的缓存也有必需的编译产物,二者同层,肉眼分不开。 - 任何「命中 0 / 计数 0」式的清除验证,必须**同时断言页面是健康的** (正对照:状态码 200 且关键锚点在场)。否则"仪器坏了"与"问题没了"共用同一个 0。 - 破坏性清理让用例中途失败之后,要回头清点它**留下了什么数据**, 而不是只修那条红的断言。本轮善后:按 id 删除自造的 2 条 news 行 (连带 `AuditLog.targetId` 与 `ContentZone.items` 里的 JSON 引用), `news` 已发布行回到 seed 的 2 条,再重建产物。 顺带一条 IA 层面的正面收获:为「降级后 `/products` 是否仍可到达」写的守卫断言**判红是对的** —— 实测移动端底部 TabBar 只有 `['/', '/solutions', '/services', '/insights', '/contact']`, 而抽屉只渲染一级 `mainNav` ⇒ 一级导航去掉「产品」后,手机上到 `/products` 没有任何导航路径。 修法是在抽屉里渲染该轴的 mega 组(复测:抽屉 26 条链接、含 `/products`、二级项 21 个)。 **如果当时把这条断言改成"找不到就跳过",`/products` 会在手机上静默消失。** ### 5.43 `e2e/**/*.ts` 不在 tsconfig include 里:type-check 全绿也加载不了的重复声明 给 UJ-03 teardown 补 revalidate 时写了第二个 `const revalidateSecret`(同作用域内 Step 6 已有一个)。 `npm run type-check` 全程 **EXIT=0**,因为 `e2e/` 不在 include 范围内; 只有真去收集用例时 babel 解析器才报 `Identifier 'revalidateSecret' has already been declared`,**整个 spec 文件无法加载**(不是某条用例红,是整档红)。 ⇒ 改过 e2e 之后,至少跑一次不启服务的解析: ```bash cd e2e && npx playwright test <改动的 spec> --list # Total: N tests in M files 即"能加载" ``` 这条与 §5.38 同属"绿灯的载体没覆盖到那一维":type-check 的范围、管道的退出码, 都会让人把**没测**读成**测过并通过**。 ### 5.44 守卫自己抄了一份令牌值:三个副本、两种病,第三种最隐蔽 本仓「一个语义有多条表示通道」的事故已经记过两次: §5.37(hex 改了 `-rgb` 没改 ⇒ 渲染主通道走没改的那条)、 §5.41(CSS 声明退役而 tailwind 映射没删 ⇒ 僵尸令牌)。 本轮是**第三份副本**:可访问性闸 `scripts/accessibility/axe-node-count.mjs` 把暗色底 **抄成字面量** `EXPECTED_BG = { dark: 'rgb(10, 14, 20)' }`, 而暖色迁移(P1,在本分支基线 `da9a5cb6` **之前**)早已把它变成 `20 18 16` ⇒ 哨兵从此恒红,实测 `bgMismatch=36`,而且红因写的是「底色不等于令牌值 ⇒ 样式未加载」—— **一个失效的哨兵会顺带伪造一句错的诊断**,这比单纯判红更贵。 三条处置纪律: 1. **归因先于修闸**。`git diff da9a5cb6..HEAD -- src/app/globals.css` 里没有任何 `color-bg-primary` 改动 ⇒ 不是本轮引入;再用 `git log -S "rgb(10, 14, 20)"` 定位到 字面量入库的那一笔。没有这一步,很容易把它读成「本批改坏了」。 2. **修法是把副本换成真源,而不是把副本改成新值**。 现从令牌自己取:读 `--color-bg-primary-rgb` 三元组拼期望色。 把字面量改成 `rgb(20, 18, 16)` 只是再抄一遍,下次换色板还会红。 3. **换完必须重做负对照**,证明"没把闸调瞎":临时移走 `dist/standalone/dist/static` 起服务 ⇒ `expected=""`、`actual="rgba(0, 0, 0, 0)"` ⇒ 判红;装配完好 ⇒ `expected` 与 `actual` 都是 `rgb(20, 18, 16)` ⇒ 判绿。脚本存 `docs/acceptance/2026-10-17-ia-e2e/probe-bg-negative.mjs`。 附两条同轮仪器事实:`scripts/**/*.mjs` 不在 `tsconfig` 覆盖内,改完只真跑才暴露 (本轮就是漏改一处 `pageBg` 引用,闸以 `FATAL: 扫描中断(uncaughtException)` 崩掉而非静默通过); 以及闸的退出码分档(0 通过 / 1 判红 / 2 未能度量 + FATAL 独立路径)在这种时刻兑现了价值 —— **崩和"测不到"都不会被读成通过**。 ### 5.44 并行分工下「提交别人在途的文件」会冻结中间态,而提交信息会跟着说谎(2026-10-17) 现象:`1c0ce5f4` 的信息写着「package.json 重复键已由 node 回读校验」,但 `git show HEAD:package.json | grep -c '"type-check:e2e":'` 实取 **2**,且 `test:all` 整条消失。 根因链有两条,都要记: 1. **我在别人还在写它 own 的文件时就 `git add`** ⇒ 提交冻结的是他的中间态,他的终稿留在工作树。 纪律:**别人的在途文件要等该分工的回执再提交**;若必须提交,提交后立刻 用 `git show HEAD:<file>` 复算提交信息里的**每一条**断言(读 HEAD,不是读工作树)。 2. **按子串取行号再删行 = 危险动作**。我的去重命令是 `DUP=$(grep -n 'type-check:e2e' pkg | tail -1 | cut -d: -f1); sed -i "${DUP}d" pkg`—— 而 `test:all` 那一行**也含这个子串**(它引用了该脚本名),于是删掉的是全仓门禁入口。 纪律:改 JSON/YAML 走解析器(或至少按"整行精确匹配 + 键名等值"定位), 永远不要拿 `grep -n` 的行号当地址用;删行前先 `sed -n "<行号>p"` 看一眼要删的是什么。 ### 5.45 校验仪器必须对「它声称检查的那一维」敏感:三层负对照缺一不可 同轮两处自伤,都不是被测对象坏,是**仪器坏**: - 我用 `^ "([a-z0-9:_-]+)":` 数 package.json 的重复键 —— 两空格缩进只匹配**顶层**, 而重复键在 `scripts` 对象里(四空格)⇒ 报 `dups=[]`,对目标那一维根本不敏感, 却让我据此写下了那条不实的提交信息(见 §5.44)。 - `npx jest "src/app/(marketing)/products"` 里 `(` 与 `[` 是**正则元字符**, jest 把位置参数当 testPathPattern ⇒ "No tests found" 的 EXIT=1 被我读成"测试失败"。 修成的仪器 `scripts/check-package-keys.mjs` 现在按 **父路径 + 键名** 分组计数,退出码 0/1/2 三档, 并自带三层对照:正对照(真文件无重复 ⇒ 0)、负对照-同层重复必抓(1)、负对照-异父同名不误报(0); 另在真 `package.json` 上做**活体注入**:加一条重复的 `"lint"` 键 ⇒ `EXIT=1` 且点名 `scripts` 里的 "lint",还原 ⇒ 0。 ⇒ 通用判据(与 §5.42「命中 0 必须配页面健康的正对照」同族): **当"没问题"与"没测到"共用同一个 0/1 时,仪器必须先自证能取到非空样本,并且对目标维度做过一次故意的破坏**。 ### 5.46 车道的编排端口必须读脚本自己的默认约定,不能凭习惯 我把 axe 车道写成 `PORT=3000` 起 standalone,再跑 `check:axe:routes`/`check:axe`, 结果 `AXE_ROUTES=2`(17 条候选路由全不可达 ⇒ 判"清单不可信,不写出")与 `AXE=1` (`ERR_CONNECTION_REFUSED`)。这两个脚本按 CI 约定默认 `BASE=http://localhost:3100`(写在文件头注释里)。 改 `PORT=3100` 后同一条链路 **EXIT=0**(34 路由 ×4 组合、`unexpectedStatus=0`、`non2xxResponses=1` = 期望内的 `/_not-found`)。 值得记的是**这次失败没有骗人**:分母为 0 走 EXIT=2 而不是 0,闸崩溃走 FATAL 而不是静默通过 —— 退出码分档(0 通过 / 1 判红 / 2 未能度量 / FATAL)在这里第二次兑现价值。 纪律:编排脚本前先 `grep -n 'process.env\|BASE\|PORT' <脚本>` 读它自己的默认值。 ### 5.47 看见了红仍然提交:读数的时序 ≠ 门禁的时序(2026-10-17) 我在同一条命令里先算出 `TSC=2`(新测试里一处 `blocked[0]` 在 `noUncheckedIndexedAccess` 下可能 undefined), 接着却照原计划把 commit 与 push 做完,而提交信息里写着「tsc EXIT=0」—— 那是**我打算去修的那个未来状态**,不是这一笔的实测状态。 这是 §5.44(提交信息声称做了没做进去)的变种:**信息引用了尚未成立的读数**。 修法是机械的,不是意志力的:把「测量」和「提交」写进同一条依赖链,红就不可能穿过—— ```bash npx tsc --noEmit > /tmp/tc.log 2>&1; A=$? npx jest <改动面> > /tmp/jt.log 2>&1; B=$? if [ "$A" -eq 0 ] && [ "$B" -eq 0 ]; then git add … && git commit … && git push; else echo NOT_COMMITTING; fi ``` ⇒ 纪律:**任何「我看见了但打算随后修」的红灯,都不允许进入这一笔的提交信息**; 要么先修完再测再提交,要么在信息里显式写成已知红并说明去向。 本地 `pre-commit`(lint-staged)因 `core.hooksPath` 指向主检出而未执行, 所以这道依赖链只能由我来编排 —— 这本身就是 §12.8 记的那条口径的现实后果。 ### 5.48 版式对标不得夹带文案改写(2026-10-20) 拿咨询机构的版式重排首页时,我把 section 标题也一起换成了对标语: 「新闻和最新趋势」「我们为何能够打动客户」「准备好聊聊了吗?」「全部行业」。 用户看到后第一句是「怎么文案变了呢」—— 版式是视觉,标题是品牌文案,二者不是同一层授权。 纪律:**对标只借构图、留白、影像与色彩,不改 CMS 文案、section 标题、CTA 问句与导航标签**。 新增的可见文字必须来自现有页面 / 导航 / CMS 的原文;如果确实需要新文案,先单独提出,不夹带在版式改动里。 本次已全部回退到原站文案,只保留 hero 黑底面板 + 叠图、新闻大图卡、行业影像网格、能力左图右 accordion、 全幅 CTA 与「名 + 号」字标;行业卡上的英文类目标签也一并删除,避免留下第二处新增文案。 ### 5.49 可见性要乘到祖先链;axe 在半透明页面上会成片假红(2026-10-20) 多端复核时,Playwright 在 `reducedMotion: 'reduce'` 下截到整页发灰/发白,axe 报 **101–102 条对比度违规**。 第一反应是「新 hero 的白字压图不过 AA」,但这不是颜色问题:`PageTransition` 的祖先 `motion.div` 停在 `opacity: 0–0.35`,整页被压暗,axe 把每个文字节点都判成低对比度。 两个判据错误叠加才让假红看起来可信: 1. **可见性只读了单节点**:`getComputedStyle(h1).opacity` 恒为 1,祖先链的 0.15 完全看不到; 2. **测量时点落在动画中途**:`goto` 后等 `networkidle + 1.5s` 仍在淡入,截图/axe 读到的是过程态。 修法: - `PageTransition` 在 `mounted` 后始终保留同一个 `motion.div`;reduce 只切零时长、初始即可见的变体, 不再从 motion.div 切回裸 children(那会触发 exit 链,headless 下没有稳定落点)。 - E2E 的可见性判据改为**祖先链 opacity 乘积**,不是单节点。 - 多端探针把 `pageOpacity ≥ 0.99` 作为前置条件;不满足就整轮作废,axe 结果不得引用。 - 先跑「动画落定」再截图/跑 axe:`reducedMotion` 不等于「零动画」,也不等于「已落定」。 ⇒ 通用判据:**当 DOM 祖先可以整体降透明度时,「元素 opacity=1」不构成可见性证明; 仪器必须先证明页面处于终态,再解释对比度。** ### 5.50 AnimatePresence mode="wait" 会让新页永久停在 exit 态(2026-10-20) **现象**:生产环境所有站内跳转白屏,地址栏与标题已变,刷新(冷加载)才正常。 **复现**:production standalone 产物,首页点「关于我们」;`main#main-content` 的父级 motion.div 内联停在 `opacity:0; transform:translateY(-8px)`(exit 变体)且不再变化,祖先链有效 opacity 恒 0。 **机理**:`<AnimatePresence mode="wait">` 要等旧子树的 exit 完成才挂载新子树。App Router 导航期间 本组件会多次重渲染,每次 `children` 引用变化都会让 AnimatePresence 重跑 diff 并把退场完成标记 重置为 false,200ms 后切换 state 的窗口被错过。保留 `exit` 也不能只靠 sync 模式兜底:实测旧 `main` 节点常驻(`mains: 2`),因为注销同样依赖这套 presence bookkeeping。 **修法**:路由内容不再包 AnimatePresence,`<motion.div key={pathname}>` 只保留入场动画 (280ms,令牌层不变);首屏仍由 `mounted` 门控渲染裸 children。不要用「去掉 exit」或 「mode=popLayout」折中——前者留下常驻旧子树,后者留下绝对定位的隐形残影。 **连带修正(同一条因果链)**: - 移除 presence 的 `initial={false}` 上下文后,子树恢复各自入场,屏下的 ScrollReveal 在全页截图时 仍处 opacity:0。视觉用例的「直接跳到底」会跳过中间各屏(IntersectionObserver 只回调当前视口), 改为**逐屏滚动**;视觉全量 125/125。 - 首屏可见性断言改为**逐帧采样**:并行负载下,单点读 h1 会与「水合后子树重挂、入场重新开始」竞争。 **回归守卫**:`e2e/client-navigation-visibility.spec.ts` —— 点页脚链接后等 800ms(退场+入场落定) 再读祖先链乘积;`E2E_TARGET=production` 下四浏览器通过。 ⇒ 通用判据:**跨路由的「等旧页退场再挂新页」不能依赖 framer 的 presence 状态机; 新页面挂载不得以旧页面的动画完成作为前置条件。**