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）流程开发：

CBZ 章节化连续阅读（已完成并验收 ✅）——一章图片=一段连续长卷、默认滚动锁章（只能按钮/目录/滑条/书签切章）、连读开关、锁章时预渲染 0–3 章（默认 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

重发 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 里有清单）。
Phase-2 遗留票（不急，另立 spec）：阅读器 chrome 迁入设计系统（翻页/CBZ 章锁/连读/预读/书签逻辑与 localStorage 键原样保留；纸/米/夜主题重映射语义变量并与全局 light/dark 定联动）；SectionHead 粘性偏移、tooltip 化图标栏、移动端库筛选 sheet、PWA meta dark 变体、toast 与底 Tab 重叠、明暗下 FORMAT_BADGE 可读性。
收尾：最终评审干净后删 .superpowers/sdd/2026-09-08-modern-redesign-phase1/（账本先补一行 Task 8 完成 + 修复波记录），再问用户分支去向（merge master / PR / 保持）。
顺带留意（非阻塞）：空库 l 使 api 日志每分钟一条 scan rejected（上传或删库行即愈）；周期 scanner 对缺目录只 reject 不清扫。

常用命令速查

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/ 下

9.4 KiB Raw Blame History Unescape Escape