# HANDOFF — book-comic-library / feat/ui-redesign

交接时间：2026-09-08。上一会话在 **phase-1 最终评审修复波派发刚发出即被取消** 处中断。工作树干净，HEAD = `7e08478`（分支 `feat/ui-redesign`）。

## Goal

个人书/漫画库（Go 后端 + React 前端，docker/podman compose 部署）的 `feat/ui-redesign` 分支承载两件事，均已按 SDD（subagent-driven-development）流程开发：

1. **CBZ 章节化连续阅读**（已完成并验收 ✅）——一章图片=一段连续长卷、默认滚动锁章（只能按钮/目录/滑条/书签切章）、连读开关、锁章时预渲染 0–3 章（默认 2）切章零白屏；移除旧 连读/整页/适高 三档。
2. **全站现代化重构 phase 1**（代码完成，最终评审待修复 ⏳）——shadcn/Radix 设计系统 + light/dark 双主题 + 应用壳 + 登录/书架/admin 页从零重做；**阅读器（/book/:id 四 reader）本期刻意不动**，属 phase 2。

最终目的：本分支功能就绪后由用户决定合回 master / 开 PR（上一会话已问过一次，用户未选）。

## 关键文档（先读这些）

- Spec：`docs/superpowers/specs/2026-09-08-cbz-chapter-continuous-reading-design.md`、`docs/superpowers/specs/2026-09-08-modern-redesign-shadcn-design.md`
- Plan：`docs/superpowers/plans/2026-09-08-cbz-chapter-continuous-reading.md`（已执行完）、`docs/superpowers/plans/2026-09-08-modern-redesign-phase1.md`（Task1–8 已执行完）
- SDD 账本/评审包/各任务报告：`.superpowers/sdd/2026-09-08-modern-redesign-phase1/`（`progress.md` 记录任务完成与 parked minors；各 `task-N-report.md` 是实现证据；`review-*.diff` 是评审包）。前一计划账本已删除（收尾完成）。
- 项目规约：`AGENTS.md`（分支命名/CHANGELOG 英中相邻行/npm 依赖必须容器内安装/渲染配置来自 tpl 等）。

## Current Progress

- 分支领先 master 约 33 个 commit（`git log --oneline master..HEAD`）。与本 handoff 相关的段：`bba82e5..e5dacc0` CBZ 功能、`2721df8` 上传 toast 修复、`ee676c2..7e08478` phase-1（11 commits，每个都过了任务级评审+修复轮）。
- Phase-1 八个任务全部 DONE 且任务评审干净；`npm run -s check`（tsc+vitest 37+build）绿；Task 8 的 playwright 6 格矩阵（3 视口 × 2 主题）全过。
- **中断点**：phase-1 的**最终整分支评审**判 “With fixes”（1 Critical + 7 Important + 2 Minor 入波），修复子代理刚派发即被取消——**修复波零进度，待重做**（清单见 Next Steps 1，全部裁决细节在下文）。
- 之后收尾流程未走：SDD 收尾（删本计划 workspace）+ 分支合并方式询问。

## What Worked

- **SDD 流程本身**：任务简报（`task-brief` 脚本）+ 实现子代理 + 评审包（`review-package`，别用 HEAD~1）+ 限定 re-review，两轮修复都收敛干净；账本防上下文丢失。
- **环境事实**：dev 栈= podman 别名 docker；容器名 `booklib_api_1 / booklib_web_1 / booklib_postgres_1 / booklib_redis_1`（下划线）；一切 npm/vitest 走 `docker exec -w /app booklib_web_1 …`（node_modules 只在容器里）；后端测试 `docker exec booklib_api_1 sh -c 'cd /app && go vet ./... && go test -p 1 -count=1 ./...'`；psql 走 postgres 容器 `printenv POSTGRES_USER/POSTGRES_DB`；前端 :5173 代理 /api（api 的 8080 不映射宿主！宿主 curl 只能打 5173）。
- **登录凭据（dev）**：admin / `xfqcmNXrTz240dmQiTHJwepc`（= api 容器 `ADMIN_PASSWORD`）。重建 admin 的方法：清空 users 表 + `docker restart booklib_api_1`（seed 仅在 0 用户时建）。
- **测试素材**：`deploy/api/storage/test/test_manga.zip`（4 章 32 页，ch4 长 20 页，= 宿主 storage 映射容器 `/data/books`）、`test_flat.zip`（扁平 6 页）。生成脚本逻辑在 `task-8-report.md` 时代记录过，必要时可再造。
- **playwright-cli**（PATH 里就有）做 UI 验收很顺：`open/goto/snapshot/find/click/fill/press/mousewheel/resize/upload/eval/close`；`press` 键名小写；`fill` 到 range input 不触发 pointerup（会留下 scrub 假象）；隐藏 FileList 用 `upload` 前先 click 触发 chooser；产物目录 `.playwright-cli/` 用完 `rm -rf`（未 gitignore）。
- shadcn CLI 生成 13 原语、`components/ui/` 与旧 `components/ui.ts` 并存过渡、URL-as-state（?lib/?q/?sort/?group）都成立。

## What Didn't Work（别重蹈）

