# TODOS > 由 /plan-eng-review(2026-08-04,watch-folder 方案评审)首次生成。格式:What / Why / Pros / Cons / Context / Depends。 ## 1. LibraryShell.tsx 拆分(存量债) - **What:** 把 1240+ 行的 `next-app/src/app/library/_components/LibraryShell.tsx` 拆到 <800 行——导入编排、溢出菜单、可用性展示各自成模块。 - **Why:** 全局编码规则红线是 800 行,当前已超 55%;每个新功能都在往里堆(watch-folder PR-1 又 +~10 行)。现在拆比半年后拆便宜得多。 - **Pros:** 后续 library 迭代全部受益;接线层可测性改善;审查负担下降。 - **Cons:** 纯重构 PR,无用户可见价值;碰面大,需要完整回归(e2e library 两条 spec + 手测导入/播放链路)。 - **Context:** 2026-08 watch-folder 评审中发现的存量债,与该 feature 无阻塞关系。拆分时天然的切缝:handleAddFolder 导入编排、HudOverflowMenu items 构造、availability/probe 展示逻辑、ImportDrawer/pill 状态机。遵守"结构性与行为性改动分离"原则,单独 PR。 - **Depends on / blocked by:** 建议在 watch-folder PR-1/PR-2 合并后动手,避免同期冲突。 ## 2. library 逻辑层测试债回填 - **What:** 给 `enumerator.js` / `fileHandleStore.js` / `useFileHandles.js` / `importPipeline.js` 全链路补单测。PR-1 只补被改到的部分(reuse 分支回归 + touchSeries + useImport 默认行为)。 - **Why:** 代码里预留的 DI seam(`useImport` 的 `{db, dandan, hashPool}`)从未被使用;全局规则要求 80% 覆盖率。 > 事实更正(2026-08-22 评审):本条原写「整个 library 逻辑层只有 `buildLibraryMatchResult.test.js` > 一个测试文件」——已不成立。`_services/` 下现有 7 个测试文件(`rescanController`/`rematchPayload`/ > `loadSeriesRows`/`rescanService`/`folderWatcher`/`resolveSeriesBinding`/`resolveMergedIds`)。 > 仍缺的是 `enumerator.js` / `fileHandleStore.js` / `useFileHandles.js` / `importPipeline.js` 这条链。 - **Pros:** PR-2(改管线核心)/PR-3(observer)都有安全网;PR-1 会建好 fake DirectoryHandle(async-iterator 夹具)和 fake repo 层,回填时直接复用,边际成本低。 - **Cons:** 纯测试 PR,管线分支多(matchCache 命中/过期、reuse/new/ambiguous、跨文件夹 merge),工作量不小。 - **Context:** 测试跑法是 `bun test` 纯逻辑测试(无 RTL/jest/fake-indexeddb);仓库惯例是逻辑抽纯函数单测(authForm/registerFlow 模式)。importPipeline 可经 fake repos 测 processCluster,不需要真 Dexie。 - **Depends on / blocked by:** watch-folder PR-1 落地(复用其测试夹具)。 ## 3. Dexie schema v6:fileRefs 加 [libraryId+relPath] 索引 - **What:** `next-app/src/lib/library/db/db.js` 追加 version(6),fileRefs 索引串在现有基础上追加 `[libraryId+relPath]`。 - **Why:** watch-folder 用全局 (relPath,size) 基线 + toArray 全表扫,当前规模(数百行)毫秒级完全够用;索引只在库上万行、或实现"relPath 消失条目清理"功能时才有收益。 - **Pros:** 加的时候只需一次 version bump,索引-only 变更无需 upgrade 函数;为失效条目清理铺路。 - **Cons:** 现在加是无收益 schema 变更,白承迁移风险。 - **Context:** ⚠️ 届时注意:Dexie 的 `version(N).stores({fileRefs})` 是整表替换不是合并——必须重声明**完整**索引串:`'id, episodeId, hash16M, matchStatus, [libraryId+matchStatus], *libraryIds, [libraryId+relPath]'`(2026-08 评审验证时确认,db.js 当前无裸 libraryId 索引)。 - **Depends on / blocked by:** 触发条件:库规模上万行,或"文件消失处置"产品决策落地为清理功能。 ## backfill 队列的暂停 / 恢复控制 **What** — 给 `/admin` 的「中文简介」区块加一对暂停/恢复按钮，作用于 `description_backfill` 队列。 **Why** — 首次回填要连续跑约 31 小时。这期间如果 bgm.tv 出问题、或者发现写入有误想紧急刹车，目前唯一的手段是 SSH 上 prod 改数据库、或者重启容器——而重启会把在线富化一起停掉。独立队列的价值有一半就在「能单独停」，现在这半个价值还没接出来。 **Context** — P3 已经把 sweep 放进了独立队列（`internal/queue/control.go` 的 `DescriptionBackfillQueueName`），river 的 `QueuePause` 机制也已经在生产跑（V3 heal-CN 在用）。所以这件事是接线不是造轮子： - 后端：`queue.PauseV3` / `ResumeV3` 旁边加一对同形函数，改队列名即可 - 前端：照抄 `_actions/enrichment-queue.ts` 里的 `pauseHealCn` / `resumeHealCn` - 位置：`EnrichmentBar` 的「中文简介」区块已经留好了地方 **Depends on / blocked by** — 无。dashboard 只读部分（本次 PR）落地后即可做。 **为什么这次没做** — 它属于运维能力，不属于「看见进度」这个需求。分开做两边都更干净。 **2026-09-08 更新：后端已落地，只剩前端按钮。** river 注册表那轮把这条的后端做完了，而且比这里设想的更宽：不是「加一对同形函数」，是一组通用的 `queue.PauseQueue / ResumeQueue / QueuePaused / StatusAll`，队列名按注册表白名单校验，八条专用队列全部可停可看。HTTP 面是 `POST /api/admin/queues/{name}/pause`、`/resume` 和 `GET /api/admin/queues`。 白名单显式排除 river 的 `default`——那条队列同时装着 V1、V2、warm_season、orphan_scan，停它就等于停掉页面在等的富化；river 的 `"*"` 通配同样被拒。 未知名字返回 400 而不是 500（操作者要了个不存在的东西，和 river 挂了是两回事）。 顺带修掉一个：`PauseHeal` / `ResumeHeal` 在 `QueueCtrl` 为 nil 时会返回 `200 {"paused":true}` 却什么也没暂停。现在返回 503。 **还剩什么** — 只有前端：`EnrichmentBar` 的「中文简介」区块加按钮，照抄 `_actions/enrichment-queue.ts` 里的 `pauseHealCn` / `resumeHealCn`， 把路径换成 `/api/admin/queues/description_backfill/pause`。`GET /api/admin/queues` 已经把可停队列名和各自的暂停态一起返回，前端不需要硬编码队列列表。 ## anime-relations:字幕组连番号的精确重定向表 - **What:** 接入 [`erengy/anime-relations`](https://github.com/erengy/anime-relations),把字幕组连续编号的 续季集号精确重定向到该季的 1..N,补上启发式归一覆盖不到的场景。 - **Why:** 本地库的显示层归一(`normalizeEpisodeNumbers`)是个保守推断——只在「本地最小集号 已越过本季集数」且「构成连续段」时才平移。文件没下全、一季拆两个 cour、跨季混在同一 文件夹这三种它会主动不动手,结果仍是网格前半截是死格子。 - **Pros:** 规则表是 **public domain**(比 `go-api/data/hant/` 那份 CC BY-SA 还干净,不存在 AGPL 污染顾虑);2026-08 仍在维护;**规则里第三个 id 直接就是 AniList id**,正好是 `anime_cache` 的主键,不需要中间跳转;约 1,000 条规则,压缩后几十 KB。 - **Cons:** 引入一个需要定期同步的外部数据集——和 `refresh-bgm-map` 同一个形状,而那个 workflow 曾静默失败一个月无人察觉(见 issue #61/#62 的修复)。同步失败必须有告警, 否则规则表会悄悄过期。 - **Context:** 规则语法 `MAL|Kitsu|AniList:范围 -> MAL|Kitsu|AniList:范围`,`!` 后缀表示 同时生成一条自指规则,`~` 重复源 id,`?` 未知。两种接入方式:(a) 数据烤进构建产物, 照 `go-api/data/hant/` 的模式——独立目录 + 独立 license 文件;(b) go-api 加一个 `/api/anime/relations` 端点定期拉取并按 anilistId 索引,省客户端体积但多一次往返。 备选数据集 `eliasbenb/PlexAniBridge-Mappings`(MIT,每日自动生成,AniList 主键)覆盖更全, 但它解决的是 TVDB 季结构对齐而不是字幕组连番号,对这个场景是间接的,**不作首选**。 - **Depends on / blocked by:** 触发条件 = 显示层归一上线一个月后,统计仍有可观比例的 卡片集号不对。在那之前不要动——先拿覆盖率数字。 ## 导入抽屉:整个哈希阶段只显示一个静止的「准备中…」 - **What:** 拆掉 `useImport.js` 哈希阶段的 `Promise.all` 屏障,改成边算边吐行(下游本来就有 `running` 状态);并在枚举结束时就把文件总数交给进度条,不必等哈希做完。 - **Why:** 现在第一行要等**所有**文件都哈希完才出现,而抽屉的空状态条件就是 `rows.length === 0`, 所以整个哈希阶段界面是一个静止的「准备中…」,进度显示 `0 / —` ——**分母其实枚举完就知道了**。 用户无法区分「在算」和「卡死」,唯一的判断办法是去看后端日志确认还没进匹配阶段。 实测有人因此以为导入挂了。这是纯 UI/编排问题,管线本身是对的。 - **Pros:** 首行出现时间从「全部哈希完」降到「第一个文件哈希完」;进度条真的会动; 不需要改哈希本身,也不需要动匹配逻辑。 - **Cons:** 边吐边算意味着行的顺序不再是枚举顺序,分组渲染要能接受乱序插入; 失败重试的语义要重新想一遍(现在是屏障之后统一处理)。 - **Context:** 屏障在 `next-app/src/app/[lang]/library/_hooks/useImport.js` 的 `await Promise.all(items.map(...pool.hash(item.file)))`;空状态在 `_components/ImportDrawer.tsx` 的 `rows.length === 0` 分支。 哈希池并发被 `lib/library/hashPool.js` 的 `MAX_POOL_SIZE = 4` 卡死,跟机器核数无关, 所以耗时大致是 `文件数 ÷ 4 × (读前 16MB + MD5)`,走 File System Access API + Worker。 **注意 `MAX_POOL_SIZE` 是刻意的上限,不要顺手调大** —— 先确认它当初为什么被压到 4。 - **Depends on / blocked by:** 无。与集数显示那条线无关,可独立做。 ## go-api 的 Dockerfile 健康检查打的是一个不存在的路由 - **What:** `go-api/Dockerfile` 的 `HEALTHCHECK` 打 `/healthz`,但服务只注册了 `/health` (`cmd/server/main.go`)。改 Dockerfile 里的路径即可。 - **Why:** 那条 HEALTHCHECK **从来没成功过**,一直在 404。compose 起的容器之所以显示 healthy, 是因为 `docker-compose.yml` 用 `/health` 覆盖了它。裸 `docker run` 这个镜像会永远 unhealthy, 任何依赖镜像自带健康状态的编排(k8s、swarm、别人 pull 下来跑)都会拿到错误答案。 副作用是每 2 秒往日志里写一条 404,把真实请求淹掉——排查时很误导。 - **Pros:** 一行改动;顺带让日志干净。 - **Cons:** 无。唯一要小心的是别反过来把路由改成 `/healthz` —— compose、 部署脚本和文档都已经用 `/health`,改路由要同步改一圈,改 Dockerfile 只动一处。 - **Context:** 2026-08-22 本地起全栈时发现。`grep -rn 'healthz' go-api/` 能看到全部引用。 - **Depends on / blocked by:** 无。 ## 匿名访客的访问量,后台完全看不到 - **What:** 从 nginx access log(或 Cloudflare Analytics / Logpush)离线统计未登录访客的 页面访问量,写进一张日聚合表,在 `/admin` 的活跃度面板里单独开一块显示。 - **Why:** 活跃度面板每一个数字都按 `user_id` 统计 —— DAU/WAU/MAU、访问天数、留存, 全部只覆盖已登录访问。而本站是 SEO 驱动的目录站,**流量大头是没有登录的**, 所以后台看到的是一小块,不是全景。读到「今天 41 人活跃」时很容易忘掉这件事, 尤其是半年以后。 - **Pros:** 请求路径上零成本 —— 日志本来就在产生,统计是离线的;Cloudflare 那一侧 连边缘缓存命中的请求也能看见,而源站日志永远看不到那部分(命中时请求到不了源站)。 - **Cons:** 需要一个日志解析作业(river 定时);区分不了爬虫和真人,得自己维护 UA 过滤, 而这份过滤会持续腐烂;CF Logpush 属于付费套餐,要先确认账号情况。 - **Context:** 这个缺口本来打算用一个浏览器 beacon(`POST /api/activity/beacon`)来填, 在 2026-08-28 的评审里被砍掉了 —— 原因是 `/anime/*` 走 CF 边缘缓存,命中时请求根本 到不了源站,而 beacon 是 POST(CF 从不缓存 POST),等于把「零源站负担」变成 「每次真人浏览一个必然打到源站的请求」;它还会占用 `isPublicReadExempt` 只放行 GET 的那个 per-IP 限流额度(1 rps / burst 60),可能把翻页快的读者 429 掉。 日志路线是同一个需求的零请求成本实现。迁移 `0025_user_activity.up.sql` 的头注释里 也写了同一句结论,两处可以互相印证。 - **Depends on / blocked by:** 无。与活跃度面板已有的部分完全独立,可以随时单独做。 ## bangumi 绑定决策无法从存储状态重建 - **What:** 在 `anime_cache` 加一个 text 列(暂名 `bgm_match_name`),让 `UpdateBangumiV1` 在绑定成功时把当时选中的 Bangumi 侧原名 `best.Name` 一并写下来。 然后基于它做一次存量绑定审计。 - **Why:** 现在绑定成功只写回 `bgm_id` / `title_chinese` / `bgm_match_source` 三个字段, **Bangumi 侧的原名从来没被存下来**,全库也没有这个列。后果是一条已经存在的绑定, 事后没办法回答「当时是拿哪个标题匹配上的」—— 也就没办法判断它对不对。 `title_chinese` 只是部分代理:它在 `NameCN` 为空或等于 `Name` 时是 NULL, 而且后续 v2/v3 富化可能已经改写过它。这是「bgm 绑定 41% 无来源」那笔债的 结构性原因之一 —— 不是没记来源,是就算记了也无法复盘。 - **Pros:** 一个列 + 一个 UPDATE 字段,约 10 行;从此每条新绑定都可复盘, 存量审计从「不可能」变成「一条 SQL」。 - **Cons:** 需要一条 migration(本仓已到 0026);按项目惯例写 migration 前要先走 `database-migrations`;而且价值要到真的做存量 sweep 那一期才兑现,单独做收益为零。 - **Context:** 2026-08-28 的 `/plan-eng-review` 里发现(季号信号方案的 D3)。当时刻意 没有并进那个 PR —— 那个改动是单文件纯逻辑、无 schema 变更、前向 only,加一条 migration 会改变它的风险类别,而本仓 `description_cn` 那一轮用了 0014→0015→0016 三次才定下来。 另一个必须一起想的点:`bangumi_v1` 只处理 `bangumi_version = 0` 的行,成功后置 1 永不回头,所以存量行不会自己重新评估,审计和纠正都得单独写 sweep。 - **Depends on / blocked by:** 无技术前置。建议与存量绑定 sweep 同期做,否则加了列也没人读。 ## 分割放送会 50% 概率绑错,而且标成高置信 - **What:** 给 `internal/bangumi` 的候选打分补上季号信号。**要先解一个包依赖环。** - **Why:** `NormalizeTitle` 的 `seasonSuffixReplacer` 把 `season2..9` / `第2期..第9期` / `ii,iii,iv` / `part2..5` / `ova,movie` 全删掉,之后季号和格式**不再作为任何分量出现** (`ScoreCandidate` 只有 titleSim / yearScore / epsScore 三项)。分割放送下 S1 和 S2 同年 同集数时两个候选得分**完全相同**,argmax 退化成「列表里谁在前面」,而档位规则 1 (`ts≥0.95 && ys≠0`)立即命中 → 权威绑定。同一个陷阱对「剧场版 vs TV 版」也成立。 - **Pros:** 直接消掉一整类静默错绑;`titlematch` 已有 `ExtractMarker`/`MarkerFor`/`SameEntry` 且在 live data 上被打磨过(`season.go:70-79` 记录了 anilist 213097 ↔ bgm 659686 的假阴性修复)。 - **Cons / 已知陷阱(2026-08-28 评审 + codex outside voice 找出来的,重写时别重踩):** 1. **`internal/titlematch/titlematch.go:35` 已经 import 了 `internal/bangumi`**, 所以 `bangumi/match.go` 不能反向 import —— 编译成环。 ✅ **2026-08-28 已实测出解法,比预想便宜得多(0.5 人天,不是「跨包重构」)**: 环的承重面只有 **一行** —— `titlematch.go:53` 的 `bangumi.TitleSimilarity` (全包 5 处提到 bangumi,其中 4 处是注释;`SearchResult` 一次都没出现, 我最初的猜测是错的)。而 `season.go` 恰好**零仓库依赖** (只 import `regexp`/`strconv`/`strings`/`x/text/unicode/norm`)。 → 把 `season.go` 原样搬成 `internal/titleseason`,在 `titlematch` 留一个 `type Marker = titleseason.Marker` 的别名 shim + 三个 wrapper 函数。 **实测:调用方 0 改动、测试 0 改动**,`titlematch` 的 30 个测试一字未改全绿, `dandanplay/seasonmatch.go` 和 `queue/bangumi_episodes.go` 也不用动。 ⚠️ `Marker` 必须用**类型别名 `=`**,不能 `type Marker titleseason.Marker` ——后者不继承方法集,`SameEntry`/`Merge`/`Normalized` 会全没。 ⚠️ shim 用 wrapper **函数**不要用 `var ExtractMarker = ...`(可变包级状态且不可内联)。 2. 不要用字典序排序(confirmed > neutral > implicit > conflict)——那等于给季号 **无限权重**,一个相似度很低的候选会无条件压过接近满分的候选。Seanime 的 `−8`/`−3` 是**有界惩罚**,其它证据能翻盘,这才是对的形状。 2b. ★**季号 gate 写在哪里决定测试是 0 改还是 1 挂**(两种写法都实跑过): 写在 `ScoreCandidate` 里(markers 不一致就 `return 0`)会挂 `match_test.go` 的 `TestPickBest_TierLow_YearContradicted`,而且**会把 TierLow 塌成 TierNone —— 等于吃掉 needs-review 通道**,把「存疑」变成「无匹配」。 写在 `PickBest` 里(marker 只作 argmax tiebreak + TierHigh 准入条件)现有测试全绿。 **选后者。** 3. 「一侧声明、另一侧沉默」不能只降排序不设闸门:候选表里没有正确的 S2、 只有裸标题 S1 时它正是这一档,仍会被权威绑定 —— 洞没堵上。 4. 不要把 Season 和 Part 判定「取更差者」:双方都声明 S2 但都没写 Part 时会退化成 中性,让「双方确认」几乎不可达。 5. 现有的 `TestPickBest_TierLow_YearContradicted` **分不出**这几种设计——它的年份差 4 年,`ys=0.0` 已经把它压到 TierLow 了。必须补一个「候选声明了不同季号 **且** 年份一致」的新用例才有判别力。 - **Context:** 参照实现是 `5rahim/seanime` 的 `internal/library/scanner/matcher.go` (1596 行,GPL-3.0):带负分的累加、门槛 6.0、季号一致 +5 / 明确不符 −8 / 隐含 −3、 格式相符 +5 / 不符 −5、年份差>1年 −10。它的 `getIgnoredSynonyms` 也值得看 ——被多个候选共享的别名只保留给主标题最短的那个,且只作用于非主标题。 ★ **注意别重复一个已经犯过的归因错误**:这条路径产出的是 `anime_cache.bgm_id`, **不是** `bgm_id_map`(后者是从 `data/anilist_bgm_map.json` 灌进来的输入表, `bangumi_v1.go:128` 命中即绑定并 return,根本不走 scorer)。所以这个改动改善的是 fuzzy 匹配质量,**不是**「无来源绑定」那笔债的修复,优先级要按前者判。 - **Depends on / blocked by:** ~~被包依赖环阻塞~~ —— **已不再阻塞**,解法见 Cons 第 1 条 (0.5 人天,零调用方改动)。缺陷本身也已用可运行原型复现,不是推演: 基线下 `picked id=1 / tier=high`(绑错季且高置信),加上修复后 `picked id=2 / tier=high`; 候选表里只有错季条目时,基线 `tier=high` 无条件绑定,修复后 `tier=low` 转 needs-review。 ## 若任一路由的服务端渲染慢过约 300ms，把段内 `loading.tsx` 加回去 - **What:** 2026-08-28 把 `app/[lang]/loading.tsx` 从根部挪进了 `(home)/`，代价是 除首页、`/search`、`/welcome` 之外的路由在冷渲染时不再有骨架屏。若将来某个路由的 服务端渲染变慢，给它单独加一个段内 `loading.tsx` —— 但**前提是那个路由不调 `notFound()`**，否则 `routeBoundaries.test.ts` 会（正确地）变红。 - **Why:** 当时同意删掉的理由挂在一个会变的数上：源站直连实测首页 0.124s 渲染完， 在「感知为瞬时」的 100ms 阈值附近，先闪 91ms 骨架屏再换内容更像多余的状态切换。 这个论证在页面变慢时自动失效，而那时没人会记得当初是按哪个数判的。 - **Pros:** 阈值写下来了，重新判断时不用从头量；`routeBoundaries.test.ts` 已经保证 加回去的位置不会重新制造 soft-404。 - **Cons:** 可能很久都不会触发；渲染耗时受机器和网络影响，需要用同样的方法复测 （源站直连 TTFB vs total，差值就是流式窗口）而不是随手 curl 一下线上。 - **Context:** 那个根部文件第一行注释写着 "HomePage skeleton" —— 它本来就是首页的 骨架屏，只是放高了一层，顺带把 Suspense 边界盖到 24 个路由段上，让 5 个调 `notFound()` 的路由发不出 404。挪回 `(home)/` 之后首页的骨架屏原样保留。 当时测到的流式窗口：`/search` 0.287s、`/welcome` 0.263s（两者保留了自己的 `loading.tsx`）、`/` 0.091s、`/seasonal` 0.043s、`/calendar` 0.038s， 而 `/anime/[id]` 是 0.001s —— 它是 ISR，整页缓存后一次发出，那 167 行骨架屏 从来没有渲染给任何人看过。 - **Depends on / blocked by:** 无。 ## 把 `resolveLocale` 拆成会抛和不会抛两个变体 - **What:** `lib/i18n/route.ts` 的 `resolveLocale()` 在 `[lang]` 不是合法 locale 时 直接 `notFound()`。它被 20 个页面和全部 4 个 layout 引用。拆成一个给 layout 用的 会抛变体，和一个给「边界之下的页面」用的不会抛变体。 - **Why:** `routeBoundaries.test.ts` 现在有三条 allowlist（`(home)` / `search` / `welcome`），理由都一样：这些页面重复调了一次 `resolveLocale`，而 `[lang]/layout.tsx` 已经用同样的 params 在边界**之上**检查过了，所以页面里那一次永远不可能是决定 404 的 那一次。拆开之后这三条 allowlist 自动清空，规则变成无条件成立。 - **Pros:** 把「靠 allowlist 说明为什么破例」变成「结构上不可能破例」；也省掉每个页面 一次多余的 locale 解析。 - **Cons:** 触及 20 个页面文件，是个大范围但机械的改动；两个变体的命名要足够清楚， 否则下一个人会挑错那个。 - **Context:** 这是「为什么 allowlist 存在」的正解，不是绕过。allowlist 每条都带了 理由并且会做陈旧性检查（条目描述的违规若已消失，测试同样变红），所以现状是安全的， 只是不够干净。 - **Depends on / blocked by:** 无，但做完之后要把 `routeBoundaries.test.ts` 的 `ALLOWED` 清空，那三条陈旧性检查会提醒你。 ## 清掉「客户端语言来自 `lang` cookie」这个说法 —— 全仓 14 个文件，而那个 cookie 不存在 - **What:** `grep -rlE "lang.{0,12}cookie|cookie.{0,12}lang" next-app/src` 命中 14 个 文件。其中源头 `lib/lang-client.tsx` 已在 2026-08-28 改正，其余需要逐个过一遍： 留下真正是历史陈述的（「cookie 被移除之后……」是准确的），删掉仍在描述当前行为的。 - **Why:** 全仓**没有任何 `lang` cookie**——不写也不读。`cookies()` 只用于鉴权 （admin / library / login / register），`?lang=` 是 `proxy.ts` 里的遗留**查询参数**， 不是 cookie。而这些注释描述的是一套完整的机制：hydration 后有个 effect 把语言换成 cookie 值，所以客户端语言和服务端渲染「故意不一致」。这套机制不存在。 - **Pros:** 这不是措辞问题，它已经在改变判断。旧版季度页 （`seasonal/[season]/[year]/page.tsx`）曾用它当作一个设计决定的依据（那段注释随旧的 筛选药丸一起删了）；`not-found.tsx` 曾用它论证 404 页的语言不可信 （实测可信，现由 `e2e/specs/sandbox/not-found-status.spec.ts` 三语在浏览器里钉住）。 - **Cons:** 纯注释改动，没有测试能防止它再次发生；14 个文件要一个个读，不能批量替换， 因为其中确实有几处是准确的历史陈述。 - **Context:** `lang-client.tsx` 自己的 `LanguageProvider` 注释一直是对的 （"There is no reconciliation step and no local state"），与同文件头部的说法直接 矛盾了很久没人发现 —— 一个文件里两段注释互相打架，是这类腐烂的典型信号。 - **Depends on / blocked by:** 无。 ## ✅ 已修：`proxy.ts` 把任何以点后缀结尾的路径当成静态资源，裸 URL 因此匹配不到路由 > 2026-09-15 随 hub 页一起修：`NON_PAGE_PATH` 改成真实扩展名白名单。触发点是 `/studio/J.C.STAFF`——那家有几百部番。`proxy.locale.test.ts` 钉住白名单和四个带点的页面路径；e2e 的 KNOWN DEFECT 用例翻成正向断言。下面是原始记录。 - **What:** `proxy.ts:94` 的 `NON_PAGE_PATH = /^\/api\/|^\/_next\/|\.[a-z0-9]+$/i`。 第三个分支意思是「任何以 `.` + 字母数字结尾的路径」。这类路径会跳过 locale 改写， 而**裸 URL 正是靠那次改写才能匹配到 `/[lang]/...`** —— 于是它谁也匹配不上，落到 Next 内置的 404 页。带 `/en`、`/zh-Hant` 前缀的不受影响（`en` 本身就填进了 `[lang]`）。 - **Why:** 实测：`/u/{contact-shaped handle}` 裸路径 404，`/en/u/{同一个}` 正常 308 重定向到掩码 handle。凡是邮箱形状的别名都中招，因为常见邮箱域名都以点后缀结尾。 - **Pros:** 修法很清楚：把「任何点后缀」换成真实的扩展名白名单。 - **Cons:** 那条守卫是**承重**的 —— 它防止 `/sitemap.xml`、`/robots.txt`、jassub 的 `.wasm` 被改写到 locale 段下面，而 sitemap 是这个站最不能出事的 URL。白名单漏一个 就等于弄坏一个资源，所以这是一次需要自己的测试和自己的评审的改动。 - **Context:** 影响面有限：受害的只有**别名**形态，而站内所有链接指向的是规范形态 `/u/user-xxxx`（无点，裸路径正常）。状态码层面 404 也是个说得过去的答案，丢掉的是 那次重定向。已由 `not-found-status.spec.ts` 的 "KNOWN DEFECT" 用例钉住现状。 - **Depends on / blocked by:** 无。 ## `/u/` 的三处重定向会丢掉 locale 前缀 - **What:** `/en/u/{alias}` 重定向到**裸** `/u/user-xxxx`，`/en` 没了。英文读者被静默 送回中文站。三个 `/u/` 重定向调用点都是这样。 - **Why:** `permanentRedirect()` 收到的是硬编码的 `/u/${...}`，没有经过 `localizePath()`。 以前这个缺陷是隐形的：重定向根本发不出状态码（流式响应把状态冻在 200），走的是客户端 导航。2026-08-28 拿掉 `loading.tsx` 之后它变成真 308，缺陷才暴露在 HTTP 层。 - **Pros:** 改动很小 —— 那三处套一层 `localizePath(path, locale)` 即可，页面本来就有 locale。 - **Cons:** 需要同时更新 `not-found-status.spec.ts` 里那条 "KNOWN DEFECT" 用例，它目前 断言的是「前缀确实丢了」，修好之后会（正确地）变红。 - **Context:** 这是那类「只有把上游修对了才看得见」的缺陷。 - **Depends on / blocked by:** 无。 ## 404 的 `Cache-Control` 和真实番剧页一模一样 - **What:** 生产构建下 `/anime/{不存在的 id}` 返回 `s-maxage=60, stale-while-revalidate=31535940`，与 `/anime/21` 逐字节相同。 于是一个 404 会进 Cloudflare 边缘缓存，在该 id 变成真页面之后仍可能被发出一次。 - **Why:** ISR 的 `revalidate` 是**整条路由**的属性，Next 没有在页面层面按状态码区分 缓存时长的声明式写法。要区分得走 nginx 或中间件。 - **Pros:** 实际敞口很小：SWR 语义是「发陈旧的同时后台重验」，所以最多是新鲜窗口过后 的第一个访客拿到一次旧的 404，下一个就是新的。 - **Cons:** 这条**没有测试**，而且故意没有：沙箱套件跑在 `next dev` 上，那里这个头是 `no-cache, must-revalidate`，断言会永远为真 —— 一条不可能失败的绿灯比没有断言更糟。 要测只能放线上那个 project，且只能在部署之后跑。 - **Context:** 与 2026-08-28 的状态码修复无关，线上今天就是这个头，变的只是被缓存的 东西从 200 变成了 404。 - **Depends on / blocked by:** 无。 ## 未匹配任何路由的 URL 拿到的是 Next 内置 404，不是我们设计的那张 - **What:** `/en/nope-nothing-here` 这类打不中任何路由的地址，渲染的是 Next 自带的 `404: This page could not be found.`，没有 Navbar、没有品牌、没有去处。我们设计的那张 只在页面主动调 `notFound()` 时出现。 - **Why:** 我们的 `not-found.tsx` 在 `app/[lang]/` 下，不是 app 根。根级未匹配 URL 要 `app/not-found.tsx` 或 `app/global-not-found.js` 才接得住，而我们**不能**建 `app/not-found.tsx` 之外的根级静态段（会遮蔽 `[lang]`）。 - **Pros:** Next 文档正好点名了我们这个形状：「根布局用顶层动态段（如 `app/[country]/layout.tsx`），会让统一的 404 页更难拼」，并把 `global-not-found.js` 列为对应答案（`node_modules/next/dist/docs/01-app/03-api-reference/ 03-file-conventions/not-found.md`）。 - **Cons:** 该特性 v15.4.0 起仍是 experimental，需要开 `experimental.globalNotFound`， 且它绕过正常渲染 —— 得自带 ``、字体和全局 CSS。 - **Context:** SEO 上无损（状态码就是 404，Next 还自动注入 noindex），纯粹是体验和品牌 问题：打错一个字的访客拿到的是一张空白页而不是回站内的入口。 - **Depends on / blocked by:** 无。 ## 台湾/大陆译名不同 —— 简繁折叠做完之后剩下的那 59% - **What:** 2026-08-28 给 `/api/anime/search` 加了查询词简繁折叠（用现有的 `opencc-s2twp.txt`，转出的繁体额外去匹配 `title_hant`，不写库、不改显示）。 **这条 TODO 的本体已完成。** 留下的是它够不到的部分：**同一部番在台湾和大陆 用不同译名**，任何字符映射都跨不过去。 - **Why:** 实测而非估计。拿 **5,160 行**同时有简体标题和**权威**繁体标题 （`title_hant_source <> 'opencc'`）的记录做测量：折叠后的简体标题能成为库里繁体 标题的子串（正是搜索用的判据）的比例是 **40.7%**，不折叠是 **7.4%** —— 提升 约 5.5 倍，但不是"解决"。 - **Pros:** 失配的成因已经查清，不用再猜：**2,237 条失配长度就不同**，是彻头彻尾 的另一个译名 —— 海賊王 / 航海王、三眼小子 / 三眼神童、鋼鐵奇兵 / 金屬對決、 勇敢魔女 / 無畏魔女。剩下 822 条等长的也多是译名差异（兄弟鬥爭 / 兄弟戰爭） 和繁体行文惯例（你 / 妳），不是字形转换错误。 - **Cons:** 要再往前走只有一条路：**别名表**。可以从 AniList 的 synonyms 里挖 （那本来就是多译名的来源），也可以人工维护热门番的别名。这是独立的一件事， 且收益递减 —— 40.7% 已经覆盖了最常见的情况。 - **Context:** 另有 **57 行「有简无繁」**（用户敲繁体、库里只有简体）仍未覆盖， 需要 t2s 表而仓库只 vendor 了 s2twp。57 行太少，是否值得再 vendor 一份表留待再判。 ★还有个坑值得记：**s2twp 不是纯字形转换**，`wp` 是台湾词汇替换 ——「折叠」会变成 「摺疊」而不是「折疊」。写测试探针时用了这类词会让测试红而功能其实是好的， 我为此排查了两轮。 - **Depends on / blocked by:** 无。 ## 不存在的番剧 id 在 AniList 被限流时返回 500 而不是 404 - **What:** `/anime/{不存在的 id}` 走的是「本地缓存未命中 → 实时问 AniList」。AniList 一旦限流，go-api 返回 `AniList rate limited`，next-app 抛 `ApiError`，页面变成 **500**。实测：沙箱套件用 `--repeat-each=3` 并发压一下就稳定复现，dev 日志逐字写着 `Error [ApiError]: AniList rate limited` 后跟 `GET /anime/999999999 500`。 - **Why:** 一个不存在的 id 本该答 404，在限流窗口里答的是 500。缺陷本身与 CI 无关、 独立可复现（见上面的 `--repeat-each=3`），代价写在下面的 Context 里。 > ★**归因更正（2026-08-29）**：本条原写「这大概率就是沙箱 CI 里 > `not-found-status.spec.ts` 那条 `/en answers 404` 偶尔变红、重试即过的真正原因」—— > **那句是错的，已删**。那个 flake 的真身是 Turbopack dev 下**整类嵌套动态路由变 > 404**（见下一条「Turbopack dev 下……」）。三条判据各自独立地否掉了本条： > 症状是 **404 不是 500**；受害路由包括 `/reset-password/[token]`，它**一次 AniList > 都不调**；而失败那次里 `/anime/*` 的 404 只花了 42ms（`next.js: 5ms`）， > 根本没进过第三方调用。两件事只是恰好都落在同一个套件上。 > ⚠️ **同一句错误归因也逐字写在 `e2e/specs/sandbox/not-found-status.spec.ts:59-60` > 的注释里**（"almost certainly the cause of the `/en answers 404 (retry #1)` > flake"），修这条缺陷时一并改掉，否则它会继续把下一个人引到 AniList 上。 - **Pros:** 修法和 2026-08-28 的搜索改动是同一个思路：**目录里没有的 id，本地就能判定 不存在，不必问第三方**。`anime_cache` 有 17,689 行，一个 id 不在里面且不是新番的 概率极高。至少可以做到「AniList 不可达时退回本地判定」而不是直接 500。 - **Cons:** 有真实的取舍：一个刚上映、我们还没收录的番，本地判定会给出 404，而现在 它能通过 AniList 找到并顺带入库。要保留这个自愈能力，就不能无条件本地化。 - **Context:** 对 SEO 的影响是实的 —— Googlebot 撞上限流窗口时，一个本该是 404 的 URL 会返回 500，而 500 会让爬虫认为是临时故障并反复重试，比 404 更糟。 `not-found-status.spec.ts` 里那几条状态断言故意保持严格（只接受 404），**不要**为了 让 CI 变绿而放宽成「404 或 500」—— 那会把这个缺陷永久藏起来。 - **Depends on / blocked by:** 无。与本地搜索独立，但共用同一个判断。 - **进展（2026-09-23，分支 `fix/anilist-budget-cold-id`）：** 「反复打 AniList」那一半已修 —— AniList 答「不存在」的 id 在进程内记 24h（`detail.go` `absent`，只在冷 id 分支写，429/超时/ 其它上游错误**不记**），同一冷 id 的并发请求经 singleflight 只打一次上游。**「限流窗口里冷 id 仍 5xx」这一半保留**：2026-09-20 eng-review（D3）否决了「AniList 不可用时本地判定 404」， 因为那会对刚上 AniList、我们还没收录的新番答 404，而且会被 CF 缓存（60s + SWR）；503 是 诚实的「暂时不知道」，爬虫和 CF 都不会把它缓存成结论。 ## Turbopack dev 下，嵌套在 `[lang]` 里的动态路由会整类 404 - **What:** 沙箱 e2e 时红时绿、重跑即过，一直被当成不明 flake。真身不在测试里： `next dev` 用的是 Turbopack（Next 16 起是默认），而某些进程实例里**凡是 `[lang]` 下面还有一层动态段的路由，一整轮全部 404** —— `[lang]/anime/[id]`、 `[lang]/reset-password/[token]`、`[lang]/u/[username]`、 `[lang]/seasonal/[season]/[year]` 无一幸免。止血办法是让沙箱的 dev server 也走 webpack（`next dev --webpack`，该 flag 确认存在），与 `next build --webpack` 对齐。 - **Why:** 形状本身就排除了产品代码：两个 PR（#127 改 CSS/SVG filter、#128 改弹幕速度 设置）**diff 毫无交集**，却在 attempt 1 挂掉**同样 9 条用例、同样的行号** （散落在 6 个 spec 文件里），且都在**零代码改动**的重跑里全绿。 再看范围：`[lang]` 是唯一动态段的路由（`[lang]/faq`、`[lang]/search`、 `[lang]/privacy`）自始至终正常，`[lang]` **之外**的动态路由 `/sitemaps/anime/sitemap/[id].xml` 同一轮里也正常 200 —— 坏的恰好是 「`[lang]` + 再嵌一层动态段」这一类，三段路径 **0 成功 / 19 次失败**。 - **Pros:** 两条判据都能直接从 CI 日志读出来，不必复现： 1. **`generate-params` 阶段在不在。** next-dev.log 里每条 200 都带 `generate-params: …`，每条 404 **一个都没有**。这一段缺失＝该段从没被编译。 2. **404 花了多久。** 健康时 `/anime/0` 是 `404 in 942ms (next.js: 870ms)` —— 段编译过了、页面在 `anilistId <= 0` 上主动 `notFound()`，这是**产品的** 404。 故障时是 `404 in 42ms (next.js: 5ms)` —— 从没编译过，404 来自路由层。 ★**状态码一模一样，来源完全不同** —— 只看状态码永远分不出这两件事。 - **Cons:** `--webpack` 是**止血不是修复**，而且 2026-08-29 的对照组实测证明**现在还不能上**。 同一个 commit 推 6 个分支各跑一次（不同 ref 才能绕开 `cancel-in-progress`，同 ref 连发只会 互相取消）： | | Turbopack 基线 | webpack 6 次 | |---|---|---| | 嵌套动态段 404 指纹 | 14 次里出现 3 次 | **0/6，确实消失了** | | job 时长 | ~4 分钟 | **8m08s–9m23s，约 2.2 倍** | | 套件结果 | 间歇性红 | **6/6 全红** | ★**它换来了一个更糟的缺陷**：7 条用例在 6 次里每次都挂（`auth` 3 条、`locale-routing` 2 条、`stale-tab` 2 条），确定性的，不是抖动。机理在第一条里写着 —— 期望 「邮箱或密码错误」，实际拿到「邮箱格式不正确」，即**打字进了 DOM 没进 React state**， 正是 #129 修 `/search` 时记下的水合竞态。#129 只修了那一个 spec，其余会打字的 spec 仍然不等 `__reactFiber$`，而 webpack 更慢的编译把那个窗口从偶发撑成了必现。 **结论：套件本来就依赖 dev server 足够快，Turbopack 的速度一直在掩盖这件事。** 换打包器之前必须先把这些 spec 的水合等待补上，否则是拿一个间歇性红换一个确定性红。 另外两块代价不变：沙箱从此不再覆盖生产之外的第二个打包器；**上游那半还没查** —— 这是不是已知的 Next issue、有没有在更晚的 16.x 里修掉，目前是空白 （查的时候 web search 额度已耗尽，不是查过没有）。在补上这一步之前， 只能说「webpack 下没复现 404」，**不能**说「根因是 Turbopack 的某某」。 - **Context:** 全仓只有沙箱在跑 Turbopack —— `next-app/package.json` 的 build 是 `next build --webpack`，只有 `dev` 走默认。当前钉的是 `next@16.2.6`。 ★**最值钱的是早期指纹**：warm-up 那一行 `warmed /reset-password/warmup -> 404`。 那个页面不调任何 API、也没有任何 `notFound()` 分支，**健康栈里它不可能是 404**。 翻了 14 次历史运行它出现过 3 次，**3 次对应的 attempt 全部失败**。而 warm-up 的守卫 只对 `5xx|000` 判失败，所以它两次都把指纹打印出来又原样放行了。把这一行收紧成 「`/reset-password/warmup` 不是 200 就直接失败」成本一行，收益是把一次半小时的 e2e 排查压成一条报错。 ★**取证顺序**：重跑会**覆盖** job 日志，但 `gh api repos/OWNER/REPO/actions/runs//attempts/1/logs` 仍取得到失败那次； 而 `Dump service logs on failure` 是 `if: failure()`，所以 next-dev.log 和容器日志 **只有失败那次才存在**，重跑变绿之后就永远没有了。**先取证，再重跑。** - **Depends on / blocked by:** 无。 ★★**2026-08-29 补：换打包器不是唯一出路，自愈已实测可行。** 自建最小复现（290 个 page + 2.2MB 共享模块 —— **空 app 复现不出来，0/20**），把 dev server 打进故障态 41 次分三组： **control 0/13 修好、`touch`（纯 mtime，零字节写入）11/11、内容写入 11/11**。 macOS 与 Linux 容器两边都跑了（FSEvents 与 inotify 对 `utimensat` 的处理没理由假设同构）。 机理不是只看状态码翻转：touch 前 `404 in 43ms (next.js: 5ms)`（没编译）， touch 后 `200 in 818ms (generate-params: 688ms)`（段第一次被编译）。 三条硬约束，都是实测不是推的： ① **touch 必须打在 `app/` 底下** —— 打在被 import 但位于 app/ 外的模块上 **0/2**； ② **可以 touch 一个惰性文件**（app/ 下的空文件、零 import）**2/2**， 所以自愈脚本不需要编辑任何 page 源码； ③ 检测到故障再 touch，落点远在 ready 之后，不会踩上游说的「ready 后约 1.5s 事件被吞」窗口。 ★**一条诚实的保留**：复现里死的是**动态段下面的静态子段**，而动态叶子全部活着 —— **和我们 CI 里 404 的形状正好相反**。复现的确定是上游那个缺陷； 我们 CI 那次是不是同一个，靠指纹吻合推断，**这次实验没有直接证明**。 所以判据只能用指纹（瞬时 404 + 缺 `generate-params` + 整类全灭 + 持续整场），不能用路由形状。 ★方法论坑，值得记：对照组差点出假阳性 —— 一台试验中的 server 被误杀，post 探测全是连接错误 （status 0），而分类器只把 **404** 当「死路由」，于是记成「自愈成功」。 **「不是失败信号」不等于「成功信号」**；探测器要加存活断言。 ★**退出条件 —— 什么情况下可以把 Turbopack 换回来**，三条都满足才动： ① 找到对应的上游 issue，并确认它在某个具体的 16.x 里标为已修； ② 升到那个版本； ③ **用同一个指纹复验**：连跑若干次沙箱，`warmed /reset-password/warmup` 全是 200， 且 next-dev.log 里嵌套动态路由的 200 全都带 `generate-params`。 「跑了一次没红」**不算数** —— 这个缺陷本来就是间歇的，n=1 在本仓已经骗过人不止一次。 ## 断言「不存在」的用例，在整体故障下会以错误的理由变绿 - **What:** 扫一遍沙箱套件，把「断言 404 / 不可见 / 空结果」却**没有同路由族正例配对**的 用例挑出来，逐条补上正例。**这条 TODO 的本体是那次扫描**，不是某一个文件 —— 下面的样本只是发现它的入口，不是全部。 ★**已配对两处，其余未扫**（别把这两处当成扫描做完了）： ① `/seasonal//` —— 原本唯一的正例在 `chromium-prod`， 那个 project 打的是**已经部署的线上站**，所以「PR 把每一季都改成 404」照样全绿。 正例已加进 `not-found-status.spec.ts` 并**排在文件第一位**：该文件是 `mode:"serial"`，前面任何一条红掉，后面的全部 **skip**，只有第 1 位不会被静音。 ② `stale-tab.spec.ts` 那 3 条「通知不出现」—— 它们此前在**功能彻底不工作**时 也全绿（实测：让监听器永不注册，旧代码那 3 条一条不红）。现在它们先等 `/version.json` 的往返真的发生，再问通知有没有出现。 ★这两处给出的通用配方：**负向断言要先等一个「被测能力确实运行过」的可观测量**， 不能只等一段时间然后断言什么都没发生 —— 后者与「能力从没启动」完全同形。 - **Why:** 2026-08-29 那次故障给了一个教科书级的样本：**全站每一条嵌套动态路由都在 404**，而 `not-found-status.spec.ts` 里断言 404 的 **10 条用例全绿** —— `/anime/0`、`/anime/abc`、`/anime/-1`、`/anime/999999999`、 `/seasonal/notaseason/2026`、`/u/{不存在}` 及其 `followers`/`following`， 再加三个 locale 前缀各一条。它们要的答案是 404，而路由层正在无差别地发 404， 于是**每一条都以完全错误的理由通过了**。一条断言「这个不存在」的用例， 在「什么都不存在」的时候没有任何判别力。 - **Pros:** 配对的效力不是推演，**同一个文件里就有现成的对照组**： `not-found-status.spec.ts:207` 的 "a real anime still answers 200 in every locale form"。那一轮 11 条状态断言里**唯一变红的就是它**，而它的注释当初就把理由写清楚了 —— "a change that 404s the whole catalogue passes every assertion above"。 作者预见到了这个形状并挡住了；缺的只是把同一条规则推广到其余用例。 - **Cons:** 配对不是免费的：正例需要一条真实存在的夹具数据，而夹具生命周期在 `fullyParallel` 下本身就是出过 bug 的地方（#123 修过一次共享夹具的并发缺陷， #118 那轮的三条红也全是我自己 spec 的并发缺陷）。补正例时别顺手引入新的共享可变状态， 否则治好一个盲区、换来一个 flake。 - **Context:** 沙箱 20 个 spec 里有 12 个含形如 `toBe(404)` / `not.toBeVisible` / `toHaveCount(0)` / `toBeHidden` 的负向断言，共 **35 处** —— 这是扫描的**分母**， **不是**「35 处都有问题」的结论，也**不是**「已经扫过了」。逐条只问一个问题： **「如果被测的这个能力彻底坏掉，这条断言会不会照样绿？」** 会，就补正例。 ★配套的一条判据见上一条：状态码相同不代表路径相同，用例分辨不了的， 服务端日志能分辨（`generate-params` 在不在 / 404 花了几毫秒）。 - **Depends on / blocked by:** 无。与 Turbopack 那条彼此独立 —— 打包器换回去之后， 这个盲区照样在。 ||||||| parent of b94900e (docs: record the dialog primitive migration as a TODO) ## 把剩余 10 个手搓对话框迁到共享 Dialog primitive - **What:** 下一个新增的对话框会顺带抽出一个共享 Dialog primitive(backdrop、Escape、焦点进入、 焦点归还),并让它与 `components/anime/PlayButton.tsx` 同时使用。本条是把其余 10 个也迁过去: `library/_components/` 的 MergeDialog / SplitDialog / RematchDialog / OpsLogDrawer / SeriesDetailSheet、 `components/anime/TorrentModal.tsx`、`components/profile/PhotoCropModal.tsx`、 `components/safety/ReportDialog.tsx`,以及 HudOverflowMenu 与 LanguageMenu 中的同形部分。 - **Why:** 全仓 11 个组件各自手写 `e.key === "Escape"`,**没有任何共享实现**;其中只有 3 个 (HudOverflowMenu / LanguageMenu / PlayButton)做了关闭后的焦点归还。下一次无障碍修复 (焦点囚禁、`inert`、滚动锁定)要手改 11 处,而没有任何机制告诉你漏了哪几处。 - **Pros:** 每迁一个,重复的图案数量减一;顺带把 8 个缺失的焦点归还一起补上;以后无障碍修复只改一处。 - **Cons:** 跨 library / player / anime / profile / safety 五个区域,各自有转场动画、背景点击、 滚动锁定的差异,不是机械替换;纯重构 PR,无用户可见价值,需要逐个回归。 - **Context:** 2026-08-29 清点全仓对话框实现时发现。刻意没有一次性全迁 —— 让 primitive 上线 当天就有两个真实使用者(新对话框 + PlayButton),同时把重复图案数保持在 11 而不是变成 12, 且不让一次全站重构阻塞新功能。primitive 从 `PlayButton.tsx:36,49` 已验证的 rAF 焦点模式 提炼(`triggerRef.current?.focus()` / `closeRef.current?.focus()`)。 **这条 TODO 最重要的作用不是催重构,而是让下一个要写弹窗的人知道 primitive 已经存在** —— 否则抽象会被手搓的第 12 份白白作废。建议按区域分批,一次一个 PR,每个配一条 e2e 键盘用例。 - **Depends on / blocked by:** 阻塞于 primitive 先落地。 ## 网站 /library 的非 Chrome 兜底 - **What:** 给 `next-app/src/app/[lang]/library/_components/DropZone.tsx` 补上 `webkitdirectory` / `webkitGetAsEntry` 兜底路径,让 Safari / Firefox 用户能建库。`/player` 那个同名文件已经有一份现成实现(`flattenDropFiles` + ``),直接搬。 - **Why:** 实测 `library/_components/DropZone.tsx:262` 是 `if (onPick && isFsaSupported) onPick();` —— 非 Chromium 浏览器上点「添加文件夹」**什么都不会发生,没有任何兜底分支**。这些用户不是体验差,是整个本地库功能对他们不存在。 - **Pros:** `/player` 代码现成可搬;非 Chrome 用户从「完全用不了」变成「能用」;纯前端,不阻塞任何其他工作。 - **Cons:** 没有持久句柄 —— `File` 对象活不过刷新,每次开站要重选一次文件夹;也没有自动重扫(`FileSystemObserver` 同样 Chromium-only)。 - **Context:** 2026-08-29 `/plan-eng-review`(agent 方案评审)中发现。⚠️ **降级模式必须在 UI 上明说**,否则「每次要重选文件夹」会被用户读成「功能坏了」—— 这个仓库在静默降级上栓过多次。注意两个 `DropZone.tsx` 是不同文件,别改错。 **为什么不等一个"装个东西就好了"的方案:** 任何要求用户先安装本地程序的路线都只救**装了的人**。不装的 Safari / Firefox 用户在那之后依然是今天这个处境,所以这一项不被它取代。 - **Depends on / blocked by:** 无。纯前端,与其他方向零交集,任何时候都能做。 ## deploy.sh 的 smoke 检查从不因为 5xx 失败 - **What:** 让 `scripts/deploy.sh` 末尾那三条 smoke curl 在非 2xx/3xx 时真的让部署红掉,而不是只打印一行状态码。 - **Why:** 现在是 `curl -sk -o /dev/null -w "HTTP %{http_code} from /"` —— 把状态码**印出来但不判断**,三条都一样。脚本自己最后一行写着「If a smoke line shows 5xx, check `docker compose logs`」,也就是它明确依赖**有人去看那行输出**。一个全站 500 的部署,退出码是 0。这不是假想:2026-08-30 本地把 bgm 字段灌进 `anime_cache` 之后,`/anime/116674` 连续返 500,而整条流程照常走完。 - **Pros:** 改动极小(三行加 `-f`,或显式比较状态码);把仓库自己那条「验部署要 curl 不能看退出码」的教训真正写进脚本;严重度高于大多数前端缺陷 —— 500 是硬故障,不会自愈。 - **Cons:** smoke 跑在 `$COMPOSE up -d` **之后**,所以「失败」时新版已经在线且没有回滚。要么接受「大声报错但不回滚」(仍比静默好),要么顺带接上回滚 —— 后者就不是小改动了。`scripts/p9-rollback.sh` 已存在,可以先看它能不能直接接。 - **Context:** 2026-08-30 的 `/plan-eng-review` 中发现:外部声音指出 smoke 在 `up -d` 之后且不 gate,由读脚本确认。⚠️ 注意别顺手把它改成 `set -e` 直接退出 —— 那会在「新版已上线」的状态下留下一个半完成的部署,比现在更难收拾;先决定失败语义再动手。 - **Depends on / blocked by:** 无。纯 shell,与任何代码改动零交集。 ## `bangumi_version` 是单向棘轮，version≥2 的行没有任何重跑路径 **What** — 给富化流水线加一条「让一行重新过一遍 V1→V2→V3」的入队路径，不依赖把 `bangumi_version` 手动改回 0。 **Why** — 现在所有 V1 生产者（orphan scan、`/search` 与 `/schedule` 的 upsert 后置、warm_season、admin ReEnrich(0)）都过滤 `bangumi_version = 0`，而 `UpsertAnimeCache` 在冲突时**刻意不覆写**版本号（`go-api/internal/db/queries/anime_cache.sql:253-258`）。V2 一跑完把版本推到 2，这一行就永久掉出所有扫描；V2 本身又只由 V1 绑定成功后的 `chainV2`（`bangumi_v1.go:264`）链式触发，没有任何周期任务生产 V2 作业。结果是**那一次跑空了就永远是空的**——`bangumi_v2.go:344` 把 episodes fetch 错误记个 warn 就 `return nil`，作业标记完成，river 不重试，而版本已经推进。 **Context** — 2026-09-02 分集标题方案评审中查出。当时的处理是**绕过**而不是修：存量用 `cmd/bgmbackfill` 的一次性 CLI 补，而不是让流水线自己重跑。但同一个棘轮对 V2/V3 写的**每一个**字段都成立——characters、bangumi_score、title_chinese、分集标题——所以下一个「某个富化字段大面积缺失」的问题会再撞一次，而且每次都得再写一个一次性 CLI。 实测规模：1,784 行有 bgm_id 却零分集标题，其中 1,522 行任何自动任务都够不到（772 行卡在 v1、3 行 v2、747 行 v3）。 ⚠️ 动它之前先确认真实的 `MaxAttempts`：三个 worker 的头注释都写「river 默认 3 次」是**错的**，v0.37.1 的 `MaxAttemptsDefault` 是 **25**，配 attempt^4 退避约 20 天。 已有的绕行补丁（都没修棘轮本身）：id-map 绑定扫描（`bgm_bind_idmap.go`）、分集标题扫描、简介回填，以及 2026-10-18 加的「在播/未开播且未绑定的番每周重搜 Bangumi」（`bgm_rebind_search.go`，只管 V1 没绑上的那部分，绑定之后的 V2/V3 字段照旧只跑一次）。 **Depends on / blocked by** — 无。但与 `## 分割放送会 50% 概率绑错` 那条同属富化流水线，建议一起看。 ## id-map 一致并不排除「范围不符」，而它挡着分集网格取 max **What** — 在绑定校验里加第三个信号：上游正片集数与 `anime_cache.episodes` 的量级比对。现有两个信号（标题相似度、季号标记）和 id-map 都答不了这个问题。 **Why** — id-map 回答的是「这个 anilist 条目对应哪个 bgm subject」，**不是**「这个 subject 的集列表就是这个条目的集列表」。一个 3 集的 ONA 可以合法地映射到整部正片的 subject 上，于是我们把正片几百集的标题写进了这个小条目。实测 `anime_episode_titles.episode > anime_cache.episodes` 的有 776 部：`+6..24` 那档 **335 部**抽样全是 ONA/SP 绑到正片 subject（`我的幸福婚姻` ONA 写着 3 集库里 12 行；`机动战士SD高达` SPECIAL 3 集 17 行）；溢出 >100 集的 18 部里有 **9 部是 id-map 确认的绑定**——也就是说权威映射表点头了，数据仍然是错的。 **Context** — 2026-09-02 评审实测。⚠️ **这条阻塞分集标题方案里的 T9**（`next-app/src/components/anime/episodeGridSkeleton.ts:101` 的 authoritative 分支取 max）：不先解决范围不符，取 max 会把这批陈旧溢出重新渲染出来，`与莫芬一起` 那种 5 集 ONA 会被画出 3,528 个格子。所需信号很便宜——上游集数本来就在同一个响应里，不额外花请求。 ⚠️ 阈值要小心：实测溢出量是 +1 到 +820 的**连续谱**，`+1` 那档 164 部多是 AniList 少算一集的真实情况（`格斗美神·武龙` 25 集 / 上游 26 集，行是密的），不能一刀切。 **2026-09-03 更新：阈值已从分布定出，产出方已加守卫。** 按**比值**（写入的最高集号 ÷ 目录集数）重新分档，比按绝对溢出量清楚得多： | 比值 | 番剧 | 越界行 | id-map 确认 | 平均目录集数 | |---|---|---|---|---| | ≤1.10x | 122 | 183 | 89% | 29.1 | | 1.10–1.50x | 95 | 423 | 75% | 17.1 | | 1.50–2.00x | 198 | 1,829 | 63% | 10.9 | | **>2.00x** | **475** | **17,880** | 41% | **4.2** | >2.00x 一档占全部损坏的 **88%**，平均目录集数 4.2（都是 ONA/SP/短片），最坏一部 3,528 个集位。≤1.10x 一档 89% 由独立映射确认、平均 29 集、总共才 183 行——那是目录少算一两集，**标题是对的，不能碰**。 ★★**这不是绑错，是范围不符**：>2.00x 那 475 部里有 195 部绑定被 id-map 确认。Bangumi 合法地用一个 subject 覆盖 AniList 拆成正片+短片的内容，所以**解绑是错的修法**。 已做：`episodetitles.ScopeExceeded` 以 2.00x 为界，CLI 记 `SCOPE_MISMATCH`、sweep 记 rejected，**整条拒绝而不是截断**（列表属于整个系列时，它的第 1 集是系列的第 1 集不是本条目的，头和尾一样不可信）。目录集数未知的 2.9% 放行——没有分母就没有判据。**未做：存量那 20,315 行的清理**，以及 T9 本身。 **Depends on / blocked by** — 无。做完它 T9 才能安全上线。 ## dandanplay client 把所有 4xx 压成「没有数据」 **What** — 让 `go-api/internal/dandanplay/client.go:386` 区分 401/403（凭据或授权问题）、404（该资源确实不存在）、其他 4xx，而不是统一返回 `(nil, nil)`。 **Why** — 现在调用方拿到的「没有数据」同时可能意味着「这个 subject 上游确实没有」「AppId/AppSecret 失效了」「请求被拒了」。前者是正常的数据稀疏，后两者是需要人介入的故障，而它们在日志和返回值上完全一样。 **2026-09-04 更新** — 同一个函数上**另一半**已经修了：dandanplay 把应用层错误放在 **HTTP 200 的 body 里**（`{"success":false,"errorCode":429}`），而 `do()` 只看状态码、全仓从没解析过 `success`/`errorCode`，所以**配额耗尽和「这个条目没数据」完全同形**。现已加 `apiStatus` + `checkStatus`，返回 `ErrQuotaExceeded` / `ErrUpstreamRejected`。本条剩下的 4xx 部分**仍未做**：401/403/404 和其他 4xx 依然一律返回 `(nil, nil)`。两者是同一处症结的两面，但状态码那面还在。 **Context** — 2026-09-02 评审中由外部声音（Codex）指出，读代码确认。**严重度不高**：分集标题回填走的是人工跑的 CLI，凭据失效会让整份报告 100% EMPTY，跑的人一眼就能看出来；真正无人值守的只有 RELEASING 那个小 sweep（实测 TV 52 部），它静默空转的代价是「缺口不修但没人知道」。弹幕匹配路径（`match.go` / `handlers.go`）同样分不出这三种，改一次两边都受益。 **Depends on / blocked by** — 无。但它动的是共享 client，回归面包含现有弹幕功能。 ## 绑定覆盖率：811 部 R18 绑定（已终态化）+ 5,222 部压根没有 bgm_id **What** — 提高无绑定行的匹配覆盖率。（原本还包含「清理指向已不存在 subject 的绑定」，这半条已被证伪并解决，见下方 09-03 更新二。） **Why** — 这是分集标题缺口里最大的一块，但它是**绑定问题不是富化问题**。5,222 部没有 bgm_id，对应 32,471 个集位完全没有上游可取；另有 811 部卡在 `bangumi_version = 1`，抽样 12 个 bgm_id **12/12 上游返回 404**（`/v0/subjects/207567` 明说 resource has been removed），811 行里只有 1 行在 `bgm_id_map` 里有任何条目——是 `fuzzy_high` 绑到了不存在的 subject id。这批绑定不但补不回一条标题，还在每轮富化里静默消耗上游配额。 **Context** — 2026-09-02 评审实测。这 811 部创建集中在 2026-05-31～06-08，格式以 OVA/ONA 为主。解决后分集标题、中文简介、评分三个缺口一起受益。注意 `bgm_id_map` 是从 `data/anilist_bgm_map.json` 灌进来的**输入**表不是匹配器产物，所以「改进匹配器」和「扩充 map」是两条不同的路。 **2026-09-03 更新** — 这批里有一个子集已经有自动路径了。未绑定行中 826 部在 `bgm_id_map` 里**本来就有答案**，只是够不着：V1 的 tier 0 早就查这张表，但 `UpdateBangumiV1` 带 `AND bangumi_version = 0`，而这些行停在 version 3（migration 0004 记录的 Express 时代批量态），所以答案有了也没人回头用。新的 `bgm_bind_idmap` sweep 补上这个入口，可绑 **791** 部（826 减去 33 部 subject 已被别的行占用、再减去 2 部两行争一个 subject）。剩下的约 4,400 部 map 里没有条目，仍然要靠改进匹配器或扩充 map，本条其余部分不变。 **2026-09-04 收尾** — 已部署（migration 0031，prod `767326bf3522`）并排干完毕：**811 行全部离开 version 1，804 行标为上游不可读，7 行实际读到了并完成 V2 富化，0 行丢失绑定**。`bangumi_version = 1` 这个状态现在在目录里已经不存在，后台「Re-enrich v1」显示 0 并自动置灰。那 7 行（0.86%）正是 migration 拒绝在迁移里批量回填的理由——从 59 个样本推广会把它们一起标错。 **2026-09-03 更新二（推翻了上面 811 那半条的诊断）** — 那 811 部**不是死绑定，绑定全是对的**。真因是 V1 和 V2 用了两个可见范围不同的接口：V1 走老搜索 `/search/subject/{关键词}`，它对匿名调用者返回 R18 条目；V2 走 `/v0/subjects/{id}`，它把 R18 藏起来答 404。我们两边都不带 token，所以 R18 作品必然「绑得上、读不到」。 上面写的「`/v0/subjects/207567` 明说 resource has been removed」是误读：那是 Bangumi 的固定 404 文案，原文 *can't be found in the database **or** has been removed*，并不声称条目被删。拿 207567 去老搜索接口查，`僧侶と交わる色欲の夜に…` 好好地在结果里；另抽的 63029、46533、109596 同样在。抽 59 个卡住的 bgm_id 全部 404，抽 3 个已完成 V2 的绑定全部 200 —— 差异在接口不在条目。判据还有一条：这 811 行 `bangumi_score` 全为 NULL，而只有 V2 写这个字段。 **所以修法方向和原条目相反：必须保留绑定**（有 token 就立刻可用，清掉还会把 subject 当无主交回 id-map sweep）。migration 0031 加了 `bangumi_subject_unreadable_at`，V2 在 subject 404 时写终态（`GREATEST(bangumi_version,3)` + 打戳 + 钉住绑定），后台 v3 图例多一行「其中 N 上游不可读」。**排干动作**：部署后在后台点一次 `Re-enrich v1`，811 行各花一次真实请求离开 version 1；不在 migration 里回填，因为样本给的成功率上限约 5%、不是零，从样本推广会把本该能富化的行标错。约 2,433 次 bgm 请求（subject/characters/episodes 三路并发），按 800ms 桶约 30 分钟，期间分集标题和简介回填要排在后面。 唯一还留在这一条里的，是那 5,222 部没有 bgm_id 的（其中约 4,400 部 map 里也没有条目）。 **Depends on / blocked by** — 无。与 `## 分割放送会 50% 概率绑错` 同属绑定质量，建议合并考虑。 ## `anime_cache.bgm_id` 没有唯一索引，541 个 subject 已经被多行同时持有 **What** — 给 `anime_cache.bgm_id` 加唯一约束；加之前必须先裁定那 1,161 行。 **Why** — 「一个 bgm subject 对应一部番」这个假设全仓到处在用，但数据库不保证它，而且**已经被破坏了 541 次**（541 个 bgm_id 被 2 行以上持有，共 1,161 行）。直接后果：`GetAnimeByBgmID` 是 `:one` 查询，对这 1,161 行返回的是任意一行——`resolveSiteAnime` 第 2 腿和 `findSiteAnime` 第 3 腿都走它，所以 `/match` 的 siteAnime 结果对这批番是不确定的。任何「按 bgm_id 拉数据写回」的作业也会把同一份中文名和简介写到多部番上。顺带一提这一列**连普通索引都没有**，每次按 bgm_id 查都是全表扫（实测 18,009 行）。 **Context** — 2026-09-03 写 `bgm_bind_idmap` sweep 时量到。⚠️ **不是所有重复都是错的**：Bangumi 有时用一个 subject 覆盖 AniList 拆成两季的内容，那种重复是数据模型差异不是绑定错误。所以不能一刀切去重，得先按「同一 subject 的两行是不是同一部作品的不同季」分类。新 sweep 自己不会让这个数字变大——它拒绝任何已被占用的 subject，也拒绝两行争同一个 subject 的情况——但它也修不了存量。 **2026-09-08 补** — river 注册表那轮的跨模型评审从另一头撞上了同一件事，结论是这条 TODO 的措辞比那边的假设更准，记一下差在哪： 评审提出的是「`bgm_bind` 队列的 `MaxWorkers: 1` 陈述了一个正确性不变量，而 `cmd/bgmbackfill` / `cmd/hantbackfill` 是进程外的第二个写入方，所以那个保证不成立」。核实为真，但只对了一半——**这条不变量不是「离假只有一个 `--apply` 标志的距离」，它已经假了 541 次**。单槽位买到的是「这个 sweep 不会让这个数字变大」，不是「这个数字是 0」。 已经做了的是措辞那一半：`internal/queue/registry.go` 的 `FixedConcurrency` 文档现在明说 MaxWorkers 是**进程内**保证、理由必须按「这个槽位买到了什么」来写；`registry_default.go` 里 `bgm_bind` 那条按本 TODO 的实测重写了。机制那一半就是本条，前提仍然是先裁定那 1,161 行——唯一索引加不上去不是因为没想到，是因为数据现在过不了。 **Depends on / blocked by** — 无。与 `## 绑定覆盖率` 和 `## 分割放送会 50% 概率绑错` 同属绑定质量。 ## dandanplay 的额度是按功能组按天算的，而回填和线上弹幕共用同一个组 **What** — 给共享额度加一层显式预算与观测：回填运行前后记录各组用量，并让 `/match` 在番剧详情组耗尽时给出可区分的错误，而不是和「这个条目上游确实没有」返回同一个 404。 **Why** — 额度结构是：每个功能组**每天 5,000 次**、每月 120,000 次。`/api/v2/bangumi/bgmtv/:id` 和 `/api/v2/bangumi/:animeId` 都归在**番剧详情**组，而这个组同时是 `/match` 取分集列表用的组（Phase 1 和 Phase 2 都走它）。所以一次不设上限的回填不只是自己跑到停——**它会把线上弹幕功能一起带下线到当天结束**。这是实测的：2026-09-03 一次分集标题回填把该组跑到 5,000/5,000，之后线上 `/api/dandanplay/episodes?bgmId=291171` 对**同一轮跑批两小时前刚成功读过分集标题的 subject** 返回 `Anime not found on dandanplay`。 **Context** — 已经做了的一半：`--limit` 默认从 0（无上限）改成 4,500，留出一成给线上；同时修了缓存命中被计进请求数导致这个预算失准的问题。没做的一半是观测——现在要靠人去看控制台才知道用了多少，代码里没有任何一处知道自己离上限还有多远。另外**月额度完全不是瓶颈**（当月只用到 8%），唯一的稀缺资源是「天」，所以长回填的正确形态是跨天分批而不是一次跑完。 **Depends on / blocked by** — 无。与 `## dandanplay client 把所有 4xx 压成「没有数据」` 是同一处症结的两面：那一条让调用方分不清故障与稀疏，这一条说明分不清的代价有多大。 ## 分集标题：从没被问过的存量已清零，剩下 4,138 行是绑定问题不是进度问题 **What** — 不再有「再跑一轮」这个动作。要么给「问过」单独记一列（见下），要么分别处理剩下三类的绑定质量问题。 **Why** — 2026-09-05 那轮把最后 2,709 行**从没被问过**的候选一次跑完（`SKIPPED` 0，在预算内收尾）。此后剩余的 4,138 个候选**全部至少被问过一次**，构成约为：`NO_TITLES` ~2,489（dandanplay 索引里没有这个 subject）、`UNDECIDED` ~1,021（没有任何独立来源为绑定背书）、`DDP_REBIND` ~575（dandanplay 说这个 subject 属于另一个 anilist 条目）、`SCOPE_MISMATCH` ~42。再跑一轮 = 花 4,138 次共享额度把上一轮的答案重听一遍，而这三类每一类都要靠改绑定、不是靠再问一次。 **Context** — 2026-09-05 实测。★★ **`--resume` 跳过的是「写成功」不是「问过了」**：`episode_titles_at` 只在写标题的事务里打戳，所以答不出来的行永远留在候选列表头部。今天第一次启动就撞上这个——200 行只写 1 行、196 次请求，照这个走法 4,000 次预算的 68% 会花在昨天已经判过的行上。★ 修法是新加的 `--start-after-id N`（PR #155），**预算工具不是正确性工具**：跳过的行仍是候选、仍没打戳。断点 `141932` 是反推的——重建 09-04 那轮的候选集（6,910 行），它最后一次写入排在第 4,132 位，正好是 4,000 次预算耗尽处。★ 那一轮成果：WRITTEN 1,296 / NO_TITLES 969 / UNDECIDED 265 / DDP_REBIND 159 / SCOPE_MISMATCH 20，2,628 次请求；库里 +1,040 条新标题、+2,327 条中文名、+68 部番剧首次有标题、打戳 8,092 → 9,390。★★ **报告里的 `titles written` 数的是被 upsert 碰到的行不是新增行**（`UpsertEpisodeTitleSourced` 的 `DO UPDATE` 没有 WHERE），所以 15,441 与库里 +1,040 并不矛盾——同一个口径问题对 3.26.0 记的 17,646 同样成立。 **Depends on / blocked by** — 无。 ## 把「问过」和「写过」分开记，`--resume` 才名副其实 **What** — 给 `anime_cache` 加一列（比如 `episode_titles_asked_at`）在**每次真的走到网络之后**打戳，与只在写入事务里打的 `episode_titles_at` 并存；`--resume` 读前者，`--start-after-id` 就可以退休。 **Why** — 现在这两件事共用一个戳，而它只记录后者。后果是每一轮回填的头部都是上一轮答不出来的行：2026-09-05 那轮开跑时，5,436 个候选里 2,730 个属于这一类，占一天预算的 68%，而它们的判决（`NO_TITLES` / `UNDECIDED` / `DDP_REBIND`）不会隔夜改变。`--start-after-id` 用一个人工传入的 id 绕开了它，代价是这个 id 得靠反推、而且只在「上一轮是被预算截断的」这个前提下成立。 **Context** — 2026-09-05 加 `--start-after-id` 时记下。⚠️ 新列必须**只在真的发出了请求之后**打戳（`asked_upstream`），缓存命中不算——否则同一轮里共享 subject 的第二行会被误标为问过。另外要想清楚重问周期：`NO_TITLES` 有朝一日可能变成有（dandanplay 补录），所以这个戳应该是「多久之后可以再问一次」而不是「永不再问」，形状和 `ListReleasingEpisodeTitleCandidates` 的 `stale_after` 一样。 **Depends on / blocked by** — 无。 ## dandanplay 交叉链接补 bgm_id：**探针已跑完，结论是做 sweep** **What** — 实现搜索驱动的 sweep：每行一次 `SearchAnime`，对前 2 个候选取 `FetchEpisodesByDandanAnimeID`，用 `onlineDatabases` 的 AniList 交叉链接**等值**作精度闸门，subject 未被占用才写。（原 What 是「先跑探针决定形态」，探针已于 2026-09-04 跑完。） **Why** — id-map sweep 已经把它能答的 791 行全绑完了，剩下约 4,463 行 map 完全没有条目，dandanplay 是唯一够得着的来源。两个方案**证据结构完全相同**（搜索只负责召回，`onlineDatabases` 的 AniList 交叉链接**等值**才是精度闸门），差别只在覆盖面和成本：机会捕获零请求但只碰得到用户恰好播放的那一小撮；sweep 覆盖全部但约 8,900 次请求 ≈ 两天的日额度。没有数据就在这两者间选，是在拿论证代替测量。 **Context** — 探针是只读的，报告里带**命中位置直方图**——那个数就是 sweep 的每行请求成本（若命中全在第 1 位，候选上限可以降到 1，每行两次请求）。★ 已查清的两件事：**`description_cn_eligible` 不用改**（它要求 `bgm_id_map` 同意，而这条路只在 map 沉默处动手，所以这类绑定天然拿不到中文简介资格——爆炸半径最大的公开字段已被现有闸门挡住）；**dandanplay 没有配额查询接口**（开放文档无此端点、`dev.dandanplay.com` 那页是 SPA 不渲染、swagger 404），所以额度只能靠人看控制台。★★ 搜索走的是**搜索组**（独立额度，长期闲置），只有详情腿和分集标题回填抢同一个组——排期时这两件事要错开。 **2026-09-04 探针结果（n=600，全目录每 7 行取 1，非头部样本）** | 分类 | 数量 | 占比 | |---|---|---| | BINDABLE | 41 | 6.8% | | SUBJECT_TAKEN | 3 | 0.5% | | NO_BGM_LINK | 36 | 6.0% | | ANILIST_MISMATCH | 37 | 6.2% | | NO_ANILIST_LINK | 25 | 4.2% | | **NO_SEARCH_HIT** | **455** | **75.8%** | | FETCH_FAIL | 3 | 0.5% | 绑定率 6.8%（95% CI 4.8%–8.9%），全量 4,465 行外推 **约 305 行可绑**，成本约 5,983 次请求。 **结论：做。** 成本落在两个不同的额度组上——约 4,465 次搜索走**搜索组**（该组常年闲置，月用量 363/120,000），约 1,518 次详情走**番剧详情组**（一天配额的 30%）。也就是一天跑完、约 305 个新绑定，而且是一次性的，这批不会快速再生。相比之下机会捕获对这批**几乎必然为零**：75.8% 的行 dandanplay 索引里根本没有，用户也不会去播这些冷门条目。 ★ **候选上限从 3 降到 2 零代价**：命中位置直方图是 `#1 → 76, #2 → 4, #3 → 0`，第 3 位一次都没命中过。降到 1 会丢 5% 的命中（4/80），不划算。 ★★ **75.8% 的 NO_SEARCH_HIT 是这条路的天花板，和匹配算法无关** —— dandanplay 索引里没有这些条目，再好的匹配器也够不到四分之三。所以「补 bgm_id」这件事的上界是 24.2%，不是 100%；剩下那部分只能靠扩充 `bgm_id_map` 或别的来源。 ⚠️ **第一次跑的探针结果（0 BINDABLE）是假的，别拿来引用。** 那次番剧详情组额度已耗尽，而当时的客户端把「200 + success:false」读成「这个条目没数据」，于是 103 次详情调用全是配额拒绝却被记成了 `NO_ANILIST_LINK`。坐实它的证据是 dandanplay 后台的月度计数只 +1。客户端已修（见下一条）。 **Depends on / blocked by** — 番剧详情组的当日额度；与上一条抢同一份预算（搜索腿不抢）。 --- ## 目录里够不着的那批条目的预告片 **What** — 给 `anime_cache` 里 `season` 或 `season_year` 为 NULL 的行补一条按 id 批量拉取的回填路径：新增一个 `Page(media: id_in: [...])` 的 AniList 查询常量 + 客户端方法 + 一个 river job，每页 50 个 id，按 `trailer_checked_at IS NULL` 取批。 **Why** — 迁移 0032 之后 trailer 只有两个写入口：`warm_season`（按 season+year 向 AniList 取整季）和详情页回源。前者按季度查，够不着没有季度的条目；后者要等有人打开那一页。2026-09-06 实测：全目录 18,048 行里 **4,500 行**没有季度（剧场版 / OVA / 特典），其中 **167 行**会出现在 `/api/anime/completed-gems` 的候选池里（该池共 1,610 行，占 10.4%）。也就是说 gems 列表大约每十张卡就有一张永远拿不到预告片，直到它自己的详情页被访问过一次。 **Pros** — 覆盖补齐到 100%；这条「按 id 批量补一个 AniList 字段」的能力是通用的，下一个要给存量行补的字段可以直接复用，不用再想一遍。 **Cons** — 新 job kind + 查询常量 + 取批 SQL + 配套测试约 250 行，而它在真实消费面（列表接口）上换来的增量只有 167 行。剩下的 4,333 行只能从详情页进，而详情页第一次访问就自己填了。 **Context** — 这条是 2026-09-06 `/plan-eng-review` 评审 PR #167 时的 D3 决策的另一半：当时选了「跑现成的 warm-all」而不是新建回填 job，理由就是上面这个 167 : 250 行的比值。⚠️ **warm-all 必须带 `?startYear=1940`**（`internal/admin/warm_all.go:47` 的默认值是 2014，而目录里最早的 `season_year` 是 1940，`season_year < 2014` 的有 7,202 行，其中 511 行落在 gems 池里——不带这个参数会把 gems 池的覆盖率从 89.6% 打到 58%）。触发条件：Nagare 那边反馈 Discover 里空白卡片明显，或者要把预告片用在别的以 gems 为数据源的位置。 **Depends on / blocked by** — 无。与 warm-all 互补而非互斥。 > **前提已变（2026-09-08，迁移 0033）** — 这条的 Cons 算的是「新 job kind + 查询常量 + 取批 SQL + 配套测试约 250 行」。其中的**查询常量和客户端方法现在已经存在**：`anilist.MediaRatingsQuery` 就是 `Page(media: id_in: [...])`，`anilist.Client.Ratings` 是它的调用方，`anilist.MaxRatingIDs` 是那个 50 的上限（AniList 超了是**静默截断**不是报错，所以上限在 `Ratings` 里挡，不能只靠调用方自觉）。剩下要写的只有取批 SQL 和 job 本身，而 `queue/ratings_refresh.go` 里那条 AniList sweep 的分批 + 「没返回的 id 也要盖戳」逻辑可以照抄。167 : 250 的比值应当重算。 > > ~~⚠️ 但**先确认 AniList 恢复了再动**：2026-09-07 起 `graphql.anilist.co` 对所有查询返回 403。~~ **2026-09-08 更正**：AniList 没有停摆，是我们的客户端没发 `Referer` 头，而它把这个拒绝说成了「API 已临时停用」。已修（`internal/anilist/client.go` 的 `requestReferer`）。这条不再有阻塞。 --- ## sitemap 的 lastmod 说的不是「内容什么时候变的」 **What** — 让 `anime_cache.updated_at` 只在内容真的发生变化时才推进（`ON CONFLICT` 的 `updated_at` 加一个 `IS DISTINCT FROM` 判断），或者给 `ListSitemapShard` 换一个内容级的 lastmod 来源。 **Why** — `ListSitemapShard` 自己的注释写着「updated_at, not now(): Google discards lastmod it can prove wrong, and "every URL changed this second, on every fetch" is provably wrong」。但 `UpsertAnimeCache` 的 `ON CONFLICT` 无条件 `updated_at = now()`，而五个写入方里有三个是流量驱动的（详情回源、search 命中、seasonal 冷启动）。于是注释想避免的那件事，正在以周为单位发生。 **Pros** — sitemap 的 lastmod 变成真信号，而 SEO 是这个项目的主线；顺带让「这行最后一次真的变了是什么时候」这个问题第一次有答案。 **Cons** — 改的是五个写入方共用的那条 upsert，爆炸半径远大于任何单个特性；而且 SEO 侧的收益无法在上线前验证，只能上线后看 GSC。 **Context** — 2026-09-06 实测 prod `anime_cache`：24 小时内 `updated_at` 被改过的有 **5,827 行（32%）**，7 天内 **17,692 行（98%）**，30 天内 **100%**。即全站 lastmod 每周整体翻新一遍，而内容并没有变。这条最初由 PR #167 评审的外部声音提出（担心 warm-all 会造成 lastmod 风暴），拿上面这组数字验证后结论反转：warm-all 的边际影响很小，因为基线本来就是全量翻新——问题不在 warm-all，在 upsert 语句本身。 **Depends on / blocked by** — 无。但改动应当单独走一个 PR，并且和一次 GSC 观察窗口配对。 --- ## 对外的 trailer 类型仍然是上游的解码结构体 **What** — 在 `internal/anime` 定义 `DetailTrailer{ID, Site}`，`assembleDetail` 转换一次，不再把 `anilist.Trailer` 直接当成公开 API 类型。 **Why** — `internal/anilist/types.go` 自己写着「field tags 跟 AniList GraphQL 字段名一致，不要改名，encoding/json 的 tag 就是契约」。同一个结构体现在同时背着两份契约：AniList 的解码格式，和我们对下游消费方的承诺。上游改名时，改 tag 会静默改变对外响应，不改 tag 会静默打断解码。 **Pros** — 两份契约解耦，各自独立演进；四行代码。 **Cons** — 与 `/search` 响应直接暴露 `anilist.PageInfo` 的现有做法不一致，要么两个一起改要么就是仓里有两套做法。 **Context** — 2026-09-06 查过下游消费方的实际代码后，这条的优先级被判定为**低**：消费方用自己的匿名结构体解码，而它的前端把 trailer id 直接拼进 `youtube-nocookie.com/embed/${id}`、**根本不读 site 字段**。所以 `site` 改名的实际影响为零；只有 `id` 改名会出事，而那种情况下我们自己的解码同样会静默失效——拆不拆类型都挡不住。同一轮还确认了 `trailer,omitempty` 不需要改：消费方是 Go 的 `encoding/json` 解到指针，「缺键」和「null」结果完全一样。 **Depends on / blocked by** — 无。真要做的话和 `anilist.PageInfo` 那处一起改，否则只是把不一致换个地方。 --- ## AniList 的评分人数已经入库，但还没有人读得到 **What** — 把 `anime_cache.anilist_score_votes` 接到详情响应上（`internal/anime/detail.go` 的 `BangumiVotes` 旁边加一个同形状的字段），然后在详情页 AniList 那一格里渲染，与 Bangumi 那格对称。 **Why** — 迁移 0033 把这个数存进了库，但**没有任何 SELECT 读它**，所以目前它是纯粹的写入。而这个不对称在页面上是肉眼可见的：`next-app/src/app/[lang]/anime/[id]/page.tsx` 里 Bangumi 那一格已经渲染 `{detail.bangumiVotes.toLocaleString()} {dict.detail.votes}`（第 816 行附近），AniList 那一格只有一个 `84 / 100` 和一根进度条，没有任何东西说明这个 84 背后是四十个人还是四万个人。存这一列的全部理由就是让这两个数能放在一起看。 **Pros** — 三处小改动（sqlc 的 SELECT 列、`detail.go` 的响应结构体、页面上一个已经存在的 `scoreVotes` 样式类），文案 `dict.detail.votes` 三个语言都已经有了。收益是详情页第一次能说清两个来源各自的样本量。 **Cons** — 改的是公开响应的形状，而这个响应有跨仓下游（`/Users/lawrence_li/nagare`）。加字段本身对它无害（Go 的 `encoding/json` 解到自己的匿名结构体，多出来的键会被忽略），但按仓库既有规矩，改响应形状要去那边看一眼再动。另外**在 AniList 恢复之前这一列全是 NULL**，上线了页面上也什么都不会显示——所以这条的自然时机是那条 sweep 真的跑过一轮之后。 **Context** — 2026-09-08 随迁移 0033 一起识别，当时刻意留在范围外：入库和呈现是两步，而第二步要碰公开契约。数据来源是 `stats.scoreDistribution` 各档 `amount` 之和（`anilist.Media.ScoreVotes`），不是 `popularity`——后者数的是把作品加进列表的人，大部分没打分。 **Depends on / blocked by** — 无。（本条原写「被 AniList 的 403 挡着」，那个 403 是我们自己少发 `Referer` 造成的，2026-09-08 已修。）实际前提只剩一个：等那条 sweep 真的跑过一轮、列里有数了再接页面，否则呈现一个全是 NULL 的列没有意义。 --- ## Bangumi 的票数列没有 CHECK **What** — 给 `anime_cache.bangumi_votes` 加一条 `NOT VALID` 的非负 CHECK，然后在确认存量行干净之后 `VALIDATE`。 **Why** — 迁移 0033 给 `anilist_score_votes` 加了 `anime_anilist_rating_pair`，理由是 sweep 会吞掉单行写入失败，一个被约束挡下的值在生产上唯一的症状是那一行悄悄不再刷新——所以得由列来拒绝。`bangumi_votes` 承受同样的写入方（现在多了 `UpdateBangumiRating`）却没有任何约束，纯粹因为它比 0033 早了 32 个迁移。 **Pros** — 两列的保护面拉齐；`NOT VALID` 加约束不锁表。 **Cons** — 要先确认存量行没有违例，而这需要跑一次全表查询并对结果负责；这件事属于愿意做 `VALIDATE` 的那个人，不属于只是新增一列的那个迁移。 **Context** — 2026-09-08 写迁移 0033 时明确留下的一条，迁移注释里也写了同样的话。 **Depends on / blocked by** — 无。 --- ## sweep 和用户请求共用同一个 AniList 额度，没有优先级 **What** — 让后台 sweep 从一个**低优先级**的额度里取令牌，或者至少在检测到用户侧请求排队时让路：给 `anilist.Client` 加一个 `Priority` 维度，或者给 sweep 一条独立的、总和仍在 30/min 之内的更慢通道。 **Why** — 额度是 30/min（`x-ratelimit-limit`，2026-09-08 实测），全站共享一个 token bucket。今天这不成问题，因为两条 sweep 都是串行发请求，任一时刻队列里最多一个后台请求，用户最坏多等一个 `minInterval`（2.1s）。**但这个结论完全依赖「串行」这个实现细节，而那个细节没有任何东西守着**——谁把批次改成并发拉取（一个很自然的「加速回填」想法），用户侧的排队就会从 2.1 秒变成整批的长度。 **Pros** — 后台工作再也不能挤占前台；也让「加速 sweep」这件事变成可以安全考虑的选项。 **Cons** — `golang.org/x/time/rate` 没有原生优先级，要么两个 limiter 手工分配额度（分错就是浪费或超额），要么在 `do()` 里加一层等待队列。而今天的实际收益是零，因为串行已经够用。 **Context** — 2026-09-08 修 `minInterval`（700ms → 2.1s）时识别。触发条件：任何把 sweep 改成并发的改动，或者额度被进一步下调。 2026-10-08：`anime_credits` sweep（`internal/queue/anime_credits.go`）是第一条会让路的 sweep——全部请求走 no-wait（令牌空闲才取，有人排队时 `Allow()` 直接拒绝），每次请求前隔 6 秒，忙就重试三次后结束本轮。facts / ratings 两条仍是排队模式；要统一的话照它改，不需要动 limiter。 **Depends on / blocked by** — 无。 --- ## 24h 读时刷新应该离开请求路径，改成 river sweep **What** — 新建一个每小时跑的 `detail_refresh` sweep（参照 `internal/queue/anime_facts.go` 的 500 行/小时节奏），按 `cached_at` 最旧优先重拉 AniList 详情；落地后把 `detail.go` `isStale` 里 `cached_at ≥ staleCacheTTL` 那一条去掉，只保留「从没拉过详情 / 角色 role 空 / 关联封面空」这类一次性修复条件。 **Why** — 2026-09-20 实测：按 `anime/detail: stale, re-fetching from AniList` 与详情 200 的计数比，**一半的详情读会在请求路径上内联打一次 AniList**（+600ms）；目录里近一半的行 `cached_at` 超过 24h，爬虫全目录走一遍等于全目录刷新一遍。它是 30/min 额度的九成以上的消耗方（爬虫枚举不存在 id 的 404 不到一成）。「stale 重拉改非阻塞 + 404 负缓存」那个 PR 只是把它从队列里请出去，读路径仍然打 AniList，而且刷新变成尽力而为之后陈旧上界不再有保证。让刷新离开请求路径是 2026-08 eng-review（「SWR 不做，若做走 river job」）和下面「未缓存的详情页…」那条 Context 里「不要在请求路径上冷启动取数」两次指向的方向。 **Pros** — 详情读彻底不碰 AniList；刷新节奏可控（每小时 500 行，与 facts sweep 同一节奏）；`anime_cache.updated_at` 不再被流量驱动翻新，sitemap lastmod 的基线随之变干净。 **Cons** — 多一个 sweep 抢同一个 30/min（每小时 10 次，与 facts/ratings 同量）；当季新番的集数/状态变化到达会慢一点（`warm_season` 已覆盖当季，实际影响小）；要决定「从来没人访问的行要不要刷」——不刷则要给 sweep 一个「最近被读过」的信号，刷则每一轮大半在刷没人看的行。 **Context** — 先看那个 PR 部署后 `stale, re-fetching` 与 `stale, budget busy, serving stale` 两个计数的比例，定 sweep 节奏。入口：`detail.go` `isStale` + `internal/queue` 新 worker + river 注册（`UniqueOpts.ByState` 必须含四态，见 `test/integration/queue_smoke_test.go`）。 **Depends on / blocked by** — 「stale 重拉改非阻塞 + 404 负缓存」PR 先落地；与「sweep 和用户请求共用同一个 AniList 额度」同源。 --- ## bingbot / Semrush 在反复爬一批现在 404 的 `/anime/{id}`，要查它们以前是不是真页 **What** — nginx 日志里详情页的 404 有相当一部分来自 bingbot 和 Semrush，同一批 id 被反复打，另有少量带 `google.com` referer 的真人点击。查这批 id 是不是曾经在 `anime_cache` / sitemap 分片里、后来被删掉或合并掉的：对照 GSC「未找到 (404)」报告、历史 sitemap 分片、以及删行/合并类 migration（同名番剧合并、Hentai 过滤、synonyms 清理都要排一遍）。 **Why** — 搜索引擎爬虫不会凭空猜 id，它们爬的是曾经见过的 URL。如果这批 id 曾经是我们的真页，现在 404 意味着**已索引页面在流失**；如果不是，那是外链污染，可以不管。两种结论的处置完全不同（301/410 vs 无视），所以值得一小时把真假判掉。 **Pros** — 判为真则能定位到具体那次删行，并决定 301 到合并后的 id 还是 410；顺带校验 sitemap 是否还在列已删 id。 **Cons** — 纯调查，要翻 GSC + 旧 sitemap + 数据库历史；可能结论是「外链垃圾」一场空。 **Context** — 2026-09-20 查 Sentry 5xx 时的旁证：把详情页 404 按 UA / referer 分桶即可看到。同一天落地的「404 负缓存」只让这些 404 不再消耗 AniList，不回答它们从哪来。 **Depends on / blocked by** — 无。 --- ## AniList 已删掉的条目我们还留着：补不全、每次缓存过期都再问一次，而且没人知道有多少 **What** — 把「AniList 不再有这个 id」存成一个事实：`anime_cache` 加一列（例如 `anilist_gone_at`），由已经掌握这个信息的地方写入——facts sweep 与 ratings sweep 批量查询时没被返回的 id，以及详情页重拉拿到 AniList 404 的已有行。写了之后 `isStale` 对这种行不再触发重拉；再决定页面怎么对外：照常保留、从 sitemap 去掉、`noindex`，或者能找到合并目标时 301 过去。 **Why** — 2026-09-23 对 #201 做线上测试时看到：库里一直补不全（`trailer_checked_at` 为空）的几行，全是 AniList 已经删掉的老番 Specials。每次进程内缓存过期后有人访问，它们就排队问一次 AniList，拿 404，记一条 Warn，返回旧行——这是一个永不收敛的重试。数据完整、只是后来被 AniList 删掉的行同样如此，只是走不排队的那条路。三个问题： - **没人知道有多少。** 两个 sweep 其实知道哪些 id 没被返回，但它们把这种行和「查过了」打成同一个戳（`MarkAnimeFactsChecked` / `MarkAnilistRatingChecked`，为的是别让它们永远排在批次最前），唯一留下的痕迹是每轮日志里的一个计数 `rowsAbsentUpstream`。 - **页面对外的说法是错的。** 详情页 JSON-LD 的 `sameAs` 固定带 `https://anilist.co/anime/{id}`（`animeJsonLd.ts`），对这些行它指向一个 AniList 已经不认的条目；sitemap 按 `anime_cache` 出，它们也在里面。 - **负缓存帮不上。** #201 的 `absent` 只在冷 id 分支写（DB 先行，行存在就读不到它），有意如此——所以对「我们有、AniList 没有」的行，每小时一次的重问不会停。 **Pros** — 重问归零；第一次能回答「目录里有多少条目在上游已经不存在」；SEO 处置有了依据，不用猜。 **Cons** — 多一列加一条 migration；两个 sweep 的「没返回」要和「这批请求失败」严格分开（后者现在整批不打戳，这个区分已经有了，但写新列时不能弄混）；AniList 偶尔会把条目合并到另一个 id，只知道「没了」不知道「去哪了」，301 需要另找来源（AniList 不给合并目标），做不到就只能 `noindex` 或保留。 **Context** — 线上测试见 CHANGELOG「详情页的 AniList 额度」条目的「部署后」段。入口：`internal/queue/anime_facts.go` `applyBatch` 的第二个循环、`ratings_refresh.go` 同位置、`internal/anime/detail.go` stale 分支拿到 `NOT_FOUND` 的地方、`isStale`。与「bingbot / Semrush 在反复爬一批现在 404 的 `/anime/{id}`」是镜像问题：那条是「我们没有、爬虫以为有」，这条是「我们有、上游已经没有」。 **Depends on / blocked by** — 无。 --- ## 未缓存的详情页在 AniList 够不到时返 502，而且没有可降级的数据 **What** — 给「行不存在 + AniList 取不到」这条路径一个比 502 更好的答案：要么 404（我们确实没有这个条目），要么排队补齐后返回 202/占位，而不是把上游失败原样透出。 **Why** — `detail.go` 已经有优雅降级，但它只在**行存在**时生效（「re-fetch 失败就返回已读到的陈旧行」）。行不存在时没有任何可返回的东西，直接 502。2026-09-08 实测两例（`88764`、`108289`，两者都不在 `anime_cache` 里），成因是 `anilist: rate limit wait: rate: Wait(n=1) would exceed context deadline` —— 限速器排队超过了请求的 5 秒预算（`queryTimeout`）。当时代码里写着 15 秒的 `refetchTimeout`，但它套在已带 5 秒 deadline 的 ctx 上，子 ctx 活不过父 ctx，从未生效（Sentry `duration_ms: 5001`）；2026-09-23 已删。 **Pros** — `/anime/*` 是 SEO 主力面，502 是这个仓库已经为之修过一轮的东西（见「详情页 500 爬虫×限流」）。 **Cons** — 「我们没有这个条目」和「我们暂时取不到」是两件事，用同一个状态码回答任何一件都会误导某一方；要分开就要引入一个新的响应形状。 **Context** — 2026-09-08。`minInterval` 从 700ms 提到 2.1s（限流实际额度 30/min）之后这个窗口变宽了 3 倍：5 秒预算在 700ms 时容得下约 7 个排队请求，2.1s 时只有 2 个。**2026-09-23 进展**：占队列的大头（stale 读时重拉，≈340/h）已改成不排队的 `DetailNoWait`，冷 id 队列里只剩冷 id 自己和 sweep 批次。**根因不是这个常量，是 30/min 对一个会在用户请求上做冷启动取数的站点本来就很紧** —— 真正的解法在「后台工作应有独立额度」那条，以及不要在请求路径上冷启动取数。实测频率很低（18 分钟 2 个）。 **Depends on / blocked by** — 与「sweep 和用户请求共用同一个 AniList 额度」那条同源。 --- ## 部署杀出的孤儿作业会压制 sweep 一小时（三个 sweep 都有） **What** — 让周期 sweep 不再依赖 `UniqueOpts` 去防重：去掉唯一性，改为靠队列的 `MaxWorkers: 1` 加候选查询的读取时间戳。或者调低 river 的 `RescueStuckJobsAfter`（默认 1 小时），但要先确认没有作业的正常时长会撞上这个窗口。 **Why** — `running` 行不代表有 pass 在跑，部署杀进程不改它，rescuer 一小时后才回收。这一小时里 `RunOnStart` 的入队被自己的尸体压制，而且**没有症状**（不产出 = 追平了，两者同形）。2026-09-08 实测：一次部署后 `anilist_ratings` / `bangumi_ratings` / `hant_backfill` 同时卡 59 分钟。 ⚠️ **不要用「把 running 从 ByState 拿掉」来修**。已经在生产上试过并回滚：river 的 `UniqueOpts.validate` 强制要求 available/pending/running/scheduled 四个都在，少一个会让 `PeriodicJobEnqueuer` 对该 kind 整个失败——只留一行 ERROR 日志，服务照常跑，sweep 再也不入队，一小时的压制变成永久。守卫见 `TestRatingsUniqueStatesMatchRiver`。 **Pros** — 三个 sweep 一起受益；ratings 是每小时跑的，一小时的窗口对它最不能忍。而且去掉唯一性对 ratings 本来就安全：候选资格是读取时间戳，紧接着的第二次 pass 取的是下一批，不是重复劳动。 **Cons** — 去掉唯一性后 river 行会累积（每小时一条，24 条/天，completed 会被 river 自己清理）；如果 worker 卡住，作业会堆积而不是被合并。`hant_backfill` 是**整表**pass，对它去掉唯一性要更谨慎——两次并发全表 pass 是真的重复劳动，它依赖的是 `MaxWorkers: 1`。 **Context** — 2026-09-08。ratings 每小时跑所以最疼；`hant_backfill` 是季度作业，一小时对它无所谓。 **Depends on / blocked by** — 无。 ## 角色中文名全库 0 行：V2 写的字段上游没有，写了也会被详情重拉整表删掉 **What** — 让 `anime_characters` 的富化列（`name_cn` / `voice_actor_cn`）真的能落地并且活过下一次详情重拉；或者承认 Bangumi 那条路给不了，删掉 V2 里这段死代码。 **Why** — 两个各自独立就足够致命的原因叠在一起： 1. **上游没有这个字段。** V2 走的是 `GET /v0/subjects/{id}/characters`，客户端解码 `Character.NameCN` / `Actor.NameCN`（`internal/bangumi/client.go:217-229`），但这个端点返回的字符对象只有 `id / name / type / images / relation / summary / actors`，演员对象只有 `id / name / type / images / career / locked / short_summary`——**两层都没有 `name_cn`**（2026-09-15 对 400602 实测）。所以 `bangumi_v2.go:336-345` 算出来的 `nameCN` 和 `voiceActorCN` 永远是 nil，`UpdateAnimeCharacterCN` 即使命中也是写两个 NULL。中文名在 Bangumi 上要 `GET /v0/characters/{id}` 逐个拉（在 `infobox` 里），一部番几十次请求。 2. **写了也活不过一天。** 详情重拉（`detail.go:762-766`）对 `anime_characters` 是 `DeleteAnimeCharacters` + 逐行 `InsertAnimeCharacter`，插入时 `name_cn = NULL`（`normalize.go:203` 自己注释「V2 之后填」）。任何 V2 写进去的东西在下一次 24h TTL 到期时整表消失，而 V2 是单向棘轮不重跑。生产库 82,274 行 characters 里 `voice_actor_image_url` 带 `bgm.tv` 的是 **0**——这才是「UPDATE 从没留下过痕迹」的直接证据（V2 命中时会把它覆成 Bangumi 图）。 顺带一个被这两条掩盖的 bug：`bangumi_v2.go:349-352` 把**角色**的 `c.Images.Medium` 写进 **`voice_actor_image_url`**，声优的图在 `c.Actors[0].Images`。现在没人看见，是因为它从来没成功写过。 **Context** — 2026-09-15 元数据计划 1.4 的调查结论，封顶半天，实际 20 分钟。不在阶段 1 修，因为正确的修法依赖阶段 2.2：`anime_characters` 存 `character_id` 之后，详情重拉才能改成按 `(anime_id, character_id)` upsert 而不是删表重建，富化列才有地方活下来；而中文名本身要么接 `/v0/characters/{id}`（按角色数计费，只值得对主角做），要么放弃。在那之前 V2 的这一段是死代码，删掉比留着更诚实。 **2026-10-08 更新** — 第 2 条已解除（migration 0042）：详情重拉和 `anime_credits` sweep 都按 `(anime_id, character_id)` upsert，`UpsertAnimeCharacter` 不写 `name_cn`，别处写进去的值能活过重拉；`voice_actor_cn` 只在 `voice_actor_id` 不变时保留。没有 character id 的旧行仍会在下一次重拉时删除。第 1 条（上游没有这个字段）仍在。 **Depends on / blocked by** — 阶段 2.2（角色 id）。与 `## bangumi_version 是单向棘轮` 同属一根。 --- ## 补全 sweep 跑完后重跑 bgmnames，并把它做成每周自动任务 **What** — 等 `anime_credits` sweep（角色、职员）和 `profiles` sweep（人物、角色资料）的首轮回填跑完，用当时最新的 Bangumi Archive 数据包（，每周二 21:03 UTC 发布）重跑一次 `cmd/bgmnames`：先不带 `--apply` 跑一遍，看配对数、冲突和将要改动的行，确认后再加 `--apply` 写入。长期把它从手动工具改成定时任务：新数据包发布后自动下载、校验、应用，不再依赖人记得每周去跑。 **Why** — 角色和人物的中文名（`bgm_character_map` / `bgm_person_map` 的 `name_cn`）以及角色简介（`bgm_character_map.summary`）只在 bgmnames 运行时写入，而它目前只在 #217 部署时跑过一次。之后两条 sweep 每小时都在往库里加角色和人物，这些新行在下一次运行之前都没有中文名，角色标签页、角色页、人物页上只显示 AniList 的名字。bgmnames 匹配的是库里当前的行，所以即使数据包没换，重跑也能补上这部分；一次写入是一个事务，跑完两张表正好等于这一轮的结果，重复运行是安全的。 **Pros** — 中文名和角色简介重新和库里的角色、人物对齐；做成定时任务后每周的新数据包自动生效。 **Cons** — 每次要下载约 440 MB 的数据包，解压其中 4 个 jsonlines 文件。做成定时任务要把工具放进镜像（现在不在镜像里），并处理下载失败、校验和与临时文件的磁盘占用。只有已绑定 Bangumi 的番，它的角色和人物才配得上，没绑定的不受益。 **Context** — 2026-10-11 核对时，首轮回填预计还要 3–4 天：角色约 30 小时，人物资料约 1 天，角色资料约 3 天，职员约 4 天。判断跑完的办法：`ListAnimeCastCandidates` / `ListAnimeStaffCandidates` 里不再有从未扫过（`cast_checked_at` / `staff_checked_at` 为空）的行，`ListPeopleCandidates` / `ListCharacterCandidates` 不再返回缺资料的人物和角色。下一个数据包是 2026-10-13，届时用最新的那份。 **Depends on / blocked by** — 两条 sweep 的首轮回填完成。 ## 预压范围第二期：详情页的预告片缩略图 **What** — 把详情页的预告片缩略图（i.ytimg.com，页面实际请求的宽度）加进 `image_variant_warm` 的夜间预压清单，并在 nginx 的 `$next_image_zone` 里把这些尺寸算作页面尺寸。 **Why** — 第一期上线后，详情页首屏只剩预告片缩略图在第一次打开时要现压，实测要好几秒。 **Pros** — 有预告片的番，详情页首屏的图全部从缓存出。 **Cons** — 源图在 YouTube，不在我们的原图镜像里：压图服务要直接回源 YouTube，`image_manager` 也不记录这类图，所以「只压镜像里已有原图的」这条规则管不到它，YouTube 回源的失败和限流要单独处理。分区规则现在只认 AniList 地址，要为 YouTube 地址另写一条。 **Context** — 第一期只覆盖 AniList 图（详情页、季度页）：见 `nginx/default.p9.conf` 的 `$next_image_zone`、`go-api/internal/queue/image_variant_warm.go`、`next-app/src/lib/images/imageVariantShapes.test.tsx`。预告片缩略图由 `next.config.ts` 里 i.ytimg.com 的 remotePatterns 放行。 **Depends on / blocked by** — 第一期上线后，用 `/_next/image` 访问日志行尾的 `cache=… zone=…` 字段确认预告片缩略图的请求占比和命中率，值得再做。 ## 预压范围第二期：2 倍屏手机用的 828 宽横幅 **What** — 把 828 宽的横幅加进夜间预压清单（`image_variant_warm` 的清单和对应测试）。分区规则已经把 828 算作页面尺寸，只是没有预压。 **Why** — 宽 390 点上下的 2 倍屏手机打开老番时，横幅要的是 828 宽，第一次打开仍要现压；桌面、2 倍屏 Mac 用 1920，3 倍屏 iPhone 用 1200，都已预压。 **Pros** — 只多一个宽度，每部有横幅的番多压一张。 **Cons** — 不知道真实访客里有多少会请求 828，可能是为很少的人多压一批。 **Context** — `next.config.ts` 的 `deviceSizes` 是 640/828/1080/1200/1920，横幅是 `sizes="100vw"`，浏览器按屏宽和倍率挑一个。 **Depends on / blocked by** — 第一期上线后，用访问日志统计横幅各宽度的请求占比；828 占比明显再做。 ## 多设备会话上线满 14 天后，删掉 users 上的旧会话列和过渡代码 **What** — 删 `users.refresh_token` / `previous_refresh_token` / `refresh_rotated_at` 三列，以及只为它们存在的过渡代码：旧格式 refresh token（不带 `sid`）的认领事务、认领后的宽限与重用判断、旧式登出分支、`user_sessions.legacy_hash` 列、`ClearRefreshTokenIfMatches` 查询、「退出其他设备」事务里顺带清旧 token 的 `ClearLegacyRefreshTokens` 查询、`internal/db/session_columns_test.go` 扫描测试，以及 `test/integration/user_session_columns_test.go` 里剩下的旧列测试。同一批还有对不带 `sid` 的访问令牌的放行：go-api `jwtx/session.go` 的 `checkSession` 里 `SessionID == uuid.Nil` 那一支、next-app `proxy.ts` 的 `decoded?.sid` 判断、ws-server `sessionLive.js` 的 `!user.sid`——这些只为会话检查上线前签发的访问令牌存在，那批令牌 15 分钟内就过期了；之后再放行，等于让将来某处漏签 `sid` 的令牌悄悄绕过「退出设备」。 **Why** — 多设备会话上线前签发的 refresh token 有效期是 14 天，过期后这些代码和列不会再被任何请求走到；留着的话，读代码的人要同时理解两套会话机制，`users` 表里也一直留着旧的 token 原文。 **Pros** — 会话逻辑只剩 `user_sessions` 一套；删掉一个文本扫描测试和一组只守旧列的集成测试。 **Cons** — 一次 drop column 迁移；之后再回滚到多设备会话之前的版本，所有人都要重新登录（上线时已经接受）。 **Context** — 上线前签发的旧 token 不带 `sid`，第一次刷新时会被认领成一条会话，同时清空 `users` 上的三列。 **Depends on / blocked by** — 多设备会话部署满 14 天，留几天余量后再做。 ## 定时清理过期的会话行 **What** — 加一个定时任务，删除 `user_sessions` 里 `expires_at` 已过的行。 **Why** — 过期行目前只在该用户下次登录时被清掉；再也不回来的用户，过期行会一直留在表里。 **Pros** — 表里只剩有效会话。 **Cons** — 以现在的规模不值得：每个用户最多 20 行，而且除了清理本身没有查询读这些行。 **Context** — 登录时的清理在多设备会话的会话代码里（每人保留最近使用的 20 条并删掉已过期的）。 **Depends on / blocked by** — 用户量大幅增长、`user_sessions` 行数明显变多时再做。 ## 会话失效时告诉用户为什么被登出 **What** — 一台设备的会话因为 30 天没用而过期、因 token 重用被吊销、同一账号超过 20 台设备被挤掉、被本人在另一台设备的「登录设备」里退出、或者改了密码时，下次打开页面给用户一句说明（例如「登录已过期，请重新登录」），而不是悄悄变成未登录。 **Why** — 用户被合理登出时，现在只会看到自己突然变成未登录，很容易以为又是「被顶号」。 **Pros** — 被登出的人知道原因，少一类「又被踢了」的误会。 **Cons** — 是界面改动，要先出画布；后端要把失效原因带给前端（目前 refresh 失败统一返回 401 INVALID_TOKEN）。 **Context** — 多设备会话上线后，go-api 每次刷新都会记一行带结果类型的会话日志（rotated / grace / reuse_revoked / not_found / legacy_unmatched 等），可以据此统计这类登出到底有多常见。 **Depends on / blocked by** — 多设备会话上线；会话日志显示这类结果不罕见时再做；画布通过。