UHD_Media_Tool/docs/plan/18-organize-release.md

媒体整理与下载发布记录

当前生产应用为 v0.3.13，健康检查通过，见下方新增发布记录。

v0.3.9 媒体整理发布

2026-10-01，Asia/Shanghai。用户授权部署，应用发布为 v0.3.9，健康检查通过。分类规则、整理来源、目录快照、手动存量和文件管理入口一起发布。详细行为见 整理手册。

发布范围与来源

• 版本：workspace / server / web 0.3.9；前端 version.json 为 v0.3.9，健康接口为 0.3.9。
• 源码：HEAD 8013196 加用户已授权的工作区修改，未创建提交。镜像标记 8013196-dirty-121ab989fb4a427b；对应源码文件指纹 121ab989fb4a427b，完整值保存在本地发布证据。
• 镜像：uhd-media-tool:v0.3.9，ID sha256:4db9dda97358a5adc5e6f3472d88b4cd05d5522eb6183663f2659d86b5401163。
• 迁移：0059_organize_source_snapshot；新增持久快照表，已有 settings 读取时补分类 YAML 和空来源列表。发布不会扫描或导入存量。
• 本次只替换 app 容器。PostgreSQL、qB、浏览器、Caddy 和宿主程序没有更换。

发布前检查

引擎 pending / running / sleeping、业务 task queued / running / waiting、整理记录、刮削记录及 Agent 在途数量均为 0。备份完成于 /data/backups/20261001T095557Z，数据库、映射和 Agent 会话的 SHA256 校验全部通过。

最终 web 回归 26 文件 / 232 项通过；来源匹配新增根范围、目录边界、全部所选项、最长路径和多候选测试。typecheck、Biome 与 production build 通过。服务端验证范围和完整回归的阶段性失败及复验口径见 业务对照 §4.3。Docker 构建完成冻结依赖安装、设计 token 检查、web build、server compile 和编译二进制模块图自检。

部署后验证

• umt-app-1 healthy，运行镜像 ID 与发布镜像一致。
• HTTP 4380 与 Caddy HTTPS 健康均为 ok；API / IO worker / Agent worker 存活，UID 10001。
• 0059 已登记，快照表存在；scanOrganizeSource@1 进入 maintenance worker，organize.sources 可用并启用。
• 通过现有管理员登录验证分类配置、整理来源、settings 和文件根读取；华语电影、澳大利亚兜底欧美电影、TV 综艺三个预览结果正确。
• 文件管理、整理记录、设置三个 SPA 地址返回正常；部署静态资产包含文件管理策略选择入口。
• 验证时来源配置仍为空，留待用户手动选目录；没有新增来源配置或对用户媒体执行整理。
• 部署后验证窗口内 error 级应用日志为 0。

本次没有运行浏览器截图或完整交互冒烟，用户可以刷新现有页面，进入「设置 → 媒体库与目录」检查分类规则与来源配置，再从文件管理器进入同一整理向导。

本地证据：.local/deploy-organize-20261001/release.json、http-check.json；构建日志 /tmp/umt-organize-docker-build.log。部署配置的版本和源码标记已更新，当次部署配置使用 v0.3.9；下方 v0.3.10 发布已更新配置。

v0.3.10 手动下载与入库发布

2026-10-01 23:18，Asia/Shanghai。用户授权部署，本批独立手动下载、串流外详情页下载、TMDB／Local 元数据兜底、正常多版本／一次性洗版与订阅完成口径调整已上线。实现、业务边界与回归结果见 MP 对照 §5.6。

• 应用与前端版本：0.3.10／v0.3.10。镜像 uhd-media-tool:v0.3.10，ID sha256:cbf3081281c75f4e60dba9a9ce18de63b0c5665c66b2b133baebaa7f05aabdd2。
• 源码标记：8013196-dirty-5ecf10d5b4f89432，HEAD 加用户授权的工作区修改；1552 个源码文件指纹记录保存在本地，部署后逐项复核未变化。没有创建提交。
• 迁移：0060_manual_acquisition 已执行；计划允许无 Slot，下载任务新增 import_plan_id 外键并使用 ON DELETE SET NULL。
• 升级前引擎、业务任务、整理、刮削、Agent 在途均为 0；备份 /data/backups/20261001T151510Z 的数据库、映射和 Agent 会话 SHA256 校验通过。
• Docker 构建的冻结依赖、设计 token、web production build、server compile 与空环境二进制自检通过。
• 只替换 app；PostgreSQL、qB、浏览器、Caddy 等其他容器 ID 保持不变。

