diff --git a/docs/superpowers/plans/2026-09-15-frontend-quality.md b/docs/superpowers/plans/2026-09-15-frontend-quality.md new file mode 100644 index 0000000..35d6420 --- /dev/null +++ b/docs/superpowers/plans/2026-09-15-frontend-quality.md @@ -0,0 +1,1185 @@ +# 前端工程质量（④）实现计划 / Frontend engineering quality implementation plan + +> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。 + +**目标：** 按 spec `docs/superpowers/specs/2026-09-15-frontend-quality-design.md` 落地四批次前端基建：ESLint+Prettier（全库 0 error）、组件测试基建（jsdom + testing-library + 3 样板）、Playwright e2e（dev 栈手动门禁 + axe 扫描）、bundle 分析（visualizer + 书面结论）。 + +**架构：** 全部改动限于 `frontend/`（外加 `.github/workflows/e2e.yml`、`docs/bundle-review.md`、`docs/README*.md`、`docs/CHANGELOG_web.md`）。四批次依序：B1 lint/format → B2 组件测试 → B3 e2e+axe → B4 bundle。每批结束 `npm run check` 必须绿。 + +**技术栈：** ESLint 9 flat config、typescript-eslint、eslint-plugin-react-hooks、eslint-plugin-jsx-a11y、Prettier、vitest 5 projects、@testing-library/react、jsdom、@playwright/test、@axe-core/playwright、rollup-plugin-visualizer。 + +**实施分支：** `feat/frontend-quality`（从 master 建；设计文档已在 `docs/frontend-quality-spec` 分支，实施前先合回 master 或直接 cherry-pick spec commit，由用户定）。**master 上不 commit。** + +**前置条件（每个涉及安装/运行的任务都依赖）：** dev 栈已起：`docker compose -f deploy/docker-compose.dev.yml up -d --build`（在仓库根执行；下文简写 `docker compose -f dev up`）。所有 npm 依赖安装在 web 容器内（`node_modules` 是匿名卷，宿主直接 npm install 无效）： + +```bash +# 仓库根执行，下文简写「容器内 npm …」 +docker compose -f deploy/docker-compose.dev.yml exec web npm +``` + +**changelog 规则（AGENTS.md）：** 本期全部是 `frontend/` 改动 → 只记 `docs/CHANGELOG_web.md`，`## [Unreleased]` 下 `### Added / 新增`；同一条目英文一行、中文紧接一行（中间不空行），不同条目之间空行。 + +**验证命令速查：** + +- 前端总门禁：`docker compose -f deploy/docker-compose.dev.yml exec web npm run check` +- e2e（B3 起，需 dev 栈 + 凭据）：完整命令见任务 10 步骤 10.2 / 任务 12 步骤 12.2 +- 后端不受本期影响，无需跑后端门禁 + +--- + +## 文件结构 / File structure + +**B1 创建/修改：** +- 创建 `frontend/eslint.config.js` — flat config，规则分层（基础/reader 豁免/e2e/测试） +- 创建 `frontend/.prettierrc`、`frontend/.prettierignore` +- 修改 `frontend/package.json` — scripts：lint/lint:fix/format/format:check/check +- 修改全部存量源文件 — prettier 基线格式化（独立 commit）+ eslint 修复 +- 修改 `docs/CHANGELOG_web.md` + +**B2 创建/修改：** +- 创建 `frontend/test/setup.ts` — jest-dom + cleanup + jsdom polyfill +- 修改 `frontend/vitest.config.ts` — projects 双环境（unit=node / components=jsdom） +- 创建 `frontend/src/components/ui/button.test.tsx` +- 创建 `frontend/src/components/ui/dialog.test.tsx` +- 创建 `frontend/src/components/theme-toggle.test.tsx` + +**B3 创建/修改：** +- 创建 `frontend/playwright.config.ts` +- 创建 `frontend/e2e/fixtures/e2e-sample.cbz`（二进制，脚本生成后提交） +- 创建 `frontend/e2e/helpers/api.ts`、`frontend/e2e/helpers/axe.ts` +- 创建 `frontend/e2e/auth-shelf.spec.ts`、`frontend/e2e/admin-smoke.spec.ts` +- 创建 `.github/workflows/e2e.yml` +- 修改 `frontend/package.json`（e2e/e2e:ui）、`frontend/eslint.config.js`（e2e override 已在 B1 预置）、根 `.gitignore` + +**B4 创建/修改：** +- 修改 `frontend/vite.config.ts` — 条件启用 visualizer +- 修改 `frontend/package.json`（analyze）、根 `.gitignore`（dist-stats） +- 创建 `docs/bundle-review.md`（双语） +- 修改 `docs/README.md`、`docs/README_zh.md`（双语等价） +- 修改 `docs/CHANGELOG_web.md` + +--- + +## B1 批次 1：ESLint + Prettier + +### 任务 1：安装依赖 + 创建 lint/format 配置 + +**文件：** +- 创建：`frontend/eslint.config.js`、`frontend/.prettierrc`、`frontend/.prettierignore` +- 修改：`frontend/package.json`（scripts，`check` 本任务先不改） + +- [ ] **步骤 1.1：容器内安装 dev 依赖** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npm install -D \ + eslint @eslint/js typescript-eslint \ + eslint-plugin-react-hooks eslint-plugin-jsx-a11y \ + eslint-config-prettier prettier +``` + +- [ ] **步骤 1.2：创建 `frontend/eslint.config.js`** + +```js +import js from "@eslint/js"; +import tseslint from "typescript-eslint"; +import reactHooks from "eslint-plugin-react-hooks"; +import jsxA11y from "eslint-plugin-jsx-a11y"; +import prettier from "eslint-config-prettier"; + +export default tseslint.config( + { ignores: ["dist/**", "dist-stats/**", "node_modules/**", "playwright-report/**", "test-results/**"] }, + js.configs.recommended, + ...tseslint.configs.recommended, + // react-hooks 插件的 flat 导出名随版本而异（recommended-latest / configs.flat.recommended）， + // 以安装版本实际导出为准，用 npx eslint --print-config src/main.tsx 验证规则已生效 + reactHooks.configs["recommended-latest"], + jsxA11y.flatConfigs.recommended, + { + files: ["**/*.{ts,tsx}"], + rules: { + "@typescript-eslint/no-unused-vars": [ + "error", + { argsIgnorePattern: "^_", varsIgnorePattern: "^_", caughtErrorsIgnorePattern: "^_" }, + ], + }, + }, + { + // 旧阅读器 chrome 的点击区/交互元素将被 ② 阅读器改版迁入 radix 原语， + // 届时收严为 error；本期对存量文件降 warn（spec S1 决策） + files: [ + "src/readers/**/*.tsx", + "src/components/Bookmarks.tsx", + "src/components/reader-nav.tsx", + "src/components/rd-slider.tsx", + "src/pages/Reader.tsx", + ], + rules: { + "jsx-a11y/click-events-have-key-events": "warn", + "jsx-a11y/no-static-element-interactions": "warn", + "jsx-a11y/no-noninteractive-element-interactions": "warn", + }, + }, + { + files: ["e2e/**/*.ts"], + languageOptions: { globals: { process: "readonly", console: "readonly", URL: "readonly" } }, + rules: { "@typescript-eslint/no-explicit-any": "off" }, + }, + { + files: ["**/*.test.{ts,tsx}", "test/**/*.ts"], + rules: { "@typescript-eslint/no-explicit-any": "off" }, + }, + prettier, // 必须最后：关闭所有与 prettier 冲突的格式规则 +); +``` + +注意：`e2e/` override 块此刻没有匹配文件（B3 才创建），eslint 对空匹配不报错，保留即可。 + +- [ ] **步骤 1.3：创建 `frontend/.prettierrc`** + +```json +{ + "printWidth": 120, + "tabWidth": 2, + "semi": true, + "singleQuote": false, + "trailingComma": "all" +} +``` + +依据：存量代码主流是双引号 + 分号（`api/client.ts`、`components/theme.tsx`），printWidth 120 贴近现有行宽，基线 format 的 diff 最小。`components/ui/*.tsx`（shadcn 生成、无分号）会被统一为带分号——这是预期。 + +- [ ] **步骤 1.4：创建 `frontend/.prettierignore`** + +``` +dist +dist-stats +node_modules +package-lock.json +playwright-report +test-results +``` + +- [ ] **步骤 1.5：`frontend/package.json` 增加 scripts（`check` 不动，任务 4 才接入）** + +在 `"scripts"` 中加： + +```json +"lint": "eslint .", +"lint:fix": "eslint . --fix", +"format": "prettier --write .", +"format:check": "prettier --check ." +``` + +- [ ] **步骤 1.6：验证工具可跑（此时有 error 是预期，不修）** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npx eslint --print-config src/main.tsx | head -5 +docker compose -f deploy/docker-compose.dev.yml exec web npm run lint 2>&1 | tail -20 +``` + +预期：print-config 输出含 `react-hooks` 与 `jsx-a11y` 规则（证明插件接通）；`npm run lint` 报出存量 error 清单。 + +- [ ] **步骤 1.7：Commit** + +```bash +git add frontend/eslint.config.js frontend/.prettierrc frontend/.prettierignore frontend/package.json frontend/package-lock.json +git commit -m "chore(frontend): eslint flat config + prettier baseline config" +``` + +### 任务 2：Prettier 全量基线格式化（独立 commit） + +**文件：** 修改：`frontend/` 下全部被 prettier 改写的源文件 + +- [ ] **步骤 2.1：全量格式化** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npm run format +``` + +- [ ] **步骤 2.2：确认无逻辑改动** + +```bash +git diff --stat | tail -5 +git diff | grep -E '^[-+]' | grep -vE '^[-+][-+]' | grep -cE '\w' +``` + +逐屏浏览 `git diff`：应当只有引号/分号/换行/缩进/class 字符串折行变化。若出现标识符或逻辑变化，停止并排查（prettier 不会改语义，出现即异常）。 + +- [ ] **步骤 2.3：跑存量门禁确认不破坏** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npx tsc --noEmit +docker compose -f deploy/docker-compose.dev.yml exec web npx vitest run +``` + +预期：tsc 0 error；9 个测试文件全过。 + +- [ ] **步骤 2.4：Commit（纯格式，单独成 commit 便于回滚）** + +```bash +git add frontend +git commit -m "style(frontend): prettier baseline format (no logic change)" +``` + +### 任务 3：ESLint 全库 0 error + +**文件：** 修改：所有报 error 的源文件；必要时微调 `frontend/eslint.config.js` + +- [ ] **步骤 3.1：拿到 error 清单并分类** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npm run lint 2>&1 | grep -E 'error' | sort | uniq -c | sort -rn +``` + +- [ ] **步骤 3.2：逐类修复** + +修复策略（按 spec S1「全库 0 error 一次到位」）： +- `no-unused-vars`：删除死代码；确需保留的参数加 `_` 前缀（config 已配 ignore pattern）； +- `@typescript-eslint/no-explicit-any`：能写出精确类型就写；确实动态的（如 JSON 解析结果）用 `unknown` + 收窄，或该行 `// eslint-disable-next-line @typescript-eslint/no-explicit-any -- <一句话理由>`； +- `react-hooks/exhaustive-deps`：recommended 集里默认是 warn，不阻断；若某条是 error 级，优先修依赖数组，修不动（故意省略）则行内 disable + 注释理由； +- `jsx-a11y/*`（reader 豁免区之外，如 `pages/Shelf.tsx`、`app-shell.tsx`）：属性级小修（加 `role`、`aria-label`、键盘事件）；确实属于将被 ② 重写的旧代码，把该文件加进 eslint.config.js 的 reader 豁免 override 的 `files` 列表，并在该块注释里补一行说明（不要新开无注释的豁免块）； +- 其余规则：能修则修；某规则全库过噪且不适合本期修，才允许在 config 中降 warn/关闭，且必须带注释理由。 + +每修一类重跑： + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npm run lint +``` + +- [ ] **步骤 3.3：验证 0 error** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npm run lint +``` + +预期：退出码 0，无 error 行（warn 允许存在，每条 warn 对应的规则降级在 config 内有注释）。 + +- [ ] **步骤 3.4：确认修复没破坏行为** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npx tsc --noEmit +docker compose -f deploy/docker-compose.dev.yml exec web npx vitest run +``` + +预期：全绿。 + +- [ ] **步骤 3.5：Commit** + +```bash +git add frontend +git commit -m "fix(frontend): resolve all eslint errors to zero (B1)" +``` + +### 任务 4：接入 check 门禁 + changelog + B1 验收 + +**文件：** +- 修改：`frontend/package.json`（check）、`docs/CHANGELOG_web.md` + +- [ ] **步骤 4.1：`check` 脚本改为** + +```json +"check": "tsc --noEmit && eslint . && prettier --check . && vitest run && vite build" +``` + +- [ ] **步骤 4.2：全量门禁验证** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npm run check +``` + +预期：五段全部通过、退出码 0。 + +- [ ] **步骤 4.3：changelog（`docs/CHANGELOG_web.md`，`## [Unreleased]` → `### Added / 新增` 顶部插入）** + +```markdown +- Developer tooling: ESLint (flat config, typescript-eslint + react-hooks + jsx-a11y) and Prettier are now part of `npm run check` and CI; the whole codebase passes with zero eslint errors. +- 开发工具链：ESLint（flat config，typescript-eslint + react-hooks + jsx-a11y）与 Prettier 纳入 `npm run check` 和 CI；全库 0 eslint error。 +``` + +- [ ] **步骤 4.4：Commit** + +```bash +git add frontend/package.json docs/CHANGELOG_web.md +git commit -m "chore(frontend): wire lint+format into check gate, changelog (B1 done)" +``` + +--- + +## B2 批次 2：组件测试基建 + +### 任务 5：测试依赖 + setup + vitest projects 配置 + +**文件：** +- 创建：`frontend/test/setup.ts` +- 修改：`frontend/vitest.config.ts` + +- [ ] **步骤 5.1：容器内安装** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npm install -D \ + jsdom @testing-library/react @testing-library/user-event @testing-library/jest-dom +``` + +- [ ] **步骤 5.2：创建 `frontend/test/setup.ts`** + +```ts +import "@testing-library/jest-dom/vitest"; +import { cleanup } from "@testing-library/react"; +import { afterEach } from "vitest"; + +afterEach(() => cleanup()); + +// jsdom 缺口 polyfill（spec S2）：radix 原语在 jsdom 下的已知缺失，一次配好全体组件测试共用。 + +class ResizeObserverStub { + observe() {} + unobserve() {} + disconnect() {} +} +globalThis.ResizeObserver ??= ResizeObserverStub as unknown as typeof ResizeObserver; + +Element.prototype.scrollIntoView ??= function scrollIntoView() {}; + +// radix 的焦点/拖拽逻辑会探测 pointer capture API，jsdom 未实现 +Element.prototype.hasPointerCapture ??= (() => false) as never; +Element.prototype.setPointerCapture ??= (() => {}) as never; +Element.prototype.releasePointerCapture ??= (() => {}) as never; +``` + +- [ ] **步骤 5.3：重写 `frontend/vitest.config.ts` 为 projects 双环境** + +```ts +import { defineConfig } from "vitest/config"; + +export default defineConfig({ + resolve: { alias: { "@": new URL("./src", import.meta.url).pathname } }, + test: { + passWithNoTests: true, + projects: [ + { + extends: true, + test: { name: "unit", include: ["test/**/*.test.ts"], environment: "node" }, + }, + { + extends: true, + test: { + name: "components", + include: ["src/**/*.test.tsx"], + environment: "jsdom", + setupFiles: ["test/setup.ts"], + }, + }, + ], + }, +}); +``` + +- [ ] **步骤 5.4：验证存量测试不受影响** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npx vitest run +``` + +预期：`unit` project 9 个文件全过；`components` 无测试（passWithNoTests）。 + +- [ ] **步骤 5.5：Commit** + +```bash +git add frontend/test/setup.ts frontend/vitest.config.ts frontend/package.json frontend/package-lock.json +git commit -m "test(frontend): component testing infra (jsdom + testing-library + vitest projects)" +``` + +### 任务 6：三个样板组件测试 + +**文件：** +- 创建：`frontend/src/components/ui/button.test.tsx`、`frontend/src/components/ui/dialog.test.tsx`、`frontend/src/components/theme-toggle.test.tsx` + +- [ ] **步骤 6.1：`frontend/src/components/ui/button.test.tsx`** + +```tsx +import { render, screen } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { describe, expect, it, vi } from "vitest"; +import { Button } from "./button"; + +describe("Button", () => { + it("renders label, exposes variant/size data attrs, fires onClick", async () => { + const onClick = vi.fn(); + render( + , + ); + const btn = screen.getByRole("button", { name: "保存" }); + expect(btn).toHaveAttribute("data-variant", "default"); + expect(btn).toHaveAttribute("data-size", "default"); + await userEvent.click(btn); + expect(onClick).toHaveBeenCalledTimes(1); + }); + + it("applies non-default variant/size and blocks clicks when disabled", async () => { + const onClick = vi.fn(); + render( + , + ); + const btn = screen.getByRole("button"); + expect(btn).toHaveAttribute("data-variant", "outline"); + expect(btn).toHaveAttribute("data-size", "sm"); + expect(btn).toBeDisabled(); + await userEvent.click(btn); + expect(onClick).not.toHaveBeenCalled(); + }); +}); +``` + +- [ ] **步骤 6.2：`frontend/src/components/ui/dialog.test.tsx`** + +```tsx +import { render, screen, waitFor } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { describe, expect, it } from "vitest"; +import { Dialog, DialogContent, DialogTitle, DialogTrigger } from "./dialog"; + +describe("Dialog", () => { + it("opens via trigger, renders title, closes via Escape (radix under jsdom)", async () => { + render( + + 打开对话框 + + 测试标题 +