- **shadcn CLI 在生成文件里写 `import { cn } from "cn"`**（误装名为 cn 的垃圾包）→ 必须批量改成 `@/lib/utils` 并卸载。
- **本 TS 版本拒绝 `baseUrl`** → tsconfig 只用 `"paths": {"@/*": ["./src/*"]}`（无 baseUrl）；vite 用 `"@": "/src"`；vitest 用 `new URL("./src", import.meta.url).pathname`。
- **计划内嵌代码的教训**（评审抓到，写计划时要自查）：`createContext` 不能包在 module 级 `useMemo` 里；`FileList` 是活引用（`input.value=""` 清空后 `.length` 归 0 → 上传 toast 报 0 的根因，`Array.from` 先快照）；Radix `DropdownMenuItem` 一律用 `onSelect`（onClick 键盘路径不触发）；react-router **NavLink 的 isActive 只看 pathname 忽略 search**（导致侧栏 `?lib=N` 全激活的 C1，见下）。
- psql `-c "多语句"` 出现过只部分生效/难核对 → 逐条 `-c`。
- 最终评审的修复清单若一次性派发被取消了：可以照单重发，内容仍然有效（HEAD 未动）。

## Next Steps

1. **重发 phase-1 最终评审修复波（一个子代理、一个 commit）**，全部裁决如下（评审原文在 `.superpowers/sdd/2026-09-08-modern-redesign-phase1/` 会话记录中，此处为完整清单）：
   - **C1** `app-shell.tsx`：侧栏库筛选 NavLink 全部同时 active（isActive 忽略 search）。裁决：删掉侧栏「全部」项（书架即全部）；NavItem 显式传 `active`——书架= `pathname==="/" && !sp.get("lib")`，库项= `sp.get("lib")===String(l.id)`，admin 项按 pathname；移动端 Tab「书架」链到 `/`（去掉 `?lib=0`）。
   - **I1** md 图标栏链接无 accessible name（label `hidden lg:inline` 出 a11y 树）→ 给链接/按钮加 `aria-label`。
   - **I2** 书卡打开按钮 `focus-visible:outline-none` 且无替代焦点环 → 补 ring/outline（`Shelf.tsx:30`）。
   - **I3** 浅色主题 `text-accent`（oklch 0.68 朱橙）作小字不达 AA → 新增 `--accent-strong`（light≈oklch(0.55 0.17 46)；dark≈0.72）映射 `--color-accent-strong`，文本场景换用；顺带补 `--destructive-foreground` token，替换 Shelf/Users 两处手搓 `bg-destructive text-primary-foreground`。
   - **I4** 触屏摸不到卡 ⋯ 菜单（hover-only opacity）→ `<md` 常显：`opacity-100 md:opacity-0 md:group-hover:opacity-100 md:focus-within:opacity-100`。
   - **I5** Shelf 三处 DropdownMenuItem `onClick` → `onSelect`；删除项优先用生成件 `variant="destructive"`（先查本地 dropdown-menu.tsx 是否支持，不支持则留 className 并记一笔）。
   - **I6** lg 侧栏永远无 “BookLib” 字标（Brand 恒 compact）→ label `hidden lg:inline`。
   - **I7** 壳三处半透明漂移（card/60、card/90、background/90）→ 统一 `bg-background/85 backdrop-blur`。
   - **M-a** `ui.ts` 的死 re-export `formatSize`（无 importer，先 grep 确认）→ 删除（保留 btn/btnGhost/formatBadge+FORMAT_BADGE）。
   - **M-b** `docs/CHANGELOG_web.md` phase-1 条目里「icon-adorned inputs/图标输入框」措辞与最终登录不符 → 原地改（EN/ZH 保持相邻行规约）。
   - 修复波验证：tsc+`npm run -s check`；playwright 复核 C1（建两个空库 `fixw/fixw2` 即可验高亮，不必等 scanner）、I2/I4 焦点与触屏可见、I3 截图、主题键盘选择；随后删测试库（psql）+ 清 `.playwright-cli`。commit 建议：`fix(web): active lib highlight, rail a11y names, card focus ring, AA accent + destructive tokens, touch-reachable menu, brand wordmark, chrome unify`。
   - **然后一次限定 re-review**（`review-package PLAN 7e08478 <newHEAD>`），parked minors 由终审者复核（账本 `progress.md` 里有清单）。
2. Phase-2 遗留票（不急，另立 spec）：阅读器 chrome 迁入设计系统（翻页/CBZ 章锁/连读/预读/书签逻辑与 localStorage 键原样保留；纸/米/夜 主题重映射语义变量并与全局 light/dark 定联动）；SectionHead 粘性偏移、tooltip 化图标栏、移动端库筛选 sheet、PWA meta dark 变体、toast 与底 Tab 重叠、明暗下 FORMAT_BADGE 可读性。
3. 收尾：最终评审干净后删 `.superpowers/sdd/2026-09-08-modern-redesign-phase1/`（账本先补一行 Task 8 完成 + 修复波记录），再问用户分支去向（merge master / PR / 保持）。
4. 顺带留意（非阻塞）：空库 `l` 使 api 日志每分钟一条 `scan rejected`（上传或删库行即愈）；周期 scanner 对缺目录只 reject 不清扫。

## 常用命令速查

```bash
docker exec -w /app booklib_web_1 npm run -s check
docker exec -w /app booklib_web_1 npx vitest run test/shelf.test.ts
docker exec booklib_api_1 sh -c 'cd /app && go vet ./... && go test -p 1 -count=1 ./...'
U=$(docker exec booklib_postgres_1 printenv POSTGRES_USER); D=$(docker exec booklib_postgres_1 printenv POSTGRES_DB)
docker exec booklib_postgres_1 psql -U $U -d $D -c 'select * from libraries'
SDD=.superpowers/sdd/2026-09-08-modern-redesign-phase1   # task-brief/review-package/sdd-workspace 脚本在 superpowers 技能目录 scripts/ 下
```