Files
novalon-website/docs/development/quality-gates.md
T
zhangxiang f23500ff07 docs(grammar): 落 ADR-0008 并改掉说谎的那一方,含四条经验教训与台账 §11
对标实测证伪了 ADR-0004 的两条视觉判据,所以本笔的主体是**改文档**:
判据错在文档里,而不是错在代码里,不一起改就是文档变成说谎的那一方。

新增 `docs/adr/0008-benchmark-grammar-takeover.md`(取证方法、实测对照表、
四项裁定、已知偏差 6 条、验证契约):
- Bain 走 archive.org 快照 2026-08-31(1600×846)绕开 Cloudflare,
  Porsche 取 live 国际站 + 中国站导航,逐元素 `getComputedStyle`。
- **被证伪 ①**(决策四)「关键数字 = 超大字号 + 品牌色」:
  Bain 成果数字实测 **40px / 字重 500 / 纯黑**;
  本仓 `--font-size-5xl: 2.25rem` 在桌面根字号 18px 下 = 40.5px ⇒ 现档正好命中,零新增令牌。
- **被证伪 ②**(决策一)「4px 色条为辅」:两家**都不用颜色给内容分类**,
  饱和红用作"面"的次数为 **0**(Bain #CC0000 出现 65 次全是字与线,
  Porsche 红出现 4 次全是按钮)。
  ADR-0004 决策一、决策四两处就地加 ⚠️ 修订块并指向 ADR-0008。
  ADR 不重写历史,但必须让读者不会把已废判据当现状。

`DESIGN.md`:front-matter 的 `rounded:` 改成 0–4px 记档 + 新增 `cta: "0px"`;
`components.cta-*/badge-pill/card-bain/input-field` 的 `rounded` 从
  `{rounded.full}` 改 `{rounded.cta}` 或 `{rounded.md}`,
padding 按实测 `14px 28px`;Elevation 段删掉「hover 升至 card-shadow-hover + translateY(-4px)」;
数据条段把「font-black + 品牌红」改为「text-5xl / 500 / text-ink」并注明是被实测推翻的那条;
Navigation 段写入双轴与「真源是代码、CMS 行须满足 IA 契约才采纳」。

`CONTEXT.md` 关键决策表 +9 行:对标双轴导航 / 导航真源=代码 / 视觉语法记档 /
僵尸令牌 / 彩色编码适用面 / 成果槽 ResultsSlot / 替代信号槽 / 承诺单一真源 /
「注释写在 JSX children 位 = 页面文字」。

`docs/development/quality-gates.md`:
- §1 的 lint warning **权威计数就地更新**:本树 `EXIT=0 / 0 error / 81 warning`,
  分项相加必须等于总数(55+12+8+4+1+1 = 81 ✓),
  并给出与 2026-09-23 那 104 条的逐项对账(`no-explicit-any` 25→4 等,净 −23 ✓)。
  归因**已实证到文件**而不是只看方向一致:逐个 `git show da9a5cb6:<被删文件>` 数出
  33 处 `any` 命中(v15.test 12 / NewsDetailClient.test 8 / v15 4 / …),
  并说明命中数 ≠ 告警数的差额来源,附可复算命令。
- §5.1 `check:motion` 现状 23 处 → **8 处 / 4 文件**,
  并写明残留 8 处全部经 `git show` 自证为基线 `da9a5cb6` 既有红、非本轮引入。
- 新增 §5.2 记录 `check:visual`(R1–R11 每条的分母口径与两条闸的**适用边界**),
  §7 的 `test:all` 组成改为八段并注明自证先跑。
- 另记一条:这条计数一度被读成 0 error,是因为管道吞掉了 EXIT=1(见 §5.38)。

`docs/lessons-learned.md` 四条(§5.38–§5.41)+ 更新记录 4 行:
管道吞退出码复犯 / 合法 JSX 的注释渲染成页面文字而三道门禁全绿 /
仪器只在被复用时才坏(module 层累加器 + 互斥前提塞进同一份夹具)/
僵尸令牌(删了值没删引用,R5 与 R7 各看一侧所以两条都绿)。

