XingfenD/book-comic-library
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
147339083b3772aebd837084b3df898cee8a384b
book-comic-library/docs/superpowers/plans/2026-09-15-frontend-quality.md
T

45 KiB
Raw Blame History

前端工程质量（④）实现计划 / 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 无效）：

# 仓库根执行，下文简写「容器内 npm …」
docker compose -f deploy/docker-compose.dev.yml exec web npm <args>

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 依赖

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
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
{
  "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" 中加：

"lint": "eslint .",
"lint:fix": "eslint . --fix",
"format": "prettier --write .",
"format:check": "prettier --check ."
  • 步骤 1.6：验证工具可跑（此时有 error 是预期，不修）
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
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：全量格式化
docker compose -f deploy/docker-compose.dev.yml exec web npm run format
  • 步骤 2.2：确认无逻辑改动
git diff --stat | tail -5
git diff | grep -E '^[-+]' | grep -vE '^[-+][-+]' | grep -cE '\w'

逐屏浏览 git diff：应当只有引号/分号/换行/缩进/class 字符串折行变化。若出现标识符或逻辑变化，停止并排查（prettier 不会改语义，出现即异常）。

  • 步骤 2.3：跑存量门禁确认不破坏
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 便于回滚）
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 清单并分类
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/关闭，且必须带注释理由。

每修一类重跑：

docker compose -f deploy/docker-compose.dev.yml exec web npm run lint
  • 步骤 3.3：验证 0 error
docker compose -f deploy/docker-compose.dev.yml exec web npm run lint

预期：退出码 0，无 error 行（warn 允许存在，每条 warn 对应的规则降级在 config 内有注释）。

  • 步骤 3.4：确认修复没破坏行为
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
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 脚本改为

"check": "tsc --noEmit && eslint . && prettier --check . && vitest run && vite build"
  • 步骤 4.2：全量门禁验证
docker compose -f deploy/docker-compose.dev.yml exec web npm run check

预期：五段全部通过、退出码 0。

  • 步骤 4.3：changelog（docs/CHANGELOG_web.md，## [Unreleased] → ### Added / 新增 顶部插入）
- 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
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：容器内安装

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
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 双环境
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：验证存量测试不受影响
docker compose -f deploy/docker-compose.dev.yml exec web npx vitest run

预期：unit project 9 个文件全过；components 无测试（passWithNoTests）。

  • 步骤 5.5：Commit
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

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(
      <Button onClick={onClick}>
        保存
      </Button>,
    );
    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(
      <Button variant="outline" size="sm" disabled onClick={onClick}>
        x
      </Button>,
    );
    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
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(
      <Dialog>
        <DialogTrigger>打开对话框</DialogTrigger>
        <DialogContent>
          <DialogTitle>测试标题</DialogTitle>
          <p>正文内容</p>
        </DialogContent>
      </Dialog>,
    );
    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
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(
      <ThemeProvider>
        <ThemeToggle />
      </ThemeProvider>,
    );

    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：运行验证
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 新文件并全量门禁
docker compose -f deploy/docker-compose.dev.yml exec web npm run check

预期：绿（新测试文件也过 eslint/prettier；不过则 lint:fix/format 后复跑）。

  • 步骤 6.6：Commit
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：容器内安装

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
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 增加
"e2e": "playwright test",
"e2e:ui": "playwright test --ui"
  • 步骤 7.4：根 .gitignore 增加（.playwright*/ 已存在）
playwright-report/
test-results/
dist-stats/
  • 步骤 7.5：验证配置可被发现
docker compose -f deploy/docker-compose.dev.yml exec web npx playwright test --list

预期：0 个测试、无配置错误（e2e 目录还不存在时输出 "no tests found"，退出码非 0 也可接受，只要不是配置解析错误）。

  • 步骤 7.6：Commit
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

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 合法
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
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

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<APIRequestContext> {
  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<number> {
  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<number> {
  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
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<void> {
  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
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）；

  • 书架卡片：外层 <button> 可访问名含书名（pages/Shelf.tsx BookCard）；

  • 阅读器容器：aria-label="漫画阅读器,点按左右两侧翻屏,点按中间显示工具栏"（readers/CbzReader.tsx:298）；chrome 默认展开（pages/Reader.tsx chromeOn=true）；

  • 导航抽屉：工具条按钮文案「导航」（aria-controls="reader-nav"），书签面板「加书签」按钮（components/Bookmarks.tsx:70），成功 toast「已加书签」，关闭按钮 aria-label="关闭导航"（components/reader-nav.tsx:58）；

  • 退出：侧栏「账户 <用户名>」dropdown → 「退出登录」（components/app-shell.tsx:52,79）。

  • 步骤 10.1：创建 frontend/e2e/auth-shelf.spec.ts

import { expect, test, type APIRequestContext } from "@playwright/test";
import { adminApi, creds, ensureSampleBook } from "./helpers/api";
import { scanA11y } from "./helpers/axe";

let admin: APIRequestContext;
let bookId: number;

test.beforeAll(async () => {
  admin = await adminApi();
  bookId = await ensureSampleBook(admin, "e2e");
});

test.afterAll(async () => {
  await admin?.dispose();
});

test("登录 → 书架 → CBZ 阅读翻页 → 书签 → 退出", async ({ page }) => {
  const { user, pass } = creds();

  // 登录页 + axe
  await page.goto("/login");
  await scanA11y(page, "login");
  await page.fill("#login-user", user);
  await page.fill("#login-pass", pass);
  await page.getByRole("button", { name: "登录", exact: true }).click();
  await expect(page).toHaveURL(/\/$/);

  // 书架 + axe；样本卡可见并点进阅读器
  await expect(page.getByRole("button", { name: /e2e-sample/ })).toBeVisible();
  await scanA11y(page, "shelf");
  await page.getByRole("button", { name: /e2e-sample/ }).click();
  await expect(page).toHaveURL(new RegExp(`/book/${bookId}`));

  // 阅读器（chrome 默认展开）+ axe
  const reader = page.getByLabel("漫画阅读器,点按左右两侧翻屏,点按中间显示工具栏");
  await expect(reader).toBeVisible();
  await expect(page.getByText("1/3")).toBeVisible();
  await scanA11y(page, "reader-chrome");

  // 右缘点击翻屏 → 页码前进
  const box = await reader.boundingBox();
  if (!box) throw new Error("阅读器容器无 boundingBox");
  await page.mouse.click(box.x + box.width * 0.9, box.y + box.height / 2);
  await expect(page.getByText("2/3")).toBeVisible();

  // 导航抽屉 → 书签 tab → 加书签 → toast
  await page.getByRole("button", { name: "导航", exact: false }).click();
  const nav = page.locator("#reader-nav");
  await expect(nav).toBeVisible();
  await nav.getByRole("button", { name: "书签" }).click();
  await nav.getByRole("button", { name: "加书签" }).click();
  await expect(page.getByText("已加书签")).toBeVisible();
  await page.getByRole("button", { name: "关闭导航" }).click();

  // 回书架 → 退出登录
  await page.getByRole("link", { name: "书架" }).click();
  await expect(page).toHaveURL(/\/$/);
  await page.getByRole("button", { name: new RegExp(`账户 ${user}`) }).click();
  await page.getByText("退出登录").click();
  await expect(page).toHaveURL(/\/login/);
});
  • 步骤 10.2：起 dev 栈并跑通
# 仓库根：确保栈在跑
docker compose -f deploy/docker-compose.dev.yml ps
# 注入凭据后跑（deploy/.env 提供 ADMIN_USER/ADMIN_PASSWORD）
set -a; source deploy/.env; set +a
cd frontend && docker compose -f ../deploy/docker-compose.dev.yml exec -T \
  -e E2E_ADMIN_USER="$ADMIN_USER" -e E2E_ADMIN_PASSWORD="$ADMIN_PASSWORD" \
  web npx playwright test auth-shelf

预期：1 passed。若选择器失配（实现与上述锚点有出入），以 DOM 实况为准修选择器，不允许改用例语义（翻页/书签/退出都必须真实发生）。

  • 步骤 10.3：处理 axe 红灯

login/shelf 页若有 critical/serious 违规：属性级小修（补 aria/对比度），修完重跑，修复记入 changelog（任务 12 步骤 12.4）。reader-chrome 的违规若源于旧 rd-* 样式（将被 ② 重写）：在 helpers/axe.ts 的 WAIVERS 加一条（page=reader-chrome、rule=违规 id、reason 注明「旧 chrome，② 迁移后移除本豁免」）。a11y 豁免只进 WAIVERS，不另开文档。

  • 步骤 10.4：Commit
git add frontend/e2e/auth-shelf.spec.ts frontend/e2e/helpers/axe.ts frontend/src
git commit -m "test(frontend): e2e main flow (login→shelf→cbz→bookmark→logout) + axe scans"

任务 11：admin 冒烟 spec

文件：

  • 创建：frontend/e2e/admin-smoke.spec.ts

UI 锚点：库管理页输入框 placeholder 以「库名」开头、按钮「建库」、成功 toast「库「<名>」已创建」、行内「扫描」按钮、toast「扫描已触发」（pages/admin/Libraries.tsx）。无删库 API（③ 范围），每次运行用唯一库名，dev 库中残留属预期。

  • 步骤 11.1：创建 frontend/e2e/admin-smoke.spec.ts
import { expect, test } from "@playwright/test";
import { creds } from "./helpers/api";

test("admin：建库 → 触发扫描（冒烟）", async ({ page }) => {
  const { user, pass } = creds();
  const libName = `e2e-admin-${Date.now()}`;

  await page.goto("/login");
  await page.fill("#login-user", user);
  await page.fill("#login-pass", pass);
  await page.getByRole("button", { name: "登录", exact: true }).click();
  await expect(page).toHaveURL(/\/$/);

  await page.goto("/admin/libraries");
  await page.getByPlaceholder(/库名/).fill(libName);
  await page.getByRole("button", { name: "建库" }).click();
  await expect(page.getByText(`库「${libName}」已创建`)).toBeVisible();
  await expect(page.getByRole("cell", { name: libName })).toBeVisible();

  const row = page.getByRole("row", { name: new RegExp(libName) });
  await row.getByRole("button", { name: /扫描/ }).click();
  await expect(page.getByText("扫描已触发")).toBeVisible();
});
  • 步骤 11.2：跑通
cd frontend && docker compose -f ../deploy/docker-compose.dev.yml exec -T \
  -e E2E_ADMIN_USER="$ADMIN_USER" -e E2E_ADMIN_PASSWORD="$ADMIN_PASSWORD" \
  web npx playwright test admin-smoke

预期：1 passed。注意本用例会真实建库并触发扫描；库残留在 dev 数据卷中（无删除 API，③ 补）。

  • 步骤 11.3：Commit
git add frontend/e2e/admin-smoke.spec.ts
git commit -m "test(frontend): e2e admin smoke (create library + scan)"

任务 12：CI e2e workflow + B3 收尾

文件：

  • 创建：.github/workflows/e2e.yml

  • 修改：docs/CHANGELOG_web.md

  • 步骤 12.1：创建 .github/workflows/e2e.yml

name: e2e
on: workflow_dispatch

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Start dev stack
        working-directory: deploy
        env:
          JWT_SECRET: ci-e2e-only-secret
          ADMIN_USER: admin
          ADMIN_PASSWORD: ci-e2e-password
        run: docker compose -f docker-compose.dev.yml up -d --build
      - name: Wait for web
        run: |
          for i in $(seq 1 90); do
            if curl -fsS http://localhost:5173/ >/dev/null 2>&1; then exit 0; fi
            sleep 5
          done
          echo "web not up in 450s"; docker compose -f deploy/docker-compose.dev.yml logs --tail 50; exit 1
      - run: cd frontend && npm ci
      - run: cd frontend && npx playwright install --with-deps chromium
      - name: Run e2e
        working-directory: frontend
        env:
          E2E_ADMIN_USER: admin
          E2E_ADMIN_PASSWORD: ci-e2e-password
        run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: frontend/playwright-report

说明：runner 未就绪期间此 workflow 不会自动跑（仅 workflow_dispatch），形同文档；凭据是 CI 一次性值，与 deploy/.env 无关。

  • 步骤 12.2：全量 e2e 本地验证（B3 验收）
set -a; source deploy/.env; set +a
cd frontend && docker compose -f ../deploy/docker-compose.dev.yml exec -T \
  -e E2E_ADMIN_USER="$ADMIN_USER" -e E2E_ADMIN_PASSWORD="$ADMIN_PASSWORD" \
  web npm run e2e

预期：2 spec 全 passed。

  • 步骤 12.3：npm run check 仍绿（e2e 不进 check）
docker compose -f deploy/docker-compose.dev.yml exec web npm run check
  • 步骤 12.4：changelog（### Added / 新增 顶部插入；若任务 10 做了 a11y 属性修复，在 ### Fixed / 修复（无此小节则新建）补一条双语说明修了什么）
- E2E test suite (Playwright + axe-core) covering login→shelf→CBZ reading→bookmark→logout and an admin create-library/scan smoke, run against the dev compose stack via `npm run e2e` (manual pre-release gate); critical/serious a11y violations fail the run.
- 新增 e2e 测试套件（Playwright + axe-core）：覆盖 登录→书架→CBZ 阅读→书签→退出 主流程与 admin 建库/扫描冒烟，针对 dev compose 栈以 `npm run e2e` 手动门禁运行；critical/serious 级 a11y 违规会使测试失败。
  • 步骤 12.5：Commit
git add .github/workflows/e2e.yml docs/CHANGELOG_web.md
git commit -m "ci: e2e workflow (workflow_dispatch) + changelog (B3 done)"

B4 批次 4：bundle 分析

任务 13：visualizer 接入

文件：

  • 修改：frontend/vite.config.ts、frontend/package.json

  • 步骤 13.1：容器内安装

docker compose -f deploy/docker-compose.dev.yml exec web npm install -D rollup-plugin-visualizer
  • 步骤 13.2：frontend/vite.config.ts 条件启用

顶部加 import：

import { visualizer } from "rollup-plugin-visualizer";

plugins 数组末尾（VitePWA({...}) 之后）加：

    // npm run analyze：体积报告输出到 dist-stats/（git-ignore，不进发布产物）
    ...(process.env.ANALYZE ? [visualizer({ filename: "dist-stats/stats.html", gzipSize: true, brotliSize: true })] : []),
  • 步骤 13.3：frontend/package.json scripts 增加
"analyze": "ANALYZE=1 vite build"
  • 步骤 13.4：验证报告生成且默认 build 不受影响
docker compose -f deploy/docker-compose.dev.yml exec web npm run analyze
docker compose -f deploy/docker-compose.dev.yml exec web ls dist-stats/
docker compose -f deploy/docker-compose.dev.yml exec web npm run build
docker compose -f deploy/docker-compose.dev.yml exec web sh -c 'ls dist-stats 2>/dev/null; test -f dist/stats.html && echo "PWA build ok"'

预期：analyze 生成 dist-stats/stats.html；普通 build 不生成/不更新它，dist 产物正常。

  • 步骤 13.5：Commit
git add frontend/vite.config.ts frontend/package.json frontend/package-lock.json
git commit -m "chore(frontend): bundle analyzer via npm run analyze (B4)"

任务 14：docs/bundle-review.md 审视结论

文件：

  • 创建：docs/bundle-review.md

  • 步骤 14.1：采集数据

打开 frontend/dist-stats/stats.html（浏览器），记录：dist 总大小、每个 chunk 的 stat/parsed/gzip/brotli 体积、Top 依赖（预期大头：pdfjs-dist、epubjs、react-dom、react-query、radix-ui、marked、dompurify、lucide-react）。同时核对 frontend/src/pages/Reader.tsx 的 lazy() 现状（cbz/txt/md/pdf/epub 五读者已是动态 import）。

  • 步骤 14.2：写 docs/bundle-review.md（双语，结构如下，数值填步骤 14.1 实测值）
# 前端 bundle 审视（2026-09） / Frontend bundle review

> 由 `cd frontend && npm run analyze` 生成 `dist-stats/stats.html` 后人工审视得出；本期只记录结论，不实施优化（spec ④ S4）。
> Generated from `dist-stats/stats.html` (`npm run analyze`); findings only — no optimization in this batch (spec ④ S4).

## 现状 / Current state

| chunk | 入口/来源 | stat | gzip | brotli | 备注 |
| --- | --- | --- | --- | --- | --- |
| （实测逐行填写：index 主包、各 lazy reader chunk、vendor 拆分情况） | | | | | |

- 五个阅读器（cbz/txt/md/pdf/epub）均已通过 `pages/Reader.tsx` 的 `lazy()` 按需加载：是/否（实测确认）。
- PWA precache（`workbox.globPatterns`）当前包含哪些大文件：（实测列出）。

## 可优化点 / Optimization backlog

| # | 问题 | 证据（chunk/体积） | 建议动作 | 归属 |
| --- | --- | --- | --- | --- |
| 1 | （例）pdfjs worker 是否进主包 | | （例）确认 worker 独立 chunk + 懒加载 | ② 或后续 |
| 2 | （例）epubjs 依赖链体积 | | | |
| … | | | | |

## 结论 / Verdict

（2-3 句：当前体积是否可接受、最优先的 1-2 个优化项、建议何时做。）

表格行与 backlog 条目必须来自实测，不写猜测值；「归属」列只能填「②」「③」或「后续 spec」。

  • 步骤 14.3：Commit
git add docs/bundle-review.md
git commit -m "docs: bundle review findings (B4)"

任务 15：README 双语更新

文件：

  • 修改：docs/README.md、docs/README_zh.md（内容等价，同批）

  • 步骤 15.1：更新前端门禁行

docs/README.md（现 L51）：

Frontend gate: `cd frontend && npm run check` (tsc + eslint + prettier + vitest + vite build). E2E is a separate manual pre-release gate against the dev stack: `cd frontend && npm run e2e` (requires `E2E_ADMIN_USER`/`E2E_ADMIN_PASSWORD`, or source `deploy/.env`; one-off browser install inside the web container: `npx playwright install --with-deps chromium`). Bundle report: `npm run analyze` → `dist-stats/stats.html`.

docs/README_zh.md（现 L51，等价中文）：

前端门槛:`cd frontend && npm run check`(tsc + eslint + prettier + vitest + vite build)。e2e 是独立的手动发布门禁,针对 dev 栈运行:`cd frontend && npm run e2e`(需 `E2E_ADMIN_USER`/`E2E_ADMIN_PASSWORD`,或 source `deploy/.env`;浏览器一次性安装于 web 容器内:`npx playwright install --with-deps chromium`)。体积报告:`npm run analyze` → `dist-stats/stats.html`。
  • 步骤 15.2：双语等价自查

两段 README 的 diff 只应触及对应行；英文行与中文行信息点一一对应（check 组成、e2e 前提与凭据、playwright 安装、analyze 产物）。

  • 步骤 15.3：Commit
git add docs/README.md docs/README_zh.md
git commit -m "docs: README frontend gates (lint/e2e/analyze), bilingual"

任务 16：总验收（DoD）+ 收尾

  • 步骤 16.1：对照 spec S5 逐项验证
# 1. check 全绿（tsc + eslint 0 error + prettier + vitest 12 文件 + build）
docker compose -f deploy/docker-compose.dev.yml exec web npm run check
# 2. e2e 全绿
set -a; source deploy/.env; set +a
cd frontend && docker compose -f ../deploy/docker-compose.dev.yml exec -T \
  -e E2E_ADMIN_USER="$ADMIN_USER" -e E2E_ADMIN_PASSWORD="$ADMIN_PASSWORD" \
  web npm run e2e && cd ..
# 3. analyze 可出报告
docker compose -f deploy/docker-compose.dev.yml exec web npm run analyze
# 4. 文档齐备
ls docs/bundle-review.md && git diff master --stat -- docs/README.md docs/README_zh.md docs/CHANGELOG_web.md
# 5. lockfile 已提交、prod 镜像无新依赖
git status --short
grep -c playwright frontend/Dockerfile.prod || echo "prod 未引入 playwright（预期 grep 无命中）"
  • 步骤 16.2：changelog 补 B2/B4 条目（### Added / 新增 顶部，B1/B3 条目之上按时间倒序）
- Developer tooling: component testing infrastructure (vitest jsdom project + Testing Library) with sample tests for shared UI components; reader component tests are deferred to the reader redesign. Bundle analysis available via `npm run analyze`, findings documented in `docs/bundle-review.md`.
- 开发工具链：组件测试基建（vitest jsdom project + Testing Library），公共 UI 组件配样板测试；阅读器组件测试留待阅读器改版。`npm run analyze` 可出 bundle 体积报告，结论见 `docs/bundle-review.md`。
  • 步骤 16.3：最终 Commit + 汇报
git add docs/CHANGELOG_web.md
git commit -m "docs: changelog for component testing + bundle review (B4 done, spec ④ complete)"
git log --oneline master..HEAD

向用户汇报四批次验收结果，走 finishing-a-development-branch 收尾（合并由用户决定）。

自检记录 / Self-check

  • 规格覆盖度：S1→任务 1-4；S2→任务 5-6；S3→任务 7-12；S4→任务 13-15；S5→任务 16；S6 范围外各项均无对应任务（正确）。spec S2「约定写入 README 或 spec 附录」——附录已在 spec 内，README 在任务 15 补命令说明，覆盖。
  • 占位符扫描：任务 14 的表格数值为运行时实测数据（文档模板即交付物结构），非计划占位符；其余步骤均含完整代码/命令。
  • 类型一致性：creds()/adminApi()/ensureLibrary()/ensureSampleBook()/scanA11y() 在任务 9 定义、任务 10/11 使用，签名一致；FIXTURE_CBZ 路径与任务 8 产物一致；e2e-sample 标题串在 fixture 文件名、waitBook 查询、书架选择器三处一致。
Reference in New Issue View Git Blame Copy Permalink