docs(scrape): 按现状改写 MP 对照 §10,运行手册写覆盖方式、自动重刮与缺元数据处理

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Cxwgnn2pbzQ7rXv3rq7fei

docs/porting/moviepilot-metadata-recognition.md

@@ -426,13 +426,17 @@ export interface TmdbPort { searchMovie(q: string, year?: number): Promise<TmdbS
 
 ## 10. 刮削（NFO、图片）
 
-| 上游 | 行为 | 本项目 |
+按 2026-10 的实现改写；细节与排查见 `docs/runbook/scrape.md`。
+
+| 上游 | 行为 | 本项目（现状） |
 | --- | --- | --- |
-| `app/chain/scraping.py:148 ScrapingOption`、`:243 get_default_config` | 按 `(movie|tv|season|episode)_(nfo|poster|backdrop|logo|disc|banner|thumb|clearart|landscape)` 逐项配置策略 `skip/missingonly/overwrite/upgrade`，默认 `missingonly` | 保留"逐项策略"的结构，放在 `policy_revision` 下的目录策略中（REQ §14.1.3："NFO/海报写入受目录策略控制"） |
-| `:320 _should_scrape` | skip 时不写；文件不存在时写；文件存在时，只有 overwrite 或全局 overwrite 才写 | 保留；另外增加一条：**用户或其他工具已修改的 NFO（含 `<lockdata>true` 或 hash 与上次写入不一致）不覆盖** |
-| `:356 _save_file` | 先写临时文件，chmod `0666 & ~umask`，再经存储链上传 | 保留"临时文件加原子替换" |
-| `app/modules/themoviedb/scraper.py:35 get_metadata_nfo` | 电影、剧、季、集四种 NFO；季和集走 `get_tv_season_detail`，有剧集组时走 `get_tv_group_detail`；标签包括 `uniqueid(tmdb default, imdb, tvdb)`、`plot`、`genre`、`actor`、`director`、`studio`、`country`、`mpaa`、`rating`、`runtime` | `packages/adapters/src/nfo/writer.ts` 输出 Kodi/Emby 兼容 NFO；**另写一个 `uniqueid type="uhd"`，内容为本地 UUID** |
-| 失败语义 | 刮削在整理后执行，失败只记日志，不回滚转移 | 保留"不重做搬运"；改为**独立任务 `refreshMetadata`，有自己的状态和重试**，不能伪报全部步骤成功（REQ §14.1.3） |
+| `app/chain/scraping.py:148 ScrapingOption`、`:243 get_default_config` | 按 `(movie\|tv\|season\|episode)_(nfo\|poster\|backdrop\|…)` 逐项配置策略 `skip/missingonly/overwrite/upgrade`，默认 `missingonly` | 没有逐项策略，只有全局覆盖方式 `organize.scrapeMode`：`update` 更新（缺省）/ `missing` 只补缺失 / `overwrite` 全部覆盖；图片与剧照各有一个开关 |
+| `:320 _should_scrape` | skip 时不写；文件不存在时写；文件存在时，只有 overwrite 或全局 overwrite 才写 | `missing` / `overwrite` 同 MP。新增 `update`：每次写入在 `scrape_record.files[].hash` 记内容 sha256，目标存在且与本工具上次写入的 hash 一致（没被改过）才用新内容覆盖，内容没变不重写；被改过的跳过（`scrape_user_modified`），不是本工具写的跳过（`scrape_exists`）；旧版本没有 hash 的记录按修改时间兜底。**不读 `<lockdata>`，也不写它** |
+| `:356 _save_file` | 先写临时文件，chmod `0666 & ~umask`，再经存储链上传 | 同目录临时文件 + rename（`services/scrape.ts` `atomicWrite`），目标必须在登记目录内 |
+| `app/modules/themoviedb/scraper.py:35 get_metadata_nfo` | 电影、剧、季、集四种 NFO；标签包括 `uniqueid(tmdb default, imdb, tvdb)`、`plot`、`genre`、`actor`、`director`、`studio`、`country`、`mpaa`、`rating`、`runtime` | `packages/domain/src/scrape/nfo.ts`（纯函数，与 MP 元素顺序一致，金样差分 `apps/server/test/scrape/nfo-mp-diff.test.ts`，偏离登记 `nfo-deviations.json`）；`uniqueid` 只有 tmdb / imdb / tvdb / douban，**没有 `type="uhd"`**；不写 `mpaa`、`episodeguide`、`lockdata`。合集 / 其他类作品按电影写（根元素 `<movie>`，判定函数 `scrapeKindOf`） |
+| 季 / 集元数据 | `get_tv_season_detail` 现取；集名缺时写占位 | 本地作品用投影后的季 / 集字段；单元缺元数据时按 TMDB id 现取季详情补齐，仍缺则该文件跳过（`scrape_metadata_missing`）、记录 `partial`，**不写「季 N」「第 N 集」占位** |
+| 元数据变化后 | 不会自动重刮 | 刷新元数据后 NFO 相关字段有变化、且作品刮削过 → 延后 2 分钟排一次 `update` 模式重刮（同目录排队记录合批防抖）；改 TMDB 映射时先清旧作品的 tmdb 来源字段与没锁的 IMDb 映射，再 full 刷新，刷新后按同一规则重刮 |
+| 失败语义 | 刮削在整理后执行，失败只记日志，不回滚转移 | 不重做搬运；刮削是独立任务 `scrapeMedia`（不重试，失败的重新刮削），每次一条 `scrape_record`（逐文件结果与原因）；非写文件的意外错误记 `scrape_internal_error` 并保留已写文件结果 |
 
 ---