`docs/acceptance/qa-tracker.md` §11:四台仪器表(每台的可失败证据)、
本轮 5 条缺陷与根因、6 个 spec 的重锚对照表、
新登记 4 条待拍(DEC-N1 彩色编码第二通道 / N2 stagger 默认值 /
N3 motion 残留 8 处 / N4 既有案例区无门槛)+ 2 条待授权(AUTH-VISUAL / AUTH-NAV)。

`config/test/lighthouserc.json`:URL 集补 `/insights`(新的一级轴)与
`/solutions/manufacturing`(本批 tracer-bullet 承载页)——
不补就是新页没有任何 Lighthouse 覆盖。

`README.md`:加本批进度条目,并把「check:motion 仍 23 处」的旧数改为指向
quality-gates §5.1 的现取口径。

探针 7 份入库 `docs/acceptance/2026-10-17-ia-e2e/`(导航结构 / 面板链接 /
首页 testid 与文案 / 段序文档坐标 / 页脚入口),是本批所有 E2E 断言的取证来源。

本笔纯文档 + 配置,不改运行时代码;同树已跑过的验证仍成立:
`npm run test:all` EXIT=0、`type-check` EXIT=0、`lint` EXIT=0(0/81)、
`test:unit` 141 套件 / 1747 例、`check:visual` 11/11 + accents 成立、`build` EXIT=0。
2026-10-17 01:08:45 +08:00

