UHD_Media_Tool/docs/runbook/organize.md

媒体整理（/console/organize）

原地入库为 v0.3.14 的待部署改动；当前生产 v0.3.13 的整理方式仍为复制／移动，独立就地刮削继续可用。

整理页分为「整理队列」与「整理记录」。队列显示等待、执行和等待继续的后台入库任务；记录显示复制／移动／原地入库的处理结果。文件管理的改名、删除、还原账本继续保存，通用记录接口仍可查询。

实现:

• 列表 / 统计 / 详情:apps/server/src/modules/acquisition-organize/routes/organization.ts(筛选 recordFilters,通配 likePattern);公开字段在 services/organize.ts 的 loadRecordsPublic。
• 删除:apps/server/src/modules/file-manager/record-delete.ts(复用文件管理删除 deleteFiles)。
• 契约:packages/contracts/src/organization.ts(OrganizationListQuery、OrganizationStats*、OrganizationDelete*),端点 Api.organization.stats / remove。
• 前端:apps/web/app/routes/console/organize.tsx、organize.$id.tsx,components/organize/(删除确认框、标题 / 季集小件),批量重新整理走共用整理弹窗的 { kind: "records" } 来源。

统一整理弹窗（v0.3.13）

手动选目录、文件管理器、下载详情与历史重新整理打开同一个弹窗。单文件只处理该文件，目录递归展开视频，多选合并去重。媒体类型可自动、电影或剧集；作品可自动识别、搜索本地／TMDB，也可选定类型后输入 TMDB ID 定位。手动指定作品与季号作用于整个本次范围，混合批次中需单独纠正的作品另行选取；文件明细可核对和修正季集、排除文件，没有另一套批量勾选语义。

各入口匹配相同来源配置，唯一匹配自动带出方式和分类／目标，多个匹配在弹窗内选定；不使用来源配置时沿用全局默认并手动指定。下载详情优先按已有 qB 标签匹配覆盖当前路径的来源。历史原配置仍覆盖可用输入时优先采用；成功移动后的目标不再属于旧来源时显示当前匹配配置或手动选项。

本次可选择原地入库、复制或移动。复制／移动可调整目标媒体库或具体目录、命名、目标冲突及整理后刮削。刮削默认沿用全局配置，显式开关只影响本次；整理成功的文件再进入现有 NFO／图片任务，TMDB 和 Local 均适用。做种义务未满足时不提供移动，复制与原地登记不改变视频文件，服务端继续核对实际状态。

手动来源发现真正成功历史时显示数量及「跳过成功记录」，默认关闭，开启后仅本次跳过；失败／部分成功记录不算完整成功，最新失败也不会遮盖较早成功。目标已存在策略单独处理。从历史记录进入直接采用重新整理语义。修改识别或选项后旧预览失效，需重新生成。

确认预览后只提供「加入整理队列」。后台受理成功后弹窗自动关闭，可以继续操作，进度到队列查看，整理后的刮削任务也显示在队列，整理详情单独展示刮削结果；部分受理时已受理文件从本次范围移除，剩余文件可修改后再预览提交。队列复用现有后台调度，不要求浏览器停留到文件处理结束。记录、队列及弹窗明细均复用统一分页。

来源、分类与存量整理

设置 → 媒体库与目录中维护分类 YAML 和整理来源。新功能已于 2026-10-01 部署为 v0.3.9，迁移 0059_organize_source_snapshot 已执行，见 发布记录（已删除，见 git ceb66f8）。

• 一条来源配置选一个来源目录、一个媒体库目标目录、复制或移动方式。通过弹窗浏览已登记的目录选择，不需要填写宿主机任意路径。不同来源可以使用相同分类，规则只维护一次。
• 分类一级固定为 movie / tv。规则按顺序首次匹配；同一规则的字段同时满足，同字段逗号值为任一匹配，! 排除。release_year 支持年份或区间；原始 TMDB 详情的一级字段也可使用。
• 空条件是兜底，应放在最后。默认保留「欧美电影」「欧美剧集」承接所有未命中的习惯。TV 默认顺序为儿童剧集、动漫剧集、纪录片、综艺、华语剧集、亚洲剧集、欧美剧集。尚未取得 TMDB 详情不能冒充分类成功。
• 自动分类在目标目录下追加分类目录，再使用现有作品／季目录模板。固定分类直接以所选目标为分类目录，避免追加第二遍分类名称。预览显示完整目标路径。已有作品沿用路径绑定，保存新规则不会移动旧库。
• YAML 保存后用于后续计划，重启保留；语法或目录名不合法时拒绝保存，已有规则保留。

来源触发方式可以选手动、qB 标签或目录快照。qB 标签同时限定下载器实例和来源范围；只有完成的任务进入整理，去掉标签后停止接管，已有管理标签继续有效。

