From 11afb2cc9f32ab80c6278c4a639ef1759bed8e41 Mon Sep 17 00:00:00 2001 From: zhangxiang Date: Sat, 17 Oct 2026 08:19:10 +0800 Subject: [PATCH] =?UTF-8?q?docs(sync):=20=E6=8C=89=20AGENTS.md=20=C2=A76?= =?UTF-8?q?=20=E6=8A=8A=E6=9C=AC=E8=BD=AE=E4=BA=94=E6=9D=A1=E8=A3=81?= =?UTF-8?q?=E5=AE=9A=E4=B8=8E=E4=B8=89=E5=8F=B0=E6=96=B0=E9=97=B8=E5=86=99?= =?UTF-8?q?=E5=9B=9E=E5=9B=9B=E4=BB=BD=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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。 --- CLAUDE.md | 4 ++++ CONTEXT.md | 5 +++++ README.md | 4 ++-- docs/development/quality-gates.md | 11 +++++++++++ package.json | 5 +++-- 5 files changed, 25 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index cac8c2a..95c9b01 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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),串行以免写库用例与截图并发污染基线 diff --git a/CONTEXT.md b/CONTEXT.md index da5b319..f78d047 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -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 新增) diff --git a/README.md b/README.md index e2e1090..5b2002e 100644 --- a/README.md +++ b/README.md @@ -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 性能测试 | ## 代码质量门禁 diff --git a/docs/development/quality-gates.md b/docs/development/quality-gates.md index b85f533..64e1023 100644 --- a/docs/development/quality-gates.md +++ b/docs/development/quality-gates.md @@ -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)。 diff --git a/package.json b/package.json index f69fb57..bf35fa6 100644 --- a/package.json +++ b/package.json @@ -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",