307 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 代码质量门禁
## 概述
项目配置了自动化质量门禁,确保代码提交前通过所有质量检查。
## 质量检查
### 1. 代码风格检查
**工具**: ESLint(flat config:`eslint.config.mjs`)
**检查时机**:
- pre-commit hook:`.husky/pre-commit` → `npx lint-staged` → `.lintstagedrc.json` 仅对 `*.{js,jsx,ts,tsx}` 执行 `eslint --fix`
- `npm run lint`(全仓)、`npm run test:all`
- CI「🔍 代码质量检查」阶段(`Jenkinsfile`)
**检查内容**:
- 代码语法错误
- 代码风格规范
- 自动可修复项的格式化(仅暂存文件,pre-commit 阶段)
**通过标准**: **0 error**。warning **不判红**——这是本项目的显式裁定(见 `CONTEXT.md`「lint warning 分级与门禁判定口径」);把 warning 清零不是门禁前置条件,但**不得**为凑绿而把它们调成 `off`。
**warning 数量口径(本文件为版本库内的权威记录位)**:
> **2026-10-17 本树复测(对标语法批,分支 `worktree-ui-grammar-two-axis`)**:`npm run lint` ⇒ **EXIT=0,`✖ 81 problems (0 errors, 81 warnings)`**。
> 分项相加必须 = 总数,口径自洽才算这条记录可信:**55** `no-console` / **12** `react-hooks/set-state-in-effect` / **8** `@next/next/no-img-element` /
> **4** `@typescript-eslint/no-explicit-any` / 各 1 `@next/next/no-sync-scripts`、`@next/next/no-html-link-for-pages`(55+12+8+4+1+1 = 81 ✓)。
> 与下行 2026-09-23 的 104 相差 **−23**,按规则逐项对账为:`no-explicit-any` **25→4(−21)**、`Unused eslint-disable directive` **1→0(−1)**、
> `@next/next/no-img-element` **10→8(−2)**、`set-state-in-effect` **11→12(+1)**、`no-console` **55→55(0)**(−21−1−2+1 = −23 ✓)。
> 归因**已实证到文件**(不是只看方向一致):`da9a5cb6` 时被删掉的文件里 `: any` / `as any` / `<any>` 命中数为
> `home-content-v15.test.tsx` 12、`NewsDetailClient.test.tsx` 8、`home-content-v15.tsx` 4、`insight-card.test.tsx` 3、
> `industry-grid.test.tsx` 2、`hero-particle-field.test.tsx` 2、`case-card.test.tsx` 2(合计 33 处命中 ⇒ 净减 21 条 warning,
> 差额是因为命中数 ≠ 告警数:泛型实参、注释里的 `any` 不产生该告警)。复算命令:
> `for f in $(git diff --diff-filter=D --name-only <base>..HEAD | grep -E '\.tsx?$'); do git show <base>:"$f" | grep -cE '(: any|as any|<any>)'; done`
> 另记一条本轮真实事故:这条计数一度被读成 0 error 是因为 `npm run lint | tail` 拿到的是 `tail` 的退出码,
> 而当时真实输出是 **2 error / EXIT=1**(`react/jsx-no-comment-textnodes` 两处)⇒ 见 `docs/lessons-learned.md` §5.38,
> **门禁命令必须重定向到文件后再读 `$?`**:
```bash
npm run lint # 看末行 ✖ N problems
npm run lint 2>&1 | grep -oE '[a-z@/_-]+/[a-z-]+$' | sort | uniq -c | sort -rn # 分项
```
> ⚠ 不要再以 `AGENTS.md` §5 为该数字的出处:`AGENTS.md` 被 `.gitignore` 有意排除、从未被 git 跟踪、并由 `next dev` 再生(验收 N-16),其内容不可审、不可回滚、可能随再生丢失,只当本地便签。
**已知例外(须保留原因)**:`eslint.config.mjs` 的按路径 override 只在三类位置降档——`ruixin/e2e-tests`(`e2e/**/*.ts` 关 `no-console`,`:65-71`)、`ruixin/unit-tests`(`**/*.test.{ts,tsx}`、`**/__tests__/**` 关 `@typescript-eslint/no-explicit-any`,`:73-79`)、`ruixin/performance-tests`(`tests/performance/*.js`,`:81`)。**`prisma/seed.ts` 不在任何 override 内**,它的 `no-console` 仍是 warning 形态存在(占 §5 计数的大头),属「种子脚本进度日志」的有意容忍项,而非配置豁免(其数量口径见本节上方的 warning 分项表)。
### 2. 提交信息规范
**工具**: commitlint
**检查时机**: commit-msg hook
**检查内容**:
- 提交信息格式
- 提交类型合法性
**通过标准**: 符合Conventional Commits规范
**提交类型**:
- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 重构
- `perf`: 性能优化
- `test`: 测试相关
- `chore`: 构建/工具相关
- `revert`: 回滚提交
- `build`: 构建相关
- `ci`: CI/CD相关
**提交信息格式**:
```
<type>(<scope>): <subject>
<body>
<footer>
```
**示例**:
```
feat(auth): add JWT authentication
Implement JWT-based authentication with:
- Token generation
- Token validation
- Refresh token mechanism
Closes #123
```
### 3. 代码覆盖率检查
**工具**: Jest
**检查时机**: 手动运行或CI/CD
**检查内容**:
- 单元测试覆盖率
- 分支覆盖率
- 函数覆盖率
- 行覆盖率
- 语句覆盖率
**通过标准**(阈值单一真源:`config/test/jest.config.js` 的 `coverageThreshold`,根 `jest.config.js` 仅转发):
- 全局: statements / lines / functions ≥ 75%,branches ≥ 82%
- 目录级棘轮按各目录实测值下调 3–5 个点设定,只允许上调
- **实测值的权威记录位就是本节**(`README.md` / `CLAUDE.md` 不再复制百分比,只指向这里;`config/test/jest.config.js` 顶部注释只是写死的快照,会滞后于树,见下方告警)
- 实测(**2026-09-23 本树复跑** `npm run test:coverage` ⇒ **134 suites / 1697 tests,`EXIT=0`、0 条 threshold 告警**):
statements 85.66% / branches 87.49% / functions 80.67% / lines 85.66%
- 目录级:`components/content` 100×4 · `components/sections` 73.69 / 90.71 / 73.8 / 73.69 · `lib/cms` 91.93 / 92.77 / 92.68 / 91.93
- ⚠ 全局实测已高出门限 5.67–10.66 个点 ⇒ 棘轮当前**偏松**(未达本文件自订的「实测 −3~5pp」)。上调是独立动作,须单列提交,不夹带功能变更
- ⚠ `config/test/jest.config.js:28-29` 的注释把 **85.56 / 86.86 / 80.59 / 85.56** 与 `components/sections` 的 87.06 挂在「134 suites / 1697 tests」名下,属**跨轮错配**:85.56 那一组属于更早的 **132 suites / 1677 tests** 树(见 `docs/acceptance/2026-09-23-gates/final-verdict.md` §1),134/1697 轮次当时的全局值是 85.59 / 87.5 / 80.67 / 85.59(同文件 N-31④)。该文件不在本次修订范围内,故此处以注释纠偏说明代替改码;引用覆盖率时**以上述本树复跑值为准**,并同时给出复算命令:`npm run test:coverage 2>&1 | grep -E "All files|Test Suites:|^Tests:"`
### 4. 类型检查
**工具**: TypeScript(`tsc --noEmit`)
**检查时机**: `npm run type-check`、`npm run test:all`、CI「🔍 代码质量检查 → TypeScript」阶段。**不在 pre-commit**——`.lintstagedrc.json` 只跑 `eslint --fix`,故本地提交不会拦下类型错误,推送前须自行跑 `type-check`。
**检查内容**:
- 类型错误
- 类型推断
**通过标准**: 无类型错误
### 5. 可访问性静态门禁(`check:a11y`)
**工具**: 三个自研 tsx 脚本(`package.json` 的 `check:a11y` 串起三者;`Jenkinsfile`「♿ 可访问性门禁」阶段逐条调用同一组,全分支执行)
| 脚本 | 命令 | 输入源 | 断言 |
|---|---|---|---|
| 令牌对比度 | `npm run check:contrast` | **只读** `src/app/globals.css` 的两主题令牌表(`scripts/utils/check-color-contrast.ts:175`),不启服务 | 声明的令牌配对(含 alpha 组、暗色)达 AA;缺令牌即红,不允许静默跳过 |
| 标题层级 | `npm run check:headings` | 存在 `dist/standalone/server.js` 时**直起 standalone**,产物缺失才回退自起 `npm run preview` 并打印告警(`scripts/utils/check-heading-hierarchy.ts:52-67`,验收 N-24③),随后 HTTP 抓渲染页 | 每页恰好 1 个 h1、层级不跳跃、无空标题;进程组回收见 `docs/lessons-learned.md` §5.23 |
| 双通道红 | `npm run check:brand-token` | 静态扫描 `src` 源码 | 品牌红**文字**必须走 `text-brand-ink*`,禁 `text-[var(--color-brand)]` |
**通过标准**: 三条全绿。**已知测不到的面**:axe 与 `check:contrast` 都忽略 `:hover`,所以半透明 hover 底色要手工合成算对比度(`CONTEXT.md`「品牌色令牌的语义拆分」);「计数 = 0」型门禁必须同时断言分母(`CONTEXT.md`「门禁断言的有效性口径」)。
#### 5.1 动效契约门禁 `npm run check:motion`(N-29 的收口,**尚未并入 `check:a11y`**)
验收 N-29(`docs/acceptance/2026-09-23-gates/final-verdict.md` §3)记录:`check:a11y` 只等于 contrast + headings + brand-token,「没有任何脚本约束时长与缓动曲线」,而 `CONTEXT.md:73-85`「动效设计四原则」是有出处的硬约束。`scripts/utils/check-motion-constraints.ts` 把它变成可判定门禁:
| 规则 | 断言 | 出处 |
|---|---|---|
| R1 `token-band` | `--transition-instant` == 100ms(反馈档);`--transition-fast` / `--transition-normal` ∈ 180–280ms(入场档,令牌名由原文点名) | `CONTEXT.md:76` |
| R2 `entrance-cap` | 一切**动效时长** ≤ 700ms:CSS `transition*:` / `animation*:` 声明值(含经 `var(--transition-*)` 解析后的值)、framer-motion `transition` 对象内的 `duration: <秒>`、Tailwind `duration-NNN`(裸数字按 ms 计)、`tailwind.config.js` 的 `animation` 简写串。豁免:`infinite` 循环动画、`*-delay`(延迟属 `:78` stagger 口径,不判) | `CONTEXT.md:82` |
| R3 `css-transition-token` | transition 声明的时长必须走 `var(--transition-*)`,裸 ms/s 字面量与悬空 `var()` 引用均判红(豁免 `prefers-reduced-motion` 的 `!important` 硬开关) | `CONTEXT.md:76` |
| R4 `easing-palette` | 写死的贝塞尔曲线必须等于令牌层已声明的某条 —— **允许集合从 CSS `--ease-*` 声明里解析,不在脚本里硬编码**;另钉住基准 `--ease-ink == [0.22, 1, 0.36, 1]` | `CONTEXT.md:77` |
**退出码**:0 无违规 / 1 有违规 / **2 未能度量**(目标目录或令牌文件缺失、扫到的源码文件数为 0、`--ease-*` 或 `--transition-*` 一个都没解析到)。摘要行始终打印分母(扫描文件数 / CSS 声明数 / 时长字面量数 / 贝塞尔字面量数),**空扫描绝不读作干净** —— 这是 N-22 / N-24 / A-6「永不可失败的门禁」的直接防线。无 `warn` 代替 `fail` 的分支。
**自证伪**:`npm run check:motion:test`(19 例,`scripts/utils/__tests__/check-motion-constraints.test.ts`)对每条规则做**双向**断言 —— 合规夹具判 0(防常红)+ 违规夹具判该规则红(防常绿),并含一条元测试:四条规则的触发集合必须恰好等于 `MOTION_RULES` 声明的全集(任一规则变得不可触发即红)。该测试跑在 `scripts/` 下,故需 `--roots` 显式指定(jest 默认 `roots` 是 `src`),不在 `test:unit` / `test:coverage` 的口径内。
**当前树状态(2026-10-17 本树复测)**:`npm run check:motion` → **EXIT=1,8 处违规 / 4 个文件**(R1 token-band 0、R2 entrance-cap 1、R3 css-transition-token 1、R4 easing-palette 6;分母 = 252 个源码文件 · 46 条 CSS 声明 · 251 个时长字面量 · 51 条贝塞尔字面量 · 7 个 `--transition-*` 令牌 · 6 个 `--ease-*` 令牌)。较 2026-09-30 的 23 处减少,是因为本轮删掉了不可达模块与 `design-system.ts`(其裸时长字面量随文件消失)、并给 `--transition-hover` 补了档;**残留 8 处全部是基线 `da9a5cb6` 就有的红**(`git show da9a5cb6:src/app/globals.css` 里 `--transition-gentle: 1000ms` 与 `transition: opacity 0.6s` 两处可自证),非本轮引入:`[0.16, 1, 0.3, 1]`(`template.tsx` ×2、`brand-visuals.tsx` ×2)与 `[0.25, 1, 0.5, 1]`(`page-transition.tsx` ×2)四条未在令牌层声明的曲线 + `--transition-gentle: 1000ms` 超 700ms 入场上限 + `globals.css:1481` 的 `0.6s` 裸字面量。登记为 `docs/acceptance/qa-tracker.md` §11.4 DEC-N3。因此**本轮只登记独立脚本、不并入 `check:a11y`**(并入即把伞下门禁做成永久红);违规修完后把 `check:motion` 追加进 `package.json` 的 `check:a11y` 串即可,规则本身不得为转绿而放宽。
#### 5.2 视觉语法与彩色编码门禁 `npm run check:visual`(2026-10-17 新增,已并入 `test:all`)
出处:对标实测(Bain archive 快照 2026-08-31 + Porsche Consulting live,`getComputedStyle` 抽样)
与 [ADR-0008](../adr/0008-benchmark-grammar-takeover.md)。两条闸都是**先自证再判分**:
自证失败即宣布「上面所有绿灯不作数」并以 EXIT=1 结束,防止一台坏仪器给出连贯却无意义的绿灯。
| 脚本 | 判据 | 分母口径 | 退出码 |
|------|------|---------|--------|
| `scripts/check-visual-grammar.mjs` | R1 radius 记档 0–4px · R2 `--radius-full` 仍为真圆(**正向守卫**,防「一并归零」把 avatar/switch/slider/radio/progress/scroll-area 全方角化)· R3 `--radius-cta` 存在且为 0 · R4 CTA/badge 表面零 `rounded-full` · R5 彩色阴影令牌已退役 · R6 `.bain-card` hover 无位移抬升 · R7 业务代码零彩色阴影消费 · R8 组件级圆角令牌落进记档(补 R4 的令牌路径盲区)· R9 按钮尺寸档直角 + `icon` 档保持圆(**双向**)· R10 hover 抬升数 ≤ 登记上限(**递减棘轮**,变少不判红但把下调提示写进 note)· R11 tailwind 映射的 `var(--*)` 必须在 `globals.css` 有声明(**僵尸令牌守卫**) | 每条规则各报自己的分母;**分母为 0 = 判据没有目标 = 未能度量(EXIT=2),不算通过**。唯一例外是 R7:它的分母是「仍在消费彩色阴影的文件数」,0 表示已清零(成立) | 0 成立 / 1 判红 / 2 未能度量 |
| `scripts/check-accents.mjs` | 营销面(`src/**` 排除测试与 `_archive`)不得出现 `accent-*` 类彩色编码 | 扫描源文件数;命中数与命中文件数一并打印 | 0 成立 / 1 判红(含**豁免腐化**:按名登记的豁免文件命中变 0 亦判红)/ 2 未能度量 |
**两条闸各自的口径边界(必须读,否则会把它当成"视觉已达标")**:
1. `check:accents` **只覆盖 Tailwind 类名通道**。第二条彩色编码通道是
`src/lib/constants/hero-themes.ts` 的 `accentColor`,它以内联样式进
`src/components/detail/detail-hero.tsx:81-86`(`backgroundColor` / `color` / `borderColor` / `--badge-accent`)。
实测 11 个主题里 **7 个用非品牌色相**(erp `#1e3a5f`、crm `#1e40af`、bi `#0c4a6e`、cms `#14532d`、
sds `#78350f`、oa `#4c1d95`、novavis `#0f3d3e`),落在产品·方案·服务详情页 hero 徽章上。
该闸的成功输出行已把这层边界印在屏幕上,判据措辞与被验的那一维保持一致
(登记于 `docs/acceptance/qa-tracker.md` §11.4 DEC-N1,待设计裁定)。
2. R10 是**存量棘轮**不是"已合规":28 处 / 19 文件的 `hover:-translate-y` 仍在,
本批只保证它不再增长。全站清账属于模板批。
**自证的可失败性证据(本轮实测)**:
- `check:grammar:selftest` ⇒ R1–R9 对已知违规全部判红(9/9);R10 在 28 处不判红、29 处判红;R11 抓到未声明引用且不误报已声明引用。
- R11 的**负对照已在真树上执行**:把 `boxShadow.brand/'glow'` 两行映射塞回 `tailwind.config.js` ⇒ `EXIT=1`、报出 2 条悬空;还原 ⇒ 11/11 成立。探针与读数存 `docs/acceptance/2026-10-17-ia-e2e/`。
- `check:accents:selftest` ⇒ 三个情景**各测一维**(违规 / 豁免腐化 / 全绿)。写成一份夹具是不行的:「营销面有违规」与「三条豁免都有命中」互斥,塞进同一份数据会让腐化那一维永远为假。
**为什么自证必须先跑**:本轮真实踩到 `checkGrammar` 把 `results` 累加器挂在 module 层,
第二次调用往同一数组追加、`.find("R10")` 取到第一次读数 ⇒ 主流程只调一次所以毫无症状
(`docs/lessons-learned.md` §5.40)。
**已接地的动态 axe 门禁(2026-09-23)**:`check:axe` / `check:axe:routes` 的脚本已落到常驻位置 `scripts/accessibility/{axe-node-count,crawl-routes}.mjs`(原 `docs/acceptance/2026-09-21-axe/` 的一次性 harness 平移而来,证据 JSON 仍留原目录,最终树 34 路由 × 4 组合 `passed=true`)。判定从「打印 PASSED」升级为**退出码**:0 通过 / 1 判红(任一引擎×主题组合的 violation 节点 > 0、主题或底色不匹配、三条规则级规则的分母不闭合、扫描中断)/ 2 清单缺失或解析出 0 条。CI 接线在 `Jenkinsfile`「♿♿ 全站 axe 节点计数」阶段(仅 main,复用上一阶段的 `dist/standalone`,按 `node dist/standalone/server.js` 起服务,`set -e`、无 `|| echo`),因此它是**真实的自动化门禁**而非可选脚本;但它不在 `check:a11y` / `test:all` 伞下(那三条是零服务依赖的静态检查,axe 轮需要生产服务与两个浏览器引擎)。复跑口径与静态资源装配要求见 `docs/testing.md`「axe 全站节点计数门禁(验收 §8-⑤)」一节。
### 6. E2E 目标口径(dev 与产物不是一回事)
| 命令 | webServer | 覆盖含义 |
|---|---|---|
| `npm run test` / `test:functional` / `test:e2e` | `npm run dev` | 日常回归。**GA4 的 4 个 `@critical` 用例 × 4 project = 16 个实例是 skipped**(GA ID 只在 `.env.production`,dev 下不注入 gtag,`test.skip` 触发)。证据 `docs/acceptance/2026-09-21-gates/skipped-tests-final-tree.json` |
| `npm run test:e2e:prod` | `E2E_TARGET=production` ⇒ `HOSTNAME=localhost PORT=3000 node dist/standalone/server.js`(`e2e/playwright.config.ts:132-135`) | **唯一**真正断言 GA4(生产响应头不在此集合,属 `@security`)/ 预渲染与 ISR 的口径;用例集是 `@smoke\|@critical\|@journey` × 4 project,`reuseExistingServer` 在此目标下为 false(`:139`)。产物是 `output: 'standalone'`(`next.config.mjs:44`),Next 16 下 `next start` 明确不受支持,故不能写成 `npm run start`;harness 不代跑构建,须先 `npm run build` 并按 `Jenkinsfile:353-355` 把 `dist/static` 与 `public` 拷进 `dist/standalone/`(standalone 不自含这两者,缺了 `/_next/static/**` 全 404) |
| `Jenkinsfile`「🌐 E2E 测试」(仅 main) | build + `test:e2e:prod` | CI 在 main 上执行产物口径;功能分支本地跑 `npm run test` 不覆盖它 |
**结论**:以 `npm run test` 的绿灯宣称"GA4/生产头已验证"属口径错误;引用时必须指明目标。
#### 6.1 产物口径的三条实操陷阱(2026-09-30 封版轮在 `a0328a6` 上实测)
1. **`test:e2e:prod` 默认集合会写真库**:它的 grep 是 `@smoke|@critical|@journey`,**不排除** `e2e/cms-workflow.spec.ts`(`@critical`)与 `e2e/user-journey.spec.ts`(`@journey`),二者对 `/api/admin/items|media` 发真实写请求 ⇒ "prod" 不等于"只读安全"。要拿写库-free 凭据必须自己加:
`--grep-invert 'cms-workflow\.spec\.ts|user-journey\.spec\.ts'`(`--grep-invert` 匹配的是含**文件路径**的 title path,先 `--list` 自证排除生效再实跑)。封版树实测:排除后 **92 例 → 91 passed / 1 failed**,`prisma/dev.db` 的 inode/size/mtime 跑前后完全一致。唯一红是 `[firefox] uj-09:124` 的并发墙钟(隔离与 4-project 复跑均绿),已登记 `docs/acceptance/qa-tracker.md` §2.4。
2. **视觉比对必须显式关写入**:**不带 `--update-snapshots` 旗标**时 Playwright 取 `missing`(`node_modules/playwright/lib/common/index.js:584`),会**静默创建**缺失参照;而**裸 `--update-snapshots`(带旗标不带值)取 `changed`**(`node_modules/playwright/lib/program.js:202` 的 `preset: "changed"`),只写「缺失 / 比对不符」两种,**不会重写通过的参照**——所以「覆盖了多少张」可以直接当作「判红多少张」。只读比对必须显式写 `--update-snapshots=none`,并先确认 `:3000` 无残留服务(`reuseExistingServer` 在 dev 目标下为 true,会静默复用旧构建)。**读数口径**:`--update-snapshots=none` 在封版树(2026-09-30)实测 **94 passed / 31 failed**(20 例缺参照 + 11 例已过时,归因见 `docs/acceptance/2026-09-30-seal/final-verdict.md` §2.2);AUTH-D3 于 **2026-10-08 闭合**(写入 38 张 = 25 新 + 13 覆盖;**38 是文件数、31 是用例数**,一例可多 shot),随后独立只读复跑 **125 passed / 0 failed / EXIT=0**,取证见 `docs/acceptance/2026-10-08-baselines/`。**判红归因的参照系是「基线采集树 vs 当前树」**(`git log -1 -- <参照路径>` 现取采集树),「本轮相对上一轮零源码改动」只支撑绿灯平移、不支撑参照同源——详见 `docs/lessons-learned.md` §5.33。
3. **安全头不必打线上**:`scripts/utils/check-security-headers.ts:28-35` 支持 `--url`,因此可以对着本分支产物跑(`--url http://localhost:3100/` ⇒ 实测 7 PASS / 1 WARN / 0 FAIL,WARN 是 HSTS,由 nginx/CDN 边缘注入,http 目标本就不下发)。只有 `test:all` 的默认值指向 `https://novalon.cn`,那条在分支产物上结构上不可能全绿,两者不可混用。
### 7. 一键门禁 `npm run test:all`
`type-check` → `lint` → `test:coverage` → **`test:integration:real`** → **`check:a11y`** → **`check:visual`** → `test:e2e:fast` → `test:security:headers`(`package.json` 的 `test:all` 原文即此八段,勿凭记忆省略 `test:integration:real`。2026-10-17 新增 `check:visual` = `check:grammar:selftest` → `check:grammar` → `check:accents:selftest` → `check:accents`,**自证先跑**:自证失败的闸不许用它的绿灯出结论。见 §5.2)。注意最后一项 E2E 仍是 **dev 目标**(`@smoke|@critical`),GA4 的 16 个实例同样 skipped,故 `test:all` 绿之后仍需按 §6 补 `test:e2e:prod`。
## 提交与 PR 流程(PR-First)
`dev` / `main` 只接收来自功能分支的 PR,执行顺序固定:**同步 dev → rebase → push → PR 门禁 → rebase 合并**。
```bash
git fetch origin dev && git rebase origin/dev # 必须以 origin/dev 为准,本地 dev 可能已陈旧
git push -u origin <feature-branch> # rebase 改写哈希后仅用 --force-with-lease,禁裸 --force
bash scripts/check-pr-checklist.sh <PR描述文件> # 未通过不得创建 PR
```
- PR 模板:`.gitea/PULL_REQUEST_TEMPLATE.md`(三节:全链路检查 / 测试分层检查 / 质量门禁)。
- 门禁校验:模板三节完整 + checklist 子项 ≥ 20 + 描述文件所有子项已勾选;不适用项**仍须勾选**并注明 `N/A:理由`。
- 功能分支合并方式统一选 Gitea 的 **Rebase**(保持线性历史),不选 Create merge commit。
- 破坏性/共享状态动作(seed 重跑、DB 写入、force push、合并、删分支、部署)须单独取得授权,不夹带在常规变更里。
> 注:`AGENTS.md` 被 `.gitignore` 排除(由 `next dev` 再生),本节是该流程在版本库中的权威副本。
## 如何绕过质量门禁
⚠️ **警告**: 仅在紧急情况下绕过质量门禁
### 绕过pre-commit hook
```bash
git commit --no-verify -m "message"
```
### 绕过commit-msg hook
```bash
git commit --no-verify -m "message"
```
### 绕过所有hooks
```bash
git commit --no-verify -m "message"
```
## 故障排查
### ESLint错误
**问题**: pre-commit hook因ESLint错误失败
**解决方案**:
1. 查看错误详情
2. 修复代码或配置
3. 运行 `npm run lint` 检查
4. 重新提交
### commitlint错误
**问题**: commit-msg hook因提交信息格式错误失败
**解决方案**:
1. 检查提交信息格式
2. 使用正确的提交类型
3. 重新提交
### 覆盖率不达标
**问题**: 覆盖率检查失败
**解决方案**:
1. 查看覆盖率报告
2. 补充测试用例
3. 重新提交
## 持续改进
### 提高覆盖率阈值
随着项目发展,逐步提高覆盖率阈值(棘轮只允许上调,调整前须附 `npm run test:coverage` 实测值):
- 当前(2026-09-21): 全局 statements 75% / branches 82%
- 下一阶段目标: 全局 statements 80% / branches 85%
### 添加更多质量检查
未来可以添加:
- 复杂度检查
- 重复代码检查
- 安全漏洞扫描
- 依赖漏洞检查
## 参考资料
- [Conventional Commits](https://www.conventionalcommits.org/)
- [ESLint文档](https://eslint.org/)
- [Jest文档](https://jestjs.io/)
- [Husky文档](https://typicode.github.io/husky/)
- [lint-staged文档](https://github.com/okonet/lint-staged)