部署后 app healthy，运行镜像与构建镜像一致；HTTP／HTTPS 返回 ok，前后端版本一致，API、IO 与 Agent 三个进程运行于 UID 10001。管理员登录及分类／来源／settings／文件根／下载任务／浏览器会话读取通过，3 个分类预览符合原配置。能力目录为 42 项，包含 metadata.resolve_organize；线上 OpenAPI 包含详情页资源解析与手动入库选项。

使用 Chromium 在真实生产入口登录，下载面板、计划列表、整理记录、文件管理、设置及媒体库共 6 个页面冒烟通过，无未捕获页面异常或失败 API，并保存截图。部署验证窗口内 error 级应用日志为 0；计划、下载、媒体资产、整理记录和订阅数量均保持一致。没有以验收为由提交下载、洗版或移动用户媒体；实际 PT 下载、外部模型与入库执行仍以真实任务验收为准。

本地证据：.local/deploy-manual-20261001/release.json、source-manifest.json、http-check.json、ui-check.json 及页面截图。构建日志 /tmp/umt-manual-docker-build.log。.env.deploy 已固定 v0.3.10 及本次源码标记，后续普通 Compose 启动使用本版本。

4380 自签 HTTPS 入口调整

随后按用户测试要求，将 4380 的宿主端口交给 Caddy：https://服务器地址:4380 使用现有 Caddy 内部 CA 证书，443 HTTPS 入口继续保留；app HTTP 仅映射 127.0.0.1:4381，容器内仍监听 4380。仅重建 app／Caddy 容器，无镜像升级或新增迁移。配置写入本机 override 与 .env.deploy。

4380／443 HTTPS 健康、管理员接口、版本一致及新接口描述验证通过；真实 HTTPS 下 6 个生产页面冒烟通过，无页面异常或失败 API，Chromium 报告 isSecureContext=true。证据为同目录 https-http-check.json、https-ui-check.json、https-switch.log，汇入 release.json。

v0.3.11 搜索详情与桌面黑边修复

2026-10-01 23:58，Asia/Shanghai。搜索资源标题现在可以点击，打开与站点工作台相同的详情抽屉；加载完整资源后复用已有详情缓存、按需抓取、简介／规格／截图／文件展示、下载选项与 Agent 入口。抽屉关闭后搜索词、筛选和分页保留。读取失败显示原有错误与重试，打开详情不会提交下载。

• 镜像 uhd-media-tool:v0.3.11，ID sha256:fa54237f250c92bee1436912275cb0b8da97d1b7c9bf9489dc1152144908b944；源码标记 8013196-dirty-a2f3f773724cbde4，1553 个文件的指纹部署后复核一致。
• 前端 typecheck、Biome、232 项测试通过；Docker 内设计 token、web build、server compile 与空环境二进制自检通过。真实 React 组件验证点击标题、未缓存自动抓取一次、缓存不额外抓取、失败显示与详情下载选项，无实际提交。
• 切换前业务、引擎和 Agent 在途为 0；备份 /data/backups/20261001T155308Z 的数据库、映射与会话校验通过。仅替换 app，数据库迁移仍为 0060。4380／443 自签 HTTPS 入口保留。
• app healthy，前后端版本一致，42 项能力及管理员接口检查通过；6 个 HTTPS 生产页面无异常或失败 API。另使用生产构建、真实缓存资源详情 API 和受控搜索结果验证点击后的简介展示及下载选项；未触发下载。验证窗口内 error 级应用日志为 0。

桌面黑边修复先于应用发布部署。实际视频与 iframe 都为 1280×900，黑边是浏览器窗口未最大化造成：底座初始化脚本把快捷键 XML 按行注释，产生无效 XML，连带最大化规则无法读取。内置完整 /defaults/umt-labwc.xml 在底座初始化后覆盖配置，保留既有快捷键／桌面菜单行为，并为窗口设置 Maximize 与 serverDecoration="no"。配置语法对应 labwc 窗口规则。

浏览器修复镜像 umt-browser-desktop:1.18.0-umt.1，ID sha256:cf31c83524b260b22c65f39a759771e6861e65a951c89c0382043794aebfadb6，基于当时运行的 1.18.0 镜像只替换初始化脚本与 XML，基础依赖保持一致；完整构建入口也已包含这两份源码。.env.deploy 固定修复标签。浏览器容器 healthy，登录状态卷保留；真实串流前后截图中心线上下黑边从 65／66 像素变为 0／0，画面铺满，视频尺寸保持 1280×900。

发布证据：.local/deploy-search-detail-20261001/ 中的 release.json、source-manifest.json、API／页面／搜索检查与截图。桌面证据：.local/desktop-sizing/ 中的修复前后截图、测量值、有效 XML、补丁构建与发布记录。

v0.3.12 列表分页、搜索历史与首页概况

