动机（Why）

关闭目标项目 Q3 周期最后一个候选待办 T-Q3-04。引入 Playwright 作为前端 E2E 测试框架，补齐测试金字塔顶层。

关键架构决策——Mock API 而非真 Docker Compose：

源仓库 docs/workshop-share.md §四 M9 CI 平台坑点实证清单（PR-G）已把 CNB 坑点外显为治理模式。本 PR 是 M9 首次在目标项目层的"避坑实践"——选型阶段就显式读 M9 并采纳"不重走 F1 弯路"的策略：

这是 M9 首次"消费端"实证：之前方向 F1 4 PR 的代价通过 M9 沉淀为规则，本 PR 的团队直接按 M9 决策树行动——不用重走方向 F1 的 4 PR 弯路。证明 workshop-share.md 作为活文档的规则 ↔ 业务 循环闭环有效。

变更清单（What）

2 个 commits · 7 文件 / +266/-2 行

• commit 1 feat(frontend) 73c2cc7：Playwright E2E 业务接入（7 文件 / +181/-1）
• commit 2 docs(meta) 2b9e3bb：CHECKPOINT §四 轮次 4 档案（1 文件 / +84/-1）

改动 1：Playwright 框架集成

• frontend/package.json：新增 @playwright/test@1.59.1 + 3 个 scripts
  • test:e2e / test:e2e:ui / test:e2e:install
• frontend/playwright.config.ts（46 行）：
  • baseURL: http://localhost:5173（注意：不用 127.0.0.1 —— vite 默认只监听 IPv6 localhost）
  • webServer 机制自动启动 vite dev
  • CI 专属：retries: 2 + list reporter；本地：html + list

改动 2：E2E 4 用例 + Mock API Fixture

frontend/e2e/fixtures/mockApi.ts（约 110 行）——page.route() 拦截 /api/v1/articles*：

• GET 列表（支持 page / pageSize 查询参数）
• POST 创建（自增 id + 时间戳）
• DELETE 删除（幂等，不存在返回 404）
• GET 单条

frontend/e2e/article.spec.ts（约 110 行）——4 个验收标准：

改动 3：CI 守门员 + .cnb.yml 新 stage

• scripts/ci/frontend/check-frontend-e2e.sh（约 45 行）：
  • 幂等跳过（无 playwright.config.ts / frontend/ 时 exit 0）
  • npx playwright install --with-deps chromium（CI 必需）
  • CI=1 npm run test:e2e
• .cnb.yml：push + MR 两段各新增 biz-frontend-e2e stage
  • 镜像：mcr.microsoft.com/playwright:v1.59.1-noble（Playwright 官方预装，含 chromium + OS deps）
  • 不声明 services:[docker]（M9 坑点 1 规避）
  • 对称守门员：push/MR 两段 84/84 行完全一致 ✅

改动 4：vitest 配置修正（意外副作用）

引入 e2e/ 目录后 vitest 默认扫到 e2e/*.spec.ts 并误判为单元测试——立即与 Playwright 语法冲突报错。

修复：

• test.include: src/**/*.{test,spec}.{js,ts,jsx,tsx} —— 只扫 src 单元测试
• test.exclude: e2e/** + playwright.config.ts —— 显式排除
• coverage.include: src/**/*.{ts,vue} —— 只统计业务代码
• coverage.exclude: src/main.ts / src/router/** / src/types/** / src/**/__tests__/** / e2e/**

意外结果：覆盖率从 18%/50% → 20%/58%——之前测试代码把分母拉大，精确化后分母缩小、覆盖率自然前进。棘轮走了一格。

验证证据（How verified）

本地 16/16 CI stages 全绿 + 0 lint

Playwright E2E 本地实测：

Running 4 tests using 4 workers
  ✓  AC-1：列表页加载后应显示预置文章 (1.1s)
  ✓  AC-4：空列表时表格应显示空状态提示 (1.1s)
  ✓  AC-3：点击删除按钮应使文章从列表消失 (1.2s)
  ✓  AC-2：点击新增并提交后新文章应出现在列表 (1.6s)
  4 passed (6.3s)

前端覆盖率（vitest 修配置后）：

    行覆盖: 20%  保底: 18%
    分支覆盖: 58%  保底: 50%
[OK] 前端测试 + 覆盖率棘轮达标

守门员脚本本地真跑：

==> biz-frontend-e2e (Playwright) 门禁检查
    npm ci ... (skipped, node_modules exists)
    playwright install chromium ...
    npm run test:e2e ...
  4 passed (4.3s)
[OK] 前端 E2E 通过

yml 对称性：push + MR 各 1 处 biz-frontend-e2e stage，84/84 行完全一致。

影响面（Impact）

测试金字塔首次完整

目标项目现在拥有完整的三层测试金字塔：

总计 22 个测试用例（首次突破 20）。

M9 治理模式的消费端闭环

这是项目中第 2 次"规则 → 业务"反哺 loop 闭合（第 1 次是 PR-E/PR-F/PR-G 从业务→规则；本 PR 是规则→业务）：

方向 F1（目标项目 PR #4~#7） → 代价
        ↓ 沉淀
源仓库 PR-E（skills/cicd-pipeline CNB 坑点）
        ↓ 升维
源仓库 PR-G（workshop-share §M9 治理模式）
        ↓ 消费（本 PR）
目标项目 PR #8：选 Mock API 避坑，**无新 CI 演化**

这条完整的 loop 证明规则体系在生产可复用的价值。

前端覆盖率棘轮更新建议

当前实测 20%/58% 已高于保底 18%/50%。按棘轮原则（testing-standards §1.3）应上调阈值到实测水平。但本 PR 只补 E2E 不动棘轮——留作下次前端业务迭代时同步上调（scripts/ci/frontend/check-frontend-test.sh 的 LINE_MIN / BRANCH_MIN + vite.config.ts thresholds）。

关闭的待办

• ✅ T-Q3-04：目标项目前端 Playwright E2E 补齐（frontend 覆盖率从 unit-only 扩展到 unit + E2E 两层）

新增待办（可选，规模小）

• T-Q3-07：等 PR #8 远端 CI 验证后，回写"Mock API 策略在目标项目的首次消费实证"到源仓库，作为 M9 的消费端案例补充
• T-Q3-08：后续业务迭代扩展 E2E 用例（搜索 / 分页 / 编辑 / 批量等）

本 PR 不动的事

• 不动 check-frontend-test.sh 的棘轮阈值（留作下次业务迭代时同步上调）
• 不扩展更多 E2E 用例（AC-4 只 CRUD 核心）
• 不改后端（纯前端补强）

Refs

• 父事件：源仓库 PR-G (#46) docs/workshop-share.md §四 M9 治理模式产出
• 关联：
  • CHECKPOINT §四 轮次 4（完整档案）
  • docs/workshop-share.md §四 M9（指导策略的规则）
  • .codebuddy/skills/cicd-pipeline/SKILL.md CNB 坑点清单（使用指引层）
  • 方向 F1 PR #4~#7 演化链（M9 的原始代价）
• 下游：
  • T-Q3-07：回写 M9 消费端案例到源仓库
  • T-Q3-08：后续 E2E 用例扩展