UHD_Media_Tool/docs/plan

计划与待办

这里只放正在推进的计划和待办。做完的计划、验收和发布记录直接删除，版本变化只记在 CHANGELOG；需要追溯时查 git 历史（2026-10-02 清理前的全部过程文档在 ceb66f8）。

文档放哪

内容	位置
需求基线	media_automation_requirements_architecture_v0.7.md
架构决策	docs/adr/
设计规范（界面、领域）	docs/design/
怎么用、怎么运维	docs/runbook/（开发环境见 dev.md，部署见 deploy.md）
与 MoviePilot 的业务对照（持续维护）	docs/porting/moviepilot-v3-comparison.md 及同目录各移植文档
版本变化	仓库根 CHANGELOG.md，每个版本几行；发布前必须写好（deno task release 会检查）
经验教训	lessons.md
证据、截图、构建日志	.local/（不进 git）

当前状态

• 版本 v0.3.31，本机测试环境已部署。
• 开发与发布约定见仓库根 CLAUDE.md。

待办

按需要再挑，挑中后在这里写清：从哪触发、最终看到什么、哪些失败需要人工处理、用什么样本验收。

工程

• BrowserService（apps/server/src/modules/browser/service.ts，约 2300 行）仍是单个类。纯函数已移到 session-view.ts；Cloudflare 挑战流程（beginChallenge～fetchSiteHtml，约 400 行）要拆成独立协作对象，需要先把它用到的私有方法改成公开接口，下次改挑战流程时做。
• 超长函数：planImport（organize-plan.ts，约 830 行）、finalizeRecord（organize-finalize.ts，约 460 行）、OrganizeWizard 组件（约 800 行）。文件已按阶段拆开，函数内部等改到相关逻辑时再拆，不单独重构。

进行中

• 界面第二轮：ui-round-2.md，5 路并行，用户最后验收。
• 下一轮（界面第二轮合并后）：
  • 统一元数据缓存：TMDB / 豆瓣 / Bangumi 共用「来源 × 资源类型」TTL 策略；进程内存一级 + PG kv_cache 二级，LISTEN/NOTIFY 跨进程失效；过期先用旧值后台刷新；关注中作品续期不淘汰、进入关注时预热（各季、剧集组、图片）；同请求合并；按 region 统计命中率。刮削顺带接 TMDB logos 写 clearlogo.png。fanart.tv 暂不接（用户 2026-10-06 定）。
  • 生命周期事件与功能模块约定：广播事件 + 链式钩子（参考 MoviePilot EventType / ChainEventType），功能清单给智能体，前端插槽默认显示、不做开关；补字幕迁为样板。
• 系统梳理后的待办：system-review.md，T0～T6 按优先级。
• 补字幕：subtitles.md，第 1、2 步已完成；待办：以后接进整理 / 订阅工作流。
• 沙箱第二批：站点网页、RSS、网页抓取的 HTML / XML 解析迁入常驻子进程池（ADR-005）。

业务（需要真实环境或决定）

• R06 通用 HTTP 失败转浏览器：要先定"哪些失败转浏览器、每站每小时上限、失败后怎么提示"，再实现；真实 Cloudflare 挑战需要一个会触发挑战的站点账号验收。
• R21 缓存阈值里未纳管占用的专项验收：需要在真实下载盘上放一批不归本工具管理的文件，观察暂停 / 恢复水位。
• 四站与真实下载、媒体服务器的完整验收：需要真实站点账号、qB 与 Emby / Jellyfin 实例。

观察项

• test/e2e/continuous-series.test.ts「另一版本延后」2026-10-02 全量跑时偶发等待超时 1 次。已核实不是业务竞争（reserve() 在 Slot 行锁内复核单元重叠，冲突即延后）；单跑 4 次、3 份 / 8 份并发均未复现，疑为负载下评估任务重试退避超过 60s 等待。再出现时保留 .local/test-logs/ 日志再查。