2026-10-02，本次将表格和卡片列表统一为 Pagination + useListPagination，自定义详情列表复用 PaginatedList。每页 10／20／50／100 条，默认 50 条，浏览器记住选择；筛选和目录变化回到第一页。支持页码、上一页／下一页、已知集合的首页／末页。游标接口仍按需拉取，返回上一页使用缓存；没有总数时准确写「已加载」，不将已加载数量当完整总数。

覆盖整理记录、审计、下载／业务任务、任务流、媒体库／身份／别名、订阅、站点卡片与资源、搜索作品候选与资源、待处理、智能体历史、媒体详情季集／版本／历史、整理预览、来源配置、计划与运行历史、设置里的规则／偏好／路径映射／Passkey，以及文件管理器和目录选择小窗。表格默认共用分页，订阅和整理批量勾选明确按本页操作，跨页已选项目保持可见计数。少量嵌套季集或版本（不超过 10 条）保留展开列表，避免同一项内重复出现翻页工具；首页近期摘要和导航通知预览不做完整列表分页，仍链接到完整页面。

小规模配置 API 跟随游标取齐，保留原返回形状；主要历史列表继续按需游标请求。作品详情的下载、整理和未提交成功的失败计划取消原先 100／100／50 条读取上限，前端分页呈现；这是现有单作品详情接口的完整查询，不新增多套 API。定时运行记录后端只保留最近 50 次，本次分页覆盖其实际保存的记录。聚合作品搜索仍是本地与 TMDB 的候选结果集合（每来源至多 50），资源列表走完整的 /search/releases 游标；未扩展 TMDB 跨页搜索业务。目录树接口原有数量截断提示保留，右侧文件列表仍可完整按游标浏览。

搜索历史在当前浏览器按账号隔离保存最近 30 个已搜索关键词，重复搜索前移，搜索页和 Ctrl／⌘ K 共用，支持点击重搜、删除单条与清空；输入过程不写入历史。通知铃铛、角标、浮层、条目、严重度、加载／空／错误状态共用控制台按钮和样式，修正手机边距与暗色角标对比。

首页新增存储和下载器两张概况卡：媒体库／下载目录所在磁盘的剩余、已用、总容量、占用比例与健康状态；各下载器连接状态和上下行速度、全系统进行中任务数。容量按所在文件系统展示，不把共用磁盘的多个目录相加；进行中数量包含等待计划、暂停和异常任务。不可读容量和离线速度显示未知。存储每 60 秒更新、下载器每 15 秒更新，首页只请求一条面板记录，速度和计数由完整汇总提供。详情分别链接运行状态和下载面板。

验证证据：.local/pagination-release-20261002/ 的类型／测试／格式／浏览器结果、页面截图和构建发布记录；.local/notification-style/ 的通知前图、首页手机／桌面与离线／容量未知检查。前端 29 文件 242 测试通过；服务端媒体版本 4 项通过，新增跨旧上限的 105 条下载、105 条整理和 51 条失败计划验证。浏览器用受控审计响应验证 10／100 条切换、跨游标下一页、缓存上一页、末页和筛选复位，搜索历史验证刷新、删除、重搜、快捷面板和清空；未执行实际下载或整理。

整理使用方式另完成 MP 固定源码与本项目实际页面对照，结论见 对照第 6 节。来源默认一致性、成功移动后重整、向导勾选语义和空配置入口仍待讨论；本次只调整分页，不实施这些业务改动。

v0.3.13 统一整理弹窗与队列

2026-10-02，用户确认 MP 方案并授权完成本轮与部署。手动、文件管理、下载详情和历史重整共用单表单弹窗，支持电影／剧集、TMDB 搜索或 ID 定位、来源配置、复制／移动、目标路径、本次刮削及可展开预览。只提供「加入整理队列」，后台受理后关闭；部分受理时移除已入队文件，剩余文件再预览。整理页分队列与记录，直接复用原任务引擎；默认队列也展示尚未生成整理记录的下载核验任务。

成功历史跳过遵循 MP：手动入口有成功历史才显示开关，默认关闭，预览与执行同参数；失败／部分成功记录不计入成功数。成功移动历史从媒体库目标重整，失败／复制仍使用源。刮削开关冻结到既有计划，TMDB／Local 与恢复执行均遵守本次值。通知数字角标改为主题 primary 配色，每页条数使用现有 Select。

无新增迁移，沿用 0060_manual_acquisition；只发布应用镜像，浏览器、Caddy、PostgreSQL、qB 和宿主版本保持当前状态。部署配置固定 v0.3.13 及本次源码指纹。备份、镜像、健康和前后端版本证据记录于 .local/organize-final-20261002/release.json。

