From 42a39ceef8b51751d9c0e7a7c7cad5d894c3bc3c Mon Sep 17 00:00:00 2001 From: XingfenD Date: Tue, 15 Sep 2026 10:59:43 +0800 Subject: [PATCH 01/22] =?UTF-8?q?docs:=20frontend=20engineering=20quality?= =?UTF-8?q?=20spec=20(subproject=20=E2=91=A3)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2026-09-15-frontend-quality-design.md | 111 ++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-15-frontend-quality-design.md diff --git a/docs/superpowers/specs/2026-09-15-frontend-quality-design.md b/docs/superpowers/specs/2026-09-15-frontend-quality-design.md new file mode 100644 index 0000000..6eb89df --- /dev/null +++ b/docs/superpowers/specs/2026-09-15-frontend-quality-design.md @@ -0,0 +1,111 @@ +# 前端工程质量（lint/format + 组件测试 + e2e/a11y + bundle 分析）设计 / Frontend engineering quality design + +日期 2026-09-15。分支 `docs/frontend-quality-spec`（设计）；实施分支另建（建议 `feat/frontend-quality`）。状态：已获用户批准（会话内确认）。 + +本 spec 是项目优化四个子项目中的 **④**（其余：② 阅读器改版、③ 功能增强；① 后端健壮性已合入 master，见 `2026-09-14-backend-hardening-design.md`）。④ 与 ② 存在排序耦合：本 spec 先落地 lint/测试/e2e 基建，② 改阅读器时即有规范与回归网可用；阅读器组件测试明确留给 ②。 + +## 目标 / Goal + +1. 引入 ESLint + Prettier，全库一次到位 0 error，进入 `npm run check` 与 CI 门禁。 +2. 建立组件测试基建（testing-library + jsdom），公共组件有少量样板测试；阅读器组件不在本期。 +3. 建立 Playwright e2e 基建，覆盖登录/书架/阅读/书签主流程与 admin 冒烟，含关键页 axe a11y 扫描；发布前手动门禁。 +4. 接入 bundle 分析工具并产出书面审视结论；不做实际优化。 + +非目标见文末「范围外」。 + +## 决策记录 / Decisions + +- 五个方向（lint/format、组件测试、e2e、a11y、bundle 分析）**全部纳入**本期，单 spec、四批次依序落地（方案 A）。用户选定。否决：B（全部基建一次接通再集中修，中间态长、难定位）、C（拆两份 spec 后置 e2e/a11y/bundle，会削弱 ② 的回归安全网）。 +- lint 工具选 **ESLint 9 flat config + Prettier**（独立格式化），否决 Biome（a11y 规则覆盖弱于 jsx-a11y）与 Biome+ESLint 混合（双工具维护成本）。用户选定。 +- lint 严格度：**全库 0 error 一次到位**，不做 baseline 渐进。过噪规则显式降 warn 或关闭，且必须在 config 内注释理由。用户选定。 +- 组件测试深度：**基建 + 少量样板**（2-3 个文件，验证基建可用），阅读器组件测试留给 ② 随新 chrome 一起写。用户选定。 +- e2e 运行方式：**针对 dev compose 栈**（默认 `http://localhost:5173`），`npm run e2e` 为发布前手动门禁，不进 `npm run check`；CI 加独立 job，`workflow_dispatch` 触发。用户选定。否决：进 check（日常摩擦大）、mock 后端（测不到集成层、与真实后端漂移）。 +- a11y 分层：**静态 jsx-a11y（批次 1 随 eslint 接通）+ e2e 关键页 axe 扫描（批次 3）**；不做组件测试层 axe 断言（与 e2e 扫描重叠）。用户选定。 +- bundle 分析：**只接工具 + 出书面结论**（`docs/bundle-review.md`），优化动作不在本期。用户选定。 +- 所有新依赖在 dev 容器内安装并提交 lockfile（AGENTS.md 约束）；Playwright 浏览器二进制仅 dev 容器手动安装（文档化），不进 prod 镜像。 + +## S0 批次总则 / Batches + +四批次依序实施、依序提交，每批独立可回滚： + +- B1 lint/format → B2 组件测试基建 → B3 e2e + axe → B4 bundle 分析。 +- 每批验收底线：`npm run check` 保持绿 + 该批新增命令可跑通。 +- B1 最先，使后续批次新写的测试/e2e 代码天然符合 lint/format 规范。 +- changelog：纯 `frontend/` 改动记 `docs/CHANGELOG_web.md`（双语同条、条目间空行、新版本在上）；`docs/bundle-review.md` 与 README 改动随 B4 同批，不重复记入 `docs/CHANGELOG.md`。 + +## S1 批次 1：ESLint + Prettier / Lint & format + +- 依赖（dev）：`eslint`、`typescript-eslint`、`eslint-plugin-react-hooks`、`eslint-plugin-jsx-a11y`、`eslint-config-prettier`、`prettier`（`prettier-plugin-tailwindcss` 可选，接入与否在实施时以噪音程度定，接则 class 自动排序）。 +- 配置：`frontend/eslint.config.js`（flat config），基线 = `typescript-eslint` recommended + react-hooks recommended + jsx-a11y recommended + `eslint-config-prettier` 收尾关闭格式冲突规则。按目录 override：`e2e/`（B3 产物）用 node 环境 globals、放宽 e2e 惯例规则；`test/`、`*.test.tsx` 允许测试专用 globals。 +- Prettier：`frontend/.prettierrc`（对齐现有代码风格：2 空格、单引号——以实施时对存量代码 diff 最小化为准）+ `.prettierignore`（`dist/`、`node_modules/`、`package-lock.json`、`dist-stats/`）。 +- scripts（`frontend/package.json`）：`lint`（eslint .）、`lint:fix`、`format`（prettier --write .）、`format:check`；`check` 改为 `tsc --noEmit && eslint . && prettier --check . && vitest run && vite build`。 +- 存量修复：全库 eslint error 清零；prettier 首次全量 format 单独成一个 commit（纯格式、无逻辑改动），便于 review 与回滚。 +- 降 warn/关闭的规则须在 `eslint.config.js` 内逐条注释理由（例如 jsx-a11y `click-events-have-key-events` 对阅读器中央点击区可先 warn，② 改版时收严）。 +- CI：frontend job 已跑 `npm run check`，lint 自动覆盖，无需改 workflow。 + +验收：`npm run check` 绿；`eslint .` 0 error；`prettier --check .` 0 diff。 + +## S2 批次 2：组件测试基建 / Component testing + +- 依赖（dev）：`jsdom`、`@testing-library/react`、`@testing-library/user-event`、`@testing-library/jest-dom`。 +- 环境分层：存量 `frontend/test/*.test.ts` 纯逻辑测试保持 node 环境不动；组件测试用 `*.test.tsx` 后缀，vitest `environmentMatchGlobs`（或等价的项目级配置）将 `**/*.test.tsx` 路由到 jsdom；`vitest run` 一次全跑，不加新 script。 +- setup：`frontend/test/setup.ts` —— 注册 jest-dom matchers、自动 cleanup、补 jsdom 缺口 polyfill（`ResizeObserver`、`Element.scrollIntoView`、pointer events），radix 组件在 jsdom 下的已知坑一次配好。 +- 放置约定：组件测试与组件同目录 colocate（如 `src/components/ui/button.test.tsx`）；纯逻辑测试维持 `frontend/test/`。约定写入 B1 的 eslint override 与本 spec 附录（S6）。 +- 样板测试（3 个，目的是验证基建而非追覆盖率）： + 1. `src/components/ui/button.test.tsx`：渲染、variant class、点击回调； + 2. `src/components/ui/dialog.test.tsx`：radix Dialog 在 jsdom 下开合、焦点管理（验证 polyfill 方案成立——② 的 chrome 迁移依赖 Sheet/Popover 等同类原语）； + 3. `src/components/theme-toggle.test.tsx`：真实业务组件，验证 localStorage/主题上下文可测。 +- 阅读器组件（`src/readers/{Cbz,Epub,Pdf,Text}Reader.tsx`）本期不写组件测试；spec 显式约定 ② 改版时随新 chrome 补齐并作为行为回归网。 + +验收：`npm run check` 绿；3 个样板测试通过；存量 9 个逻辑测试不受影响。 + +## S3 批次 3：e2e + a11y 运行时扫描 / e2e & axe + +- 依赖（dev）：`@playwright/test`、`@axe-core/playwright`；浏览器仅装 chromium（dev 容器内 `npx playwright install --with-deps chromium`，命令写入 README 与本 spec）。 +- 结构：`frontend/e2e/*.spec.ts` + `frontend/playwright.config.ts`；`baseURL` 取环境变量 `E2E_BASE_URL`，默认 `http://localhost:5173`（dev compose 栈 web 端口）。**不由 Playwright 管理 server 生命周期**——前提是手动起好 dev 栈（`deploy/docker-compose.dev.yml`），连不上直接失败并给出提示。 +- 测试数据：全部走 HTTP API 准备（注册/登录、上传 `e2e/fixtures/` 下的小 CBZ 文件），不直接碰 PG/Redis；登录态用 Playwright `storageState` 复用，避免每条用例重复登录。 +- 用例（2 个 spec，不追全量）： + 1. `e2e/auth-shelf.spec.ts`：登录 → 书架可见 → 进入 CBZ 书 → 翻页 → 加入书签 → 退出登录； + 2. `e2e/admin-smoke.spec.ts`：admin 登录 → 建库 → 触发扫描 → 扫描入口/状态可见（冒烟级；扫描状态 API 属 ③，此处只验证现有行为）。 +- axe 扫描：在关键页面（登录页、书架页、阅读器 chrome 展开态）插入 `@axe-core/playwright` 扫描步骤。门禁分级： + - critical/serious 违规 = 测试红；moderate/minor 仅输出报告不阻断； + - 存量 critical/serious 违规本批内修掉（多为属性级小修，记 `CHANGELOG_web.md`）；确属将被 ② 重写的旧阅读器 chrome 的问题，允许在测试内逐条显式 allowlist 豁免，每条注释指向 ②。 +- scripts：`e2e`（playwright test）、`e2e:ui`（playwright test --ui，开发调试用）。**不进 `npm run check`**。 +- CI：`ci.yml` 新增独立 `e2e` job，仅 `workflow_dispatch` 触发，job 内自起 PG/Redis/api/web（service 容器 + build），runner 未就绪期间形同文档，就绪后零改动可用。 +- eslint：`e2e/` 目录 override（node globals、测试文件规则）。 + +验收：dev 栈起后 `npm run e2e` 绿（2 spec + 关键页 axe 无未豁免的 critical/serious）。 + +## S4 批次 4：bundle 分析 / Bundle analysis + +- 依赖（dev）：`rollup-plugin-visualizer`；接入方式为 `vite.config.ts` 内按条件启用（如 `ANALYZE=1` 或 `--mode analyze`），产物输出到 `frontend/dist-stats/`（加入 `.gitignore` 与 `.prettierignore`，不进 dist 发布产物）。 +- script：`analyze`。 +- 审视结论文档：`docs/bundle-review.md`（英中双语，随批 commit）。内容：各大依赖（pdfjs-dist、epubjs、marked、dompurify、react-query、radix-ui、lucide-react 等）的体积占比、当前是否已懒加载/分包、可优化点清单；每个优化项标注建议归属（② 或后续 spec），**本期不动代码**。 +- README：`docs/README.md` 与 `docs/README_zh.md` 同批补充新增命令（lint/format/analyze/e2e/e2e:ui）与本地门禁清单更新，保持双语内容等价（AGENTS.md 约束）。 + +验收：`npm run analyze` 可出报告；`docs/bundle-review.md` 提交；README 双语等价。 + +## S5 整体验收 / Definition of Done + +1. `npm run check` 绿 = tsc + eslint 全库 0 error + prettier check + vitest（9 存量逻辑测试 + 3 新组件样板）+ build； +2. dev 栈起后 `npm run e2e` 绿； +3. `npm run analyze` 可出报告，`docs/bundle-review.md` 已提交； +4. `docs/CHANGELOG_web.md` 双语条目齐全；`docs/README.md` / `README_zh.md` 等价更新； +5. CI：frontend job 无需改动即覆盖 lint；新增 e2e job（workflow_dispatch）就绪； +6. lockfile 已提交；prod 镜像不新增任何本期依赖。 + +## S6 范围外 / Out of scope + +- 阅读器组件的任何测试与改动（→ ② 阅读器改版）； +- bundle 体积的实际优化动作（仅出结论清单）； +- moderate/minor 级 a11y 修复（仅输出报告）；组件测试层 axe 断言； +- Playwright 浏览器进 prod 镜像；e2e 进 `npm run check`； +- 后端任何改动（含扫描状态 API → ③）； +- `components/ui.ts`（deprecated）与 `components/icons.tsx` 的清理（→ ②，本期 lint 仅按现状规则放行或豁免，不做删除）。 + +## 附录：测试放置与命名约定 / Appendix: test conventions + +- 纯逻辑测试：`frontend/test/.test.ts`（现状不变，node 环境）； +- 组件测试：与被测组件同目录 `.test.tsx`（jsdom 环境）； +- e2e：`frontend/e2e/.spec.ts`，fixture 放 `frontend/e2e/fixtures/`； +- 测试命名：`describe` 用被测单元名，`it` 用行为描述句。 From 24c5d4253195639ab352e9f5de84deecbfcfa593 Mon Sep 17 00:00:00 2001 From: XingfenD Date: Tue, 15 Sep 2026 11:12:38 +0800 Subject: [PATCH 02/22] docs: frontend quality implementation plan (16 tasks, 4 batches) --- .../plans/2026-09-15-frontend-quality.md | 1185 +++++++++++++++++ 1 file changed, 1185 insertions(+) create mode 100644 docs/superpowers/plans/2026-09-15-frontend-quality.md 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`）； +- 书架卡片：外层 ` - diff --git a/frontend/src/components/Cover.tsx b/frontend/src/components/Cover.tsx index 8472df0..f606464 100644 --- a/frontend/src/components/Cover.tsx +++ b/frontend/src/components/Cover.tsx @@ -5,7 +5,11 @@ import { btn, formatBadge } from "./ui"; import { TriangleAlert } from "lucide-react"; export function useAuthedImage(url: string | undefined): { src: string; failed: boolean; retry: () => void } { - const [state, setState] = useState<{ key: string; src: string; failed: boolean }>({ key: "", src: "", failed: false }); + const [state, setState] = useState<{ key: string; src: string; failed: boolean }>({ + key: "", + src: "", + failed: false, + }); const [nonce, setNonce] = useState(0); const key = (url ?? "") + "#" + nonce; @@ -30,10 +34,10 @@ export function Cover({ book, className }: { book: Book; className?: string }) { const { src, failed, retry } = useAuthedImage(book.cover_url); if (!book.cover_url || failed) { return ( -
- {Array.from(book.title)[0] ?? "?"} +
+ + {Array.from(book.title)[0] ?? "?"} + {book.format} {failed && (
diff --git a/frontend/src/components/Toaster.tsx b/frontend/src/components/Toaster.tsx index 9678fad..1d26d86 100644 --- a/frontend/src/components/Toaster.tsx +++ b/frontend/src/components/Toaster.tsx @@ -36,7 +36,11 @@ export function Toaster() { t.kind === "ok" ? "border-border" : "border-destructive/40" }`} > - {t.kind === "ok" ? : } + {t.kind === "ok" ? ( + + ) : ( + + )} {t.text}
))} diff --git a/frontend/src/components/app-shell.tsx b/frontend/src/components/app-shell.tsx index 8e7b4f5..4e62aaa 100644 --- a/frontend/src/components/app-shell.tsx +++ b/frontend/src/components/app-shell.tsx @@ -4,7 +4,14 @@ import { Link, NavLink, Outlet, useLocation } from "react-router-dom"; import { api } from "@/api/client"; import { useAuth } from "@/auth/AuthContext"; import { Button } from "@/components/ui/button"; -import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger } from "@/components/ui/dropdown-menu"; +import { + DropdownMenu, + DropdownMenuContent, + DropdownMenuItem, + DropdownMenuLabel, + DropdownMenuSeparator, + DropdownMenuTrigger, +} from "@/components/ui/dropdown-menu"; import { Separator } from "@/components/ui/separator"; import { ThemeToggle } from "./theme-toggle"; import { cn } from "@/lib/utils"; @@ -12,7 +19,11 @@ import type { ReactNode } from "react"; function Brand() { return ( - + @@ -57,7 +68,10 @@ export function AppShell() { - {user?.username}{isAdmin ? " · admin" : ""} + + {user?.username} + {isAdmin ? " · admin" : ""} + {isAdmin && ( <> @@ -88,14 +102,25 @@ export function AppShell() {