docs(sync): 按 AGENTS.md §6 把本轮五条裁定与三台新闸写回四份文档

- CLAUDE.md:新增 type-check:e2e 与 check:package-keys 两条命令及其存在理由。
- CONTEXT.md 关键决策表:追加 5 行(缓存失效单一真源 / 产品线色相受控例外 /
  动效时长按用途在消费点判 / 案例发布门槛 / e2e 与 scripts 的静态口径)。
- README.md:把「本批遗留待拍/待授权」整句换成 §12 轮的实际处置,含
  DEC-N2 被证伪一事;test:all 的描述由「原文七段」改为现取十段。
- quality-gates.md:新增「§12 轮新增/改写的门禁」表,每行都带自证或负对照读数,
  并写明仍未并入 test:all 的两项与 axe 的 :3100 编排口径。
- package.json:check:package-keys 入 test:all(十段),键唯一性由守卫自证 EXIT=0。
This commit is contained in:
zhangxiang committed 2026-10-17 08:19:10 +08:00
1 parent aa67672a19
commit 11afb2cc9f
5 files changed
+25 -4

No files matched your search

+4
View File
@@ -42,6 +42,10 @@ npm run preview # ALIAS of `start` (identical `next start -p 3000
# Linting & Type Checking
npm run lint # ESLint flat config at repo root (`eslint.config.mjs`; `config/lint/.eslintrc.json` no longer exists)
npm run type-check # tsc --noEmit
npm run type-check:e2e # tsc --noEmit -p e2e/tsconfig.json(DEC-N6:e2e/** 不在根 tsconfig 内,
# 重复声明类错误只有这条能静态抓到)
npm run check:package-keys # JSON 重复键守卫(按父路径+键名;0 无重复 / 1 判红 / 2 未能度量,
# --selftest 三条各测一维)。背景:重复键被后者静默覆盖,不报错也不判红
# E2E Testing (Playwright)
npm run test # 全链路 E2E:先 test:functional(4 功能 project),再 test:visual:all(5 视觉 project),串行以免写库用例与截图并发污染基线
+5
View File
@@ -216,6 +216,11 @@ Novalon 的 6 个核心产品,互为互补关系,常以组合形式出现在
| **承诺单一真源**(commitments) | 一个 `about` 只留一条承诺,散落的 SLA 文案改由 `src/lib/constants/commitments.ts` 派生。历史上存在四条互斥 SLA(`<4小时` / `7×24` / `48小时` / `工作日 2 小时`)+ 一条形似项;现仅保留有授权口径的「工作日 2 小时内回复您的咨询」(basis = target),其余退役 | ✅ 2026-10-17(`src/lib/constants/commitments.ts`)|
| **`/* */` 写在 JSX children 位 = 页面文字** | 合法 JSX,`type-check` / 1747 例单测 / `npm run build` 全绿也不会拦,唯一静态防线是 ESLint `react/jsx-no-comment-textnodes`(error)。⇒ 注释要么进 `{/* */}`,要么移到 JSX 之外;新增此类守卫必须配**敏感性证明**(先断言被污染那段 DOM 真渲染了,再变异确认只有这一条转红)| ✅ 2026-10-17(`docs/lessons-learned.md` §5.39)|
| **移动端二级目的地必须在抽屉里可达** | 一级导航降级任何轴时,移动抽屉必须渲染该轴的 mega 组(`header.tsx` 的 `config.megaDropdown[item.dropdownKey]`),底部 TabBar 不承载二级项。理由:决策二把「产品」退出一级后,实测 TabBar hrefs 只有 `['/','/solutions','/services','/insights','/contact']` 而抽屉只渲染一级 ⇒ `/products` 在手机上**没有任何导航路径**(只剩页脚)。这条由 e2e 可达性守卫判红发现,不是人肉走查 ⇒ **降级动作必须同时验证两个视口的可达性** | ✅ 2026-10-17(qa-tracker §11.5)|
| 缓存失效单一真源 | `src/lib/cms/revalidation.ts`:`planRevalidation`/`pathsForModel` 是纯推导,`revalidateContent` 是变更链唯一出口;HTTP 入口与后台四条链共用同一份映射 | ✅ DEC-N5(草稿不刷、按 status;slug 变更时旧地址一并刷;刷失败不连带 500) |
| 产品线色相(受控例外) | 7 个非品牌 `accentColor` 承担产品线视觉身份,但必须按 **文件 + 色值** 登记在 `check:accents` 判据 B 豁免表内 | ✅ DEC-N1:保留 + 棘轮 `MAX_NON_BRAND_HUES = 7`,第 8 个即判红 |
| 动效时长判据按用途 | 红线只管**入场**;令牌声明不携带用途 ⇒ 判红发生在消费点(非 infinite 且 >700ms) | ✅ DEC-N3(`--transition-gentle` 实测零消费) |
| 案例发布门槛 | 授权 + ≥1 个 `basis===verified` + 禁词扫描,三处共用(成果槽 / CaseStudies / detail-trust) | ✅ DEC-N4;⚠ CMS `caseStudies` schema 尚无这两个字段,业务出案例前须先扩 schema |
| e2e / scripts 静态口径 | `e2e/**` 不在根 tsconfig 内(须 `type-check:e2e`);`scripts/**/*.mjs` 同理,只有真跑才暴露 | ✅ DEC-N6 |
#### 门禁断言的有效性口径(chain6/chain7 新增)
+2 -2
View File
@@ -39,7 +39,7 @@
- [x] **数字口径结构强制(2026-09-20,critique P0 收尾)**:共享数字样式渲染的指标(`metrics`/`outcomes`/`dataProofs`)统一携带 `basis: target|team-history|verified`,渲染端自动附口径角注、未声明保守回落 `target`;CMS 新增 `basis` select 录入字段;删除产品详情页「每一项指标都源自真实客户案例」「经实际场景验证」等虚构佐证并补注角注;`metrics-basis.test.ts` 机械校验声明完整性并拦截虚构佐证禁词
- [x] **五轮系统性 QA 封版(2026-09-21…28 修复,2026-09-30 封版)**:Q-1…Q-10 / S-1…S-24 共 30 处缺陷修复入库(假登出清服务端令牌、登录 IP 限流、停用令牌 fail-closed 收口、workflow 状态+审计交互式 `$transaction` 原子化、编辑器 richtext 防换行静默损毁、`StaggerReveal` 吞网格类致详情页塌成单列、首页 CMS 数组逐条守卫、about/contact/erp-upgrade 补 ISR=3600 等),每处带判别性 RED→GREEN 测试。跨周期台账 `docs/acceptance/qa-tracker.md`(§9 为现行段落),封版判定书与全部原始门禁输出见 `docs/acceptance/2026-09-30-seal/`。**判定 = 封版通过(含例外清单)**:例外为「待业务口径」(4 条互斥 SLA、erp-upgrade 无 basis 数字)与「待授权项」(写库 E2E 11 例、全量变异、生产 `db:seed`、`check:motion` 23 处)——视觉基线追认已于 2026-10-08 闭合,见下条;均非代码质量问题
- [x] **作者侧 agentic 工具化 + 视觉基线闭合(2026-10-08)**:① 选型判定采用 Playwright 1.60 自带 Test Agents(planner/generator/healer,`.claude/agents/*.md` + `.mcp.json`,**未新增依赖、运行期零模型**),淘汰 `tester-army/e2e` 等的判据全表见 `docs/testing/agentic-test-authoring.md`;② 补主导航键盘契约 `e2e/nav-keyboard.spec.ts`(4 例 `@a11y`,dev 10/6、production 10/2、稳定性 24/24,并定性两条引擎/目标差异);③ **AUTH-D3 视觉基线闭合**:写入 38 张(25 新 + 13 覆盖,逐张读图追认)后独立只读复跑 **125/0 / EXIT=0**,取证 `docs/acceptance/2026-10-08-baselines/`;④ 台账 §9 + `docs/lessons-learned.md` §5.33(基线判红须对「采集树 vs 当前树」,本轮内作废了自己一条「运行期漂移」错判)
- [x] **对标语法批:Bain / Porsche Consulting 实测驱动的 UI·UE·UX 重构(2026-10-17,tracer-bullet 一批)**:对标取证不是二手描述——Bain 走 archive.org 快照 2026-08-31(1600×846)绕开 Cloudflare、Porsche 取 live 国际站,逐元素 `getComputedStyle` 抽样。实测**证伪了 ADR-0004 的两条视觉判据**(决策四「关键数字 = 超大字号 + 品牌色」:Bain 成果数字实为 40px / 字重 500 / 纯黑;决策一「4px 色条为辅」:两家都不用颜色给内容分类),已在同一笔里改文档。四项裁定与落地见 [ADR-0008](docs/adr/0008-benchmark-grammar-takeover.md):① **借语法不借色相** —— radius 收进 0–4px 记档 + 新增 `--radius-cta: 0`(CTA 由 pill 改直角)、彩色阴影 `--shadow-brand/-brand-hover/-glow` 退役、`.bain-card` hover 去抬升,**`--radius-full` 保持 9999px**(承载 avatar/switch/slider/radio/progress 的功能性真圆,一并归零即方角化后台所有旋钮);② **一级导航改行业 × 能力 + 洞察双轴**,「产品」退出一级(入口降为能力面板里的产品矩阵总览),且把导航真源**从 DB 行反转为代码**(CMS 行须满足 IA 契约才采纳,否则 fail closed —— 实测复现过「一条自洽的旧行」让页脚各列静默变空);③ **信任层走零编造透明路线**:`ResultsSlot` 可判别空态 + `casePublishBlockers()` 反伪造不变量 + L3 替代信号槽,承诺条款收进 `commitments.ts` 单一真源;④ **范围只到首页 + 一条承载详情页**,其余模板待验收。新增三台可失败仪器并常驻门禁:`check:grammar`(R1–R11,含 R2 正向守卫、R9 双向、R10 递减棘轮、R11 僵尸令牌守卫)、`check:accents`(营销面类名通道,豁免按名登记且**豁免腐化亦判红**)、`check:dead`(import 闭包可达性);`check:visual` 已并入 `test:all` 且**自证先跑**(自证失败即宣布绿灯作废)。证据与台账见 `docs/acceptance/qa-tracker.md` §11、探针 7 份存 `docs/acceptance/2026-10-17-ia-e2e/`;经验教训 `docs/lessons-learned.md` §5.38–§5.41(含「`npm run lint | tail` 吞掉 2 个 error」与「注释写在 JSX children 位会渲染成页面文字,而 type-check/1747 例单测/build 三道全绿」)。**本批遗留待拍/待授权**:视觉基线重采(AUTH-VISUAL)、CMS 导航行改写(AUTH-NAV)、彩色编码第二通道 `hero-themes.accentColor`(DEC-N1,`check:accents` 不覆盖它,口径已印在闸的输出行上)、`StaggerReveal` 默认 stagger 与文档不符(DEC-N2)、`check:motion` 残留 **8 处**(DEC-N3,较 2026-09-30 的 23 处减少,全部经 `git show` 自证为基线 `da9a5cb6` 既有红、非本轮引入)、既有 `CaseStudiesSection`/`detail-trust-section` 无授权门槛(DEC-N4)
- [x] **对标语法批:Bain / Porsche Consulting 实测驱动的 UI·UE·UX 重构(2026-10-17,tracer-bullet 一批)**:对标取证不是二手描述——Bain 走 archive.org 快照 2026-08-31(1600×846)绕开 Cloudflare、Porsche 取 live 国际站,逐元素 `getComputedStyle` 抽样。实测**证伪了 ADR-0004 的两条视觉判据**(决策四「关键数字 = 超大字号 + 品牌色」:Bain 成果数字实为 40px / 字重 500 / 纯黑;决策一「4px 色条为辅」:两家都不用颜色给内容分类),已在同一笔里改文档。四项裁定与落地见 [ADR-0008](docs/adr/0008-benchmark-grammar-takeover.md):① **借语法不借色相** —— radius 收进 0–4px 记档 + 新增 `--radius-cta: 0`(CTA 由 pill 改直角)、彩色阴影 `--shadow-brand/-brand-hover/-glow` 退役、`.bain-card` hover 去抬升,**`--radius-full` 保持 9999px**(承载 avatar/switch/slider/radio/progress 的功能性真圆,一并归零即方角化后台所有旋钮);② **一级导航改行业 × 能力 + 洞察双轴**,「产品」退出一级(入口降为能力面板里的产品矩阵总览),且把导航真源**从 DB 行反转为代码**(CMS 行须满足 IA 契约才采纳,否则 fail closed —— 实测复现过「一条自洽的旧行」让页脚各列静默变空);③ **信任层走零编造透明路线**:`ResultsSlot` 可判别空态 + `casePublishBlockers()` 反伪造不变量 + L3 替代信号槽,承诺条款收进 `commitments.ts` 单一真源;④ **范围只到首页 + 一条承载详情页**,其余模板待验收。新增三台可失败仪器并常驻门禁:`check:grammar`(R1–R11,含 R2 正向守卫、R9 双向、R10 递减棘轮、R11 僵尸令牌守卫)、`check:accents`(营销面类名通道,豁免按名登记且**豁免腐化亦判红**)、`check:dead`(import 闭包可达性);`check:visual` 已并入 `test:all` 且**自证先跑**(自证失败即宣布绿灯作废)。证据与台账见 `docs/acceptance/qa-tracker.md` §11、探针 7 份存 `docs/acceptance/2026-10-17-ia-e2e/`;经验教训 `docs/lessons-learned.md` §5.38–§5.41(含「`npm run lint | tail` 吞掉 2 个 error」与「注释写在 JSX children 位会渲染成页面文字,而 type-check/1747 例单测/build 三道全绿」)。**§12 轮(2026-10-17)对这批待拍的处置**:`DEC-N5` 后台发布/更新/删除已接上缓存失效(新增 `src/lib/cms/revalidation.ts` 单一真源);`DEC-N3` `check:motion` 8 处归零,且时长判据从令牌声明移到消费点;`DEC-N4` 授权+basis 门槛下沉成 `case-publish-gate.ts` 供三处共用(实测门槛下隐藏条目 0 条,属前瞻加固);`DEC-N1` 彩色编码**第二条通道已收进 `check:accents` 判据 B**(产品线色相保留为受控例外:按 文件+色值 登记、棘轮 7、豁免腐化亦判红),落盘即抓到一条绕开真源抄主题的真漂移;`DEC-N6` e2e 进类型口径(`type-check:e2e` 并入 `test:all`)+ `.husky/pre-commit` 索引位 100755 + axe 证据按轮次落盘;**`DEC-N2` 被证伪**:`staggerDelay` 默认一直是 0.05(50ms),`git log -S` 查「0.15」在该文件历史里无任何提交 ⇒ 台账里那个数是叙述抄本而非仪器读数;**AUTH-VISUAL** 基线重采与 `--radius-cta` 负对照的证据落 `docs/acceptance/2026-10-17-final/`;**AUTH-NAV**(CMS navigation 行改写)仍未执行 —— 现行由代码 fail-closed 供数,不改库也能上线。
- [ ] **信任证据补齐·阶段 1/2(待内测/试点客户素材)**:如实披露「共创中/内测中/已交付」三档 + 经授权客户(脱敏);有交付成果后经授权公示可量化结果(零编造原则)——口径字段与 admin 录入口已就绪,待真实数据把 `basis` 从 `target` 升级为 `verified`
## 技术栈
@@ -202,7 +202,7 @@ novalon-website/
| `npm run check:a11y` | 可访问性静态门禁伞:`check:contrast`(令牌对比度,只读 `globals.css`)+ `check:headings`(标题层级,有产物直起 standalone、缺产物才回退 preview)+ `check:brand-token`(双通道红) |
| `npm run check:axe:routes` | 生成全站路由清单:sitemap ∪ 预渲染产物 ∪ 站内链接 BFS → `/tmp/axe-routes.xml`(`scripts/accessibility/crawl-routes.mjs`;退出码 0/2) |
| `npm run check:axe` | 双引擎 × 双主题逐页 axe **节点计数** + 三条规则级通道的分母断言(`scripts/accessibility/axe-node-count.mjs`);退出码 0 通过 / 1 判红 / 2 清单缺失。**需先有 `node dist/standalone/server.js` 在 :3100**;不在 `test:all` 内,CI 由 `Jenkinsfile`「♿♿」阶段(仅 main)执行 |
| `npm run test:all` | 全量门禁检查,`package.json:48` 原文七段:type-check + lint + coverage + **test:integration:real** + check:a11y + fast E2E + security headers;其 E2E 段仍是 dev 目标,GA4 `@critical` 在其中 skipped,需另跑 `test:e2e:prod` |
| `npm run test:all` | 全量门禁检查,现取十段:`type-check` + **`check:package-keys`**(JSON 重复键)+ **`type-check:e2e`**(e2e 静态口径)+ `lint` + `test:coverage` + **`test:integration:real`** + `check:a11y` + `check:visual` + fast E2E + security headers;其 E2E 段仍是 dev 目标,GA4 `@critical` 在其中 skipped,需另跑 `test:e2e:prod` |
| `npm run lighthouse` | 运行 Lighthouse 性能测试 |
## 代码质量门禁
+11
View File
@@ -304,3 +304,14 @@ git commit --no-verify -m "message"
- [Jest文档](https://jestjs.io/)
- [Husky文档](https://typicode.github.io/husky/)
- [lint-staged文档](https://github.com/okonet/lint-staged)
## §12 轮新增/改写的门禁(2026-10-17)
| 门禁 | 命令 | 判据 | 自证 / 负对照 |
|---|---|---|---|
| accent 第二条通道 | `npm run check:accents` | 判据 A 类名通道 + 判据 B(真源 accentColor/accentBg、营销码 `style={{…}}` 色彩属性、页内就地组装 accentColor);豁免按 文件+色值 登记并归一化为 `#rrggbb`;**登记了却命中 0 亦判红**;棘轮 7 | `--selftest` 11 情景、每情景只喂一维且断言另一维违规数为 0(EXIT=0);活体战果 = 抓到 `erp-upgrade-v3` 抄主题 |
| JSON 重复键 | `npm run check:package-keys`(在 `test:all` 内) | 按 父路径+键名 分组;0 无重复 / 1 判红 / 2 未能度量 | `--selftest` 三条各测一维;活体注入重复 `"lint"` ⇒ EXIT=1 点名 `scripts.lint`,还原 ⇒ 0 |
| e2e 类型 | `npm run type-check:e2e`(在 `test:all` 内) | `e2e/**` 静态可解析性 | 注入重复 `const revalidateSecret` ⇒ 老 `type-check` 仍 0、本闸 EXIT=2(TS2451×2);还原 ⇒ 0 |
| 动效约束 | `npm run check:motion` | 时长判据移到**消费点**:非 infinite 的 transition/animation(含 var() 解析)>700ms 判红;写死贝塞尔须走令牌层 | 真树注入三处 ⇒ EXIT=1(4 红);还原 ⇒ 0 |
> 仍未并入 `test:all`:`check:motion` 与全站 axe(`check:axe:routes` → `check:axe`,CI 于 **:3100** 跑)。编排前先读脚本自己的默认端口(`docs/lessons-learned.md` §5.46)。
+3 -2
View File
@@ -46,7 +46,7 @@
"test:e2e:mobile:accessibility": "cd e2e && npx playwright test --grep @mobile.*@accessibility",
"test:mutation": "rm -rf .stryker-tmp && npx stryker run",
"test:mutation:quick": "rm -rf .stryker-tmp && npx stryker run --mutate 'src/lib/utils.ts'",
"test:all": "npm run type-check && npm run type-check:e2e && npm run lint && npm run test:coverage && npm run test:integration:real && npm run check:a11y && npm run check:visual && npm run test:e2e:fast && npm run test:security:headers",
"test:all": "npm run type-check && npm run check:package-keys && npm run type-check:e2e && npm run lint && npm run test:coverage && npm run test:integration:real && npm run check:a11y && npm run check:visual && npm run test:e2e:fast && npm run test:security:headers",
"check:contrast": "tsx scripts/utils/check-color-contrast.ts",
"check:headings": "tsx scripts/utils/check-heading-hierarchy.ts",
"check:brand-token": "tsx scripts/utils/check-brand-text-token.ts",
@@ -75,7 +75,8 @@
"deploy": "bash scripts/deploy.sh deploy",
"deploy:skip-build": "bash scripts/deploy.sh deploy --skip-build",
"deploy:rollback": "bash scripts/deploy.sh rollback",
"deploy:status": "bash scripts/deploy.sh status"
"deploy:status": "bash scripts/deploy.sh status",
"check:package-keys": "node scripts/check-package-keys.mjs"
},
"dependencies": {
"@aws-sdk/client-s3": "^3.1089.0",