前端全套与相关服务端回归通过；服务端用隔离数据库／临时文件验证移动后重整、成功跳过、配对字幕、TMDB／Local 刮削开关和任务恢复。类型与格式检查通过。浏览器验证统一 Select、成功历史开关、预览失效、过时 TMDB 回包、受理期关闭行为、部分受理后只提交剩余文件以及手机布局，所有整理写请求均使用拦截响应，未对用户媒体执行整理、移动、替换或刮削。生产构建与应用发布检查同目录保存。

部署后核验：前端 250 项、相关服务端 64 项测试通过；4380 HTTPS 的前后端版本一致，应用 healthy，启动 error 级日志为 0，其它服务容器未替换。生产入口 13 个主页面、媒体详情及整理记录详情冒烟通过，无页面异常或失败 API；刮削队列与关联记录、桌面／手机弹窗和分页交互验证通过。备份 /data/backups/20261001T184721Z 三个文件的 SHA256 校验通过。发布文档在验收后补充，此文件不进入 Docker 构建上下文。

业务对照与决策见 第 6.4／6.5 节，使用方式见 整理手册。

v0.3.14 原地入库（代码完成，未部署）

2026-10-02。用户要求文件管理整理补齐原地处理，参考 MP，并记录改动。新增共用整理弹窗「原地入库 · 保留位置与名称」：已登记媒体库内的选择默认原地登记，可切回复制／移动；下载缓存维持原有方式。源目标相同，隐藏搬运目标／命名／替换选项，识别和预览后仍只加入既有队列。

执行只读核验源文件，不复制、移动、改名、创建目标目录或清理临时文件；复用逐文件账本和最终事务登记视频、字幕、位置、版本与季集覆盖，同作品既有资产不重复创建。结果和重新整理入口识别 in_place。不新建目录绑定，不原地洗版；已登记为其它作品或计划后改变的文件会提示失败。可选刮削只针对本次成功主视频，不扫描整个同目录／作品其它版本；只登记库根不写元数据。

MP 固定源码没有独立原地入库模式，其文件管理提供就地刮削；本项目原有刮削仅创建作品条目和元数据文件，未登记视频资产。此改动补齐本工具的资产管理，参考依据见 业务对照 §6.6。

迁移 0061_organize_in_place 为整理记录 action 和文件结果 mode 增加 in_place，未执行生产迁移。workspace／server／web 源码版本准备为 0.3.14；.env.deploy 与当前生产保留 v0.3.13。

验证：前端 30 文件／252 项测试，整理计划 22 项、枚举映射 22 项、执行只读核验 3 项通过；前后端类型检查（含新增服务端测试）、格式和差异检查通过。服务端编译及编译二进制模块图自检通过。新增 6 项隔离 PostgreSQL 集成用例覆盖实际文件、重复登记、字幕、季集、刮削范围、变更／归属冲突和只读库根，但当前会话不能连接测试数据库，全部跳过，不计为通过。

前端 production build 的客户端与服务端打包已完成，最后 React Router 预渲染需要监听 localhost，被当前沙箱以 listen EACCES 拒绝，完整构建未通过。Docker socket 访问同样被拒绝，因此未构建发布镜像、未部署、未进行生产浏览器验收。早期 Deno Vitest forks／threads 受运行时兼容问题影响；前端与执行核验改用 Node 复验通过，其它结果按实际日志记录。没有修改用户实际媒体文件。

证据位于 .local/in-place-20261002/。待有正常部署权限时，先补跑这 6 项数据库用例和完整前端构建，再按现有发布流程备份、检查在途任务、构建新镜像并仅更新 app。不得直接把旧 v0.3.13 镜像改标签当作新版。

2026-10-02 补充验证与修复（仍未部署）

开发库补齐迁移至 0061 后补跑：原地入库 6 项数据库用例全部通过（其中 1 项原先断言调用了文件管理装配未挂载的整理记录接口，改为直接查记录表）。全 workspace 类型检查、Biome 与各包测试通过：server 840（1 跳过）、adapters 464（3 跳过）、contracts 1053、domain 658、agent 82、db 21、mapping 22、tasks 17、testkit 5、web 252。

同批修复：识别升级链不再用更差的结果（no_match）顶替原有歧义候选，与 MP 识别兜底"只在前一步没有结果时采用"一致；作品目录刮削对 bluray_dir 资产直接以原盘目录为刮削根（MP 同做法）；metadata.resolve_organize 补登记到入库排障 Skill 与能力地图；db/src/types.ts 按迁移重新生成，contracts 整理动作枚举顺序与数据库对齐。前端统一通知铃铛弹层与站点卡片样式。前端完整 production build 与镜像构建仍按上文发布流程执行。