正文内容

+ + , + ); + expect(screen.queryByRole("dialog")).not.toBeInTheDocument(); + + await userEvent.click(screen.getByRole("button", { name: "打开对话框" })); + expect(await screen.findByRole("dialog")).toBeInTheDocument(); + expect(screen.getByText("测试标题")).toBeInTheDocument(); + expect(screen.getByText("正文内容")).toBeInTheDocument(); + + await userEvent.keyboard("{Escape}"); + await waitFor(() => expect(screen.queryByRole("dialog")).not.toBeInTheDocument()); + }); +}); +``` + +此测试是基建的关键验证点：radix Portal/焦点管理/动画在 jsdom 下能走通，② 的 Sheet/Popover 迁移才可依赖同一套环境。若因动画卡住，允许在断言前加 `await waitFor(...)`，不允许 mock radix 内部。 + +- [ ] **步骤 6.3：`frontend/src/components/theme-toggle.test.tsx`** + +```tsx +import { render, screen, waitFor } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { describe, expect, it } from "vitest"; +import { ThemeProvider } from "./theme"; +import { ThemeToggle } from "./theme-toggle"; + +describe("ThemeToggle", () => { + it("switches theme via dropdown, persists to localStorage, toggles dark class", async () => { + localStorage.clear(); + document.documentElement.classList.remove("dark"); + render( + + + , + ); + + await userEvent.click(screen.getByRole("button", { name: "切换主题" })); + await userEvent.click(await screen.findByText("深色")); + + await waitFor(() => expect(localStorage.getItem("ui.theme")).toBe("dark")); + expect(document.documentElement.classList.contains("dark")).toBe(true); + }); +}); +``` + +（`theme.tsx` 的持久化 key 是 `ui.theme`，dark 模式落在 `documentElement` 的 `dark` class——断言直接对齐实现，不引入新抽象。） + +- [ ] **步骤 6.4：运行验证** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npx vitest run +``` + +预期：unit 9 文件 + components 3 文件全过。失败则修测试环境问题（polyfill 缺口补进 `test/setup.ts`），不改被测组件行为。 + +- [ ] **步骤 6.5：lint/format 新文件并全量门禁** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npm run check +``` + +预期：绿（新测试文件也过 eslint/prettier；不过则 `lint:fix`/`format` 后复跑）。 + +- [ ] **步骤 6.6：Commit** + +```bash +git add frontend/src +git commit -m "test(frontend): sample component tests for button/dialog/theme-toggle (B2)" +``` + +--- + +## B3 批次 3：e2e + a11y 运行时扫描 + +### 任务 7：Playwright 依赖 + 配置 + scripts + +**文件：** +- 创建：`frontend/playwright.config.ts` +- 修改：`frontend/package.json`（scripts）、根 `.gitignore` + +- [ ] **步骤 7.1：容器内安装** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npm install -D @playwright/test @axe-core/playwright +docker compose -f deploy/docker-compose.dev.yml exec web npx playwright install --with-deps chromium +``` + +浏览器只装 chromium；安装命令将写入 README（任务 15）。 + +- [ ] **步骤 7.2：创建 `frontend/playwright.config.ts`** + +```ts +import { defineConfig, devices } from "@playwright/test"; + +export default defineConfig({ + testDir: "e2e", + timeout: 60_000, + use: { + baseURL: process.env.E2E_BASE_URL ?? "http://localhost:5173", + trace: "retain-on-failure", + }, + projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }], +}); +``` + +不由 Playwright 管理 server：前提是 dev 栈已手动起好（spec S3 决策），连不上时测试直接失败并暴露网络错误。 + +- [ ] **步骤 7.3：`frontend/package.json` scripts 增加** + +```json +"e2e": "playwright test", +"e2e:ui": "playwright test --ui" +``` + +- [ ] **步骤 7.4：根 `.gitignore` 增加（`.playwright*/` 已存在）** + +``` +playwright-report/ +test-results/ +dist-stats/ +``` + +- [ ] **步骤 7.5：验证配置可被发现** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npx playwright test --list +``` + +预期：0 个测试、无配置错误（e2e 目录还不存在时输出 "no tests found"，退出码非 0 也可接受，只要不是配置解析错误）。 + +- [ ] **步骤 7.6：Commit** + +```bash +git add frontend/playwright.config.ts frontend/package.json frontend/package-lock.json .gitignore +git commit -m "test(frontend): playwright e2e scaffolding (config + scripts)" +``` + +### 任务 8：生成 CBZ fixture + +**文件：** +- 创建：`frontend/e2e/fixtures/e2e-sample.cbz`（二进制，约 1KB） + +- [ ] **步骤 8.1：用 python3 生成 3 页 800x1200 纯色 PNG 的 CBZ** + +```bash +mkdir -p frontend/e2e/fixtures +python3 - <<'PY' +import struct, zlib, zipfile + +W, H = 800, 1200 + +def chunk(tag, data): + body = tag + data + return struct.pack(">I", len(data)) + body + struct.pack(">I", zlib.crc32(body)) + +def solid_png(rgb): + raw = b"".join(b"\x00" + bytes(rgb) * W for _ in range(H)) + ihdr = struct.pack(">IIBBBBB", W, H, 8, 2, 0, 0, 0) + return ( + b"\x89PNG\r\n\x1a\n" + + chunk(b"IHDR", ihdr) + + chunk(b"IDAT", zlib.compress(raw, 9)) + + chunk(b"IEND", b"") + ) + +with zipfile.ZipFile("frontend/e2e/fixtures/e2e-sample.cbz", "w", zipfile.ZIP_STORED) as z: + for i, rgb in enumerate([(220, 60, 60), (60, 200, 60), (60, 60, 220)], 1): + z.writestr(f"{i:03d}.png", solid_png(rgb)) +PY +``` + +800x1200 保证每页高于 e2e 视口（1280x720），右缘点击翻屏可观测到页码变化。 + +- [ ] **步骤 8.2：验证 fixture 合法** + +```bash +python3 -c "import zipfile; z=zipfile.ZipFile('frontend/e2e/fixtures/e2e-sample.cbz'); print(z.namelist(), z.testzip())" +``` + +预期：`['001.png', '002.png', '003.png'] None`。 + +- [ ] **步骤 8.3：Commit** + +```bash +git add frontend/e2e/fixtures/e2e-sample.cbz +git commit -m "test(frontend): tiny 3-page CBZ fixture for e2e" +``` + +### 任务 9：e2e helpers（API fixture + axe） + +**文件：** +- 创建：`frontend/e2e/helpers/api.ts`、`frontend/e2e/helpers/axe.ts` + +- [ ] **步骤 9.1：创建 `frontend/e2e/helpers/api.ts`** + +```ts +import { readFileSync } from "node:fs"; +import { fileURLToPath } from "node:url"; +import { request, type APIRequestContext } from "@playwright/test"; + +export const BASE = process.env.E2E_BASE_URL ?? "http://localhost:5173"; +export const FIXTURE_CBZ = fileURLToPath(new URL("../fixtures/e2e-sample.cbz", import.meta.url)); + +/** UI 登录与 API fixture 共用同一管理员凭据：E2E_ADMIN_* 优先，回落 deploy/.env 注入的 ADMIN_*。 */ +export function creds(): { user: string; pass: string } { + const user = process.env.E2E_ADMIN_USER ?? process.env.ADMIN_USER; + const pass = process.env.E2E_ADMIN_PASSWORD ?? process.env.ADMIN_PASSWORD; + if (!user || !pass) { + throw new Error( + "缺少管理员凭据：export E2E_ADMIN_USER/E2E_ADMIN_PASSWORD，" + + "或 `set -a; source ../deploy/.env; set +a` 后重跑", + ); + } + return { user, pass }; +} + +export async function adminApi(): Promise { + const { user, pass } = creds(); + const res = await fetch(`${BASE}/api/auth/login`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ username: user, password: pass }), + }); + if (!res.ok) throw new Error(`admin 登录失败：HTTP ${res.status}（dev 栈起了吗？凭据对吗？）`); + const { token } = (await res.json()) as { token: string }; + return request.newContext({ baseURL: BASE, extraHTTPHeaders: { Authorization: `Bearer ${token}` } }); +} + +export async function ensureLibrary(ctx: APIRequestContext, name: string): Promise { + const libs = (await (await ctx.get("/api/libraries")).json()) as { id: number; name: string }[]; + const hit = libs.find((l) => l.name === name); + if (hit) return hit.id; + const created = (await (await ctx.post("/api/libraries", { data: { name } })).json()) as { id: number }; + return created.id; +} + +async function findBook(ctx: APIRequestContext, q: string): Promise<{ id: number; title: string } | null> { + const res = await ctx.get(`/api/books?q=${encodeURIComponent(q)}`); + const books = (await res.json()) as { id: number; title: string }[]; + return books.find((b) => b.title.includes(q)) ?? null; +} + +/** 幂等：书已存在直接返回 id；否则上传 fixture → 触发扫描 → 轮询等书出现（扫描是 fire-and-forget）。 */ +export async function ensureSampleBook(ctx: APIRequestContext, libName: string): Promise { + const title = "e2e-sample"; + const existing = await findBook(ctx, title); + if (existing) return existing.id; + const libId = await ensureLibrary(ctx, libName); + const up = await ctx.post(`/api/libraries/${libId}/upload`, { + multipart: { + file: { name: "e2e-sample.cbz", mimeType: "application/zip", buffer: readFileSync(FIXTURE_CBZ) }, + }, + }); + if (!up.ok()) throw new Error(`上传失败：HTTP ${up.status()} ${await up.text()}`); + const scan = await ctx.post(`/api/libraries/${libId}/scan`); + if (!scan.ok()) throw new Error(`触发扫描失败：HTTP ${scan.status()}`); + const deadline = Date.now() + 30_000; + for (;;) { + const hit = await findBook(ctx, title); + if (hit) return hit.id; + if (Date.now() > deadline) throw new Error(`扫描后 30s 内未找到书「${title}」`); + await new Promise((r) => setTimeout(r, 1000)); + } +} +``` + +- [ ] **步骤 9.2：创建 `frontend/e2e/helpers/axe.ts`** + +```ts +import { expect, type Page } from "@playwright/test"; +import AxeBuilder from "@axe-core/playwright"; + +interface Waiver { + page: string; + rule: string; + reason: string; +} + +/** + * critical/serious 违规的逐条豁免清单（spec S3）： + * 仅允许「属于将被 ② 阅读器改版重写的旧 chrome」的问题进这里，reason 必须写明归属。 + * 例：{ page: "reader-chrome", rule: "color-contrast", reason: "旧 rd-* chrome 配色，② 迁移 shadcn token 后移除本豁免" } + */ +const WAIVERS: Waiver[] = []; + +export async function scanA11y(page: Page, name: string): Promise { + const results = await new AxeBuilder({ page }) + .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"]) + .analyze(); + + if (results.violations.length > 0) { + console.log( + `[axe:${name}]`, + JSON.stringify( + results.violations.map((v) => ({ id: v.id, impact: v.impact, nodes: v.nodes.length })), + null, + 2, + ), + ); + } + + const blocking = results.violations.filter( + (v) => + (v.impact === "critical" || v.impact === "serious") && + !WAIVERS.some((w) => w.page === name && w.rule === v.id), + ); + expect(blocking.map((v) => ({ id: v.id, impact: v.impact })), `${name} 存在未豁免的 critical/serious a11y 违规`).toEqual([]); +} +``` + +- [ ] **步骤 9.3：lint 验证 + Commit** + +```bash +docker compose -f deploy/docker-compose.dev.yml exec web npm run lint +git add frontend/e2e/helpers +git commit -m "test(frontend): e2e api/axe helpers" +``` + +### 任务 10：主流程 spec `auth-shelf.spec.ts` + +**文件：** +- 创建：`frontend/e2e/auth-shelf.spec.ts` + +UI 锚点（来自现有代码，写死选择器时以此为准）： +- 登录页：`#login-user`、`#login-pass`、提交按钮文案「登录」（`pages/Login.tsx`）； +- 书架卡片：外层 `