zhangxiang
03ed066c6c
对齐 novavis AGENTS.md §27，逐项按本仓实测改写，不照抄不存在的命令： - scripts/check-pr-checklist.sh：三种模式（模板结构 / 单 PR 文件 / --pr-dir 扫描） 与退出码 0/1/2 保持同源；模板根改为按脚本自身位置解析并保留 AGENT_PROJECT_DIR 覆写；修上游 --pr-dir 的参数解析缺陷（for arg in "$@" 内 shift 不消费值， 目录会被再当成 PR 文件），改 while+shift - .gitea/PULL_REQUEST_TEMPLATE.md：30 项 checklist 全部换成本仓真实门禁命令 （type-check / lint / test:unit / test:coverage 阈值 / Playwright / visual / check:contrast / check:headings / lighthouse / test:security:headers），并补 CMS 字段-需重跑 seed 声明、:3000 旧预览不作数、暗黑 token、动效 180–280ms、 品牌红触达、数字 basis 口径等本仓专有约束 - 文档同源：docs/development/quality-gates.md 新增「提交与 PR 流程」权威副本 （AGENTS.md 被 .gitignore 排除，不可依赖）、CLAUDE.md 补 Submission Flow 节 门禁自检：脚本 bash -n 通过；11 个用例覆盖三模式 + 缺节/缺文件/子项不足/非 PR 文件/未知选項/--quiet 等负路径，均带正控制以防「匹配零的假绿」。
69 lines
4.8 KiB
Markdown
69 lines
4.8 KiB
Markdown
## 变更摘要
|
||
|
||
简要描述本次 PR 的目的和主要变更（改了哪些页面/组件/API，为什么改）。
|
||
|
||
## 关联 Issue
|
||
|
||
关闭：#
|
||
|
||
> 仅当该 Issue 的验收标准/任务清单已全部完成时才可关闭。无关联 Issue 时填 `N/A` 并说明来源（评审快照、缺陷单等）。
|
||
|
||
## 提交前检查
|
||
|
||
> **硬性要求**：提交 PR 前必须通过 `bash scripts/check-pr-checklist.sh <本描述文件>`，确保模板三节完整且所有 checklist 子项均已勾选。
|
||
> 不适用的子项**仍须勾选**并在行尾注明 `N/A：<理由>`；留空未勾选即视为门禁未过。
|
||
|
||
## 全链路检查
|
||
|
||
跨层变更（页面 ↔ 组件 ↔ CMS 内容模型 ↔ seed ↔ 测试）必须完成以下检查：
|
||
|
||
- [ ] `npm run type-check` 通过（0 error）
|
||
- [ ] `npm run lint` 通过：0 error，且 warning 数未新增（须与改动前基线逐行比对，不接受「本来就有一堆告警」）
|
||
- [ ] 路由/链接真实：本次新增或改动的每个 `href`、`Link` 目标均已确认真实存在，无 `href="#"` 死链、无 404 死路
|
||
- [ ] 涉及 CMS 内容模型：字段定义（`src/lib/cms/content-types.ts`）与 seed 已同步，并已说明**是否需要重跑 `npm run db:seed`**（DB 写入须单独授权，不得静默假定已生效）
|
||
- [ ] 涉及视觉/交互改动：已在**新起的** `next dev`（如 `-p 3001`）上用浏览器复核，未把 :3000 的 `next start` 旧生产预览当作现状
|
||
- [ ] 暗黑模式：新增样式使用语义 token（`bg-bg-*` / `text-ink` / `text-text-*` / `border-border-*`），无裸 `bg-white`、`text-white`、`gray-*` 硬编码
|
||
- [ ] 动效合规：入场时长落在 180–280ms、曲线 `ease-ink` `[0.22, 1, 0.36, 1]`，stagger 步进 ≤ 60ms
|
||
- [ ] 品牌红 `#C41E3A`：每页 ≥ 3 处触达点，覆盖面积 ≤ 10%
|
||
- [ ] 数字与宣称口径：结果型数字带 `basis`（缺失/非法一律按最弱 `target` 处理并自动附角注）；无「源自真实客户案例」「实战验证」等未证实佐证（以 `FORBIDDEN_PROOF_PHRASES` 守卫为准）
|
||
- [ ] 无遗留 `console.log` / `TODO` / `FIXME` / `.only()`
|
||
|
||
## 测试分层检查（L0–L3）
|
||
|
||
> 参考 `docs/testing.md` 与 `docs/testing-guide.md`
|
||
|
||
- [ ] **L0 单元**：新增/修改的工具函数、Hook、CMS 渲染器已补对应 jest 用例
|
||
- [ ] **L1 组件**：新增/修改的 React 组件已覆盖主渲染路径与关键交互（含空态/兜底分支）
|
||
- [ ] **L2 E2E**：涉及关键用户路径（导航、表单、Hero 可见性）的改动已通过 `npm run test:e2e:fast`
|
||
- [ ] **L3 视觉回归**：改了 UI 样式的，已跑 `npm run test:visual`（必要时 `test:visual:update` 并逐张核对 diff，不接受盲更新快照）
|
||
- [ ] 新增机械守卫测试均带**正控制**（构造一个必然命中的样例），杜绝「匹配零」的假绿
|
||
- [ ] 已运行相关测试并全绿，无 `.only()` / 跳过态残留
|
||
|
||
## 质量门禁
|
||
|
||
- [ ] `npm run test:unit` 全部通过
|
||
- [ ] `npm run test:coverage` 通过 `jest.config.js` 的 `coverageThreshold`（global：branches 30% / functions 25% / lines 32% / statements 30%），且**未下调阈值**
|
||
- [ ] `npm run test`（Playwright E2E）全部通过
|
||
- [ ] `npm run check:contrast` 与 `npm run check:headings` 通过（WCAG 2.1 AA）
|
||
- [ ] `npm run lighthouse` 满足 `lhci` 断言（性能/CSP/可访问性预算未回退）
|
||
- [ ] `npm run test:security:headers` 通过（若改动涉及响应头、CSP 或部署配置）
|
||
- [ ] 文档已同步：`README.md` / `CONTEXT.md` / `CLAUDE.md` / `DESIGN.md` / `PRODUCT.md` 及 `docs/` 下受影响文件；代码注释给出决策佐证来源
|
||
- [ ] 提交信息符合 Conventional Commits，且每个 commit 是可独立评审的垂直切片
|
||
- [ ] 破坏性/共享状态动作（seed 重跑、DB 写入、force push、合并、删分支、部署）已单独取得授权，未夹带在常规变更里
|
||
|
||
## 假绿灯纪律
|
||
|
||
> 测试全绿 ≠ 功能可用。以下条目用于区分「验证过了」与「看起来验证过了」。
|
||
|
||
- [ ] 门禁命令**实际执行过**并粘贴真实输出（失败口径如实记录），未以「理论上应该没问题」代替运行
|
||
- [ ] 未通过删测试、放宽断言、`skip`/`todo` 用例、下调阈值等方式让门禁变绿
|
||
- [ ] 未把误报（false positive）当问题「修掉」——若判定为假阳，已记录判定依据与不改的理由
|
||
- [ ] 结论以 `origin/*` 与实测为准，未用本地陈旧 ref（如落后的本地 `dev`）推断分支/历史事实
|
||
- [ ] UI 改动已人工复核关键与边界态；无法复核时已在 PR 中明确写出「未验证项」而非沉默
|
||
|
||
## 其他说明
|
||
|
||
补充截图、性能数据、兼容性说明、未验证项清单，或需要评审者特别关注的事项。
|
||
|
||
> **提交前执行**：`bash scripts/check-pr-checklist.sh` 验证所有 checklist 子项已勾选。
|