新增来源或更改来源路径时，先将当前视频文件记录为基线，这些文件不会因此自动入库。快照持久化在数据库，重启保留。后续新增或改变的文件，在连续两次扫描确认大小和修改时间稳定后再处理。已知 qB 任务由下载器接管流程负责，避免两种触发重复整理。下载器目录会查询当前全部 qB 任务，即使未打标签、尚无数据库任务行，也会等下载完成。下载器不可达或目录读取失败会记录错误并保留此前快照。

「整理存量」是可重复触发的一次性扫描：排除同一源文件事实已成功整理的文件及未完成下载，历史部分成功中的失败文件、同路径发生变化的文件仍可选，候选进入同一个整理弹窗，确认识别、操作和完整目标路径后执行。单次候选按识别上限分批；完成后再次触发可处理余下文件。这个操作不重建或清空基线。识别不确定时也可打开现有智能助手协助判断，再加入整理队列。

文件管理器选中文件或目录后点「整理」，会读取来源配置并按同根、目录边界和最长来源路径匹配所选全部项目。唯一匹配自动带入复制／移动方式、分类和目标策略；多个同等匹配让用户选择，也可不用配置手动指定。不同来源混合选择或没有匹配时使用共用整理弹窗的手动选项。媒体类型在预览时核对，配置目标可由本次明确的目标选择覆写。

实现复用既有识别、冻结计划、文件操作账本、整理记录与任务引擎；未增加软链接、硬链接或另一套 AI 执行流程。

手动下载、Local 元数据与一次性洗版（已部署 v0.3.10）

搜索、站点工作台和原站详情均可独立下载，不要求订阅。下载时默认正常入库，也可选择一次性洗版并勾选旧版本；只有一个旧版本时默认选中，多个由用户选择。媒体详情与下载窗口展示已有文件和规格。正常入库保留已有版本；不同版本路径由可编辑的命名模板决定，同名冲突仍需处理。

未识别资源确认后允许下载。整理时先匹配 TMDB，再由现有网络／Agent 元数据补全能力核对译名、原名和别名；能够找到正确条目时回到 TMDB，找不到且详情资料充分时使用 Local 身份。Local 共用现有分类、命名、复制／移动和 NFO／图片任务，并保留字段来源；信息不足或候选冲突保留待处理。Agent 搜寻依赖已配置的模型／搜索能力和现有每日补全预算；没有封面资料时不会虚构图片。Local 入库安排元数据文件写入，普通 TMDB 自动刮削保持原设置。

洗版在本次冻结计划中保存选中的旧文件。新文件核验登记成功后才清理所选旧版本，剧集只处理成功对应的季集与 Part；覆盖不完整的合并集保留。相同目标路径会先暂存旧文件，失败后恢复。旧版的私有字幕等随之清理，共享 NFO／图片、未选版本及下载缓存保留；按现有文件替换设置移入回收站或删除。

关联迁移 0060_manual_acquisition，已于 2026-10-01 随 v0.3.10 发布执行。业务依据与验收见 MP 对照 §5.6。

与 MP 的对照

MP 对照源:MoviePilot-Frontend/src/views/reorganize/TransferHistoryView.vue、components/dialog/TransferHistoryDeleteDialog.vue、app/api/endpoints/history.py、app/db/models/transferhistory.py。

MP 功能	我们	说明
海报	新增	作品海报(media.posterPath),没有时显示首字占位
标题 / 年份 / 季集	已有	作品 (年) S01E02;未识别的显示「未识别 · 源文件名」
二级分类(华语电影等)	已接入	分类规则在设置编辑 YAML；电影 / 剧集为母分类，综艺属于剧集
源路径 → 目标路径	新增	列表加「源 → 目标」列(只显示末两段,悬停看全路径);详情「整理前 / 整理后」已有
存储标签(本地 / SMB…)	不做	只有本地存储,标签不提供信息
整理方式 复制 / 移动	已有	列表「方式」列;整理页聚焦复制／移动结果
软链接、Rclone 复制 / 移动	不做	整理服务不支持这几种方式
大小	新增	逐文件源大小之和(sizeBytes)
状态 成功 / 失败 + 失败原因	已有,改	支持「部分成功」；执行中任务在队列查看;成功不加徽章;失败原因走 reasons.ts 一句话,原码进详情「技术信息」
时间	已有,改	相对时间,悬停看完整时间
来源 下载器 / 手动 / 自动	新增下载器	来源列加下载器名称;详情加「下载任务」一行,种子 hash 进「技术信息」
关键字搜索(标题、源、目标;* ? 通配)	已有,补	补通配、逐文件的源 / 目标路径、种子 hash
搜「成功」「失败」切状态	不做	有状态筛选和计数按钮
状态筛选	已有
类型筛选	新增	电影 / 剧集 / 未识别(kind=movie|series|none)
时间筛选	新增	今天 / 最近 7 天 / 最近 30 天(since)。MP 没有,任务单要求
统计(总数 / 成功 / 失败)	新增	列表上方一行计数,只列非零项,点一下按该状态筛选(GET /organization-records/stats)
分页、每页条数	已有(不同)	共享分页组件，10／20／50／100 条和翻页；游标按需加载，无总数时显示「已加载」
列排序	不做	按时间倒序;分组模式下按作品聚合
分组模式(按标题)	新增	「按作品分组」,组头可折叠
筛选写进地址栏	新增	状态 / 类型 / 来源 / 时间 / 关键字 / 分组都在 URL,刷新不丢
单条:重新整理	已有,补	详情已有;列表行菜单新增。走共用弹窗（配置、展开预览、加入队列）
单条:智能助手整理	已有(不同)	「让智能体排查」:失败 / 部分成功的记录在行菜单和详情里
单条:删除(只删记录 / 连源文件 / 连媒体库文件 / 全部)	新增	确认框里两个勾选项,先核对再执行,写清删几个文件、多大、哪些删不了、会不会被自动整理再处理
查看详情	已有	详情加海报、大小、下载任务、删除按钮
批量选择 / 全选	新增	「批量」进入选择模式,表头全选
批量删除	新增	同单条删除确认框;删不了的逐条列出,其余照删
批量重新整理	新增	选中记录的可用文件一起进整理弹窗（成功移动取目标，其他取源）;同属一个作品时预选作品
清空整理记录	不做	整理记录同时是文件变更的追溯记录;清理按保留期由计划页负责

删除

POST /organization-records/delete {ids[≤200], deleteSource, deleteTarget, dryRun},scope organize.execute。

• 文件一律移入回收站,走文件管理删除(deleteFiles,mode=trash,retireAssets=true):已入库文件同时从媒体库移除(位置 removed、资产 retired、满足的收录版本转需关注 + 待处理)。回收站里能还原。
• 源文件 = 该记录逐文件结果的 source_path(只认执行进程本地视图);媒体库文件 = 成功文件的 target_path(相对库根时按库根拼)。已经不在的文件跳过、不拦。
• 只有复制 / 移动 / 原地入库 / 硬链接记录有文件可删;改名、移入回收站、还原类记录只删记录本身。
• 一条记录的任一文件不能删(做种未满足或下载中 download_active、绑定目录 needs_unbind、不在登记目录 outside_roots、目录离线等),这条记录连同它的文件都不动;还在整理的记录(running)不删。其余照删。
• 文件移入回收站会写一条「移入回收站」整理记录(同文件管理删除),trashRecordId 返回它。
• 下载器里的任务不删(同文件管理删除原则)。
• 删文件只允许管理员(控制台会话 / DEV key);API Key 只能删记录,删文件 403,需先走 /files/delete 的一次性审批。
• autoRetry:下载已完成但没入库(download_task.status=completed、本工具管理、没从下载器删除)且删完没有别的整理记录的下载任务数。自动整理扫描(index.ts 的补漏)会在几分钟后重新整理它们——与 MP 删失败记录后重新整理一致;已入库(imported)的不会。
• 删除不写增量读取的墓碑(/organization-records/changes 不会出现被删的记录);文件变化通过「移入回收站」记录可见。审计 files.organize_records_delete。

已知缺口

• 删媒体库文件只删整理记录里的文件,目录里的 NFO、图片与空目录保留(MP 在没有剩余视频时会连目录删掉)。
• 分组只对已加载的记录生效(同 MP 分组模式)。
• 统计的「进行中」= 排队 + 执行中;点它时列表只筛执行中。

原地入库（v0.3.14 待部署）

文件管理器选择已登记媒体库目录中的视频或目录，进入整理弹窗，默认选择「原地入库 · 保留位置与名称」。识别作品、手动指定电影／剧集、TMDB 和季集的方式与复制／移动相同，生成预览后加入现有整理队列。

• 源与目标路径相同；不复制、不移动、不重命名，不清理媒体目录中的临时文件。配对字幕／音轨同步登记，文件名和内容保持原样。
• 登记视频资产、所在库根、实际相对路径、版本信息与季集覆盖，已有同作品资产不重复创建；不新建会改变以后整理目标的目录绑定。
• 原地模式不使用来源配置的搬运目标、命名模板或替换策略，弹窗隐藏这些选项；不支持借此洗版或替换已有文件。
• 开启「整理后刮削」时，仅针对本次成功登记的视频在原目录补写 NFO／图片，不递归刮削整个同目录或该作品的其它版本。只登记／只读库根可原地入库，刮削关闭。
• 文件必须位于已登记、启用的媒体库根；下载缓存仍使用复制／移动或独立「刮削」。希望将现有目录直接作为媒体库时，先在设置登记该目录，然后原地入库。
• 预览与入队复用原计划校验；执行时确认文件未变化，不把已经归属其它作品的文件悄悄改绑。结果标为「原地入库」，可从整理记录重新整理。

此功能代码已实现，当前生产仍为 v0.3.13；本会话不能访问 Docker 或测试 PostgreSQL，部署及真实数据库回归尚待补验，见发布记录。