Peach: Local-first video metadata scraper and media manager.
docs(adr): ADR-0137 记录核查差异的结算判据与撤回口径
longmeidao751f37a38eac
diff --git a/docs/REUSE.md b/docs/REUSE.mdindex 4e11dc0ad..31ddde660 100644--- a/docs/REUSE.md+++ b/docs/REUSE.md@@ -604,7 +604,7 @@ OneJAV、Free JAV Torrent 只给种子链接。这类条目经索引器同源的复核用 Checkbox、Button、Badge、Select 与 `/api/review/decision`,默认勾选、沿用馆藏页 Shift 连选;支持跨组通过/拒绝与无歧义的共同来源选择。按候选数量、来源组合或字段分组,每项只出现一次,切组保留选择;成功移出、失败保留,离开页面即停。整页在 `frontend/src/react/review/`,一条队列一个 `queryKey`,判定后改缓存不重取。React Aria Components 1.22.1 的 `Radio`/`Checkbox` 继续承载原生焦点与方向键;共用 `base.css` 将隐藏输入框的定位归于所属标签,来源切换只滚动卡片正文,分段单选、媒体库图标选择和复选框使用同一定位基线,不新增依赖。批准回执在同一事务中读取实际资产版本,缓存只推进仍持有该次写入前版本的候选;逐项与批量提交共用缓存中的并发凭据。身份候选用创作者页、作品详情与 revealSource 核对样本;来源图与缺图占位共用 220px 预览区,样本支持无缩略图作品,回收站不参与。-本地 NFO 配对复用 `library_nfo`、`catalog_rules` 的番号与分卷识别、标准库 ElementTree 及现有资料补空流程。[Kodi NFO 文档](https://kodi.wiki/view/NFO_files/Movies)的同名文件与 `movie.nfo` 约定于 2026-10-17 核对;只参照公开格式,没有复制外部源码。Peach 保留同番号分卷共享、同名文件优先、多份匹配拒绝、内容番号冲突检查和输入安全限制。Kodi 整套媒体中心没有作为依赖引入;标准库随 Python 3.14 运行,无额外体积或许可证。NFO 读取后复用来源缓存与缺失缓存核查在线字段;`requires_review` 跟随候选保留覆盖复核要求,人工决定保存已展示的候选身份,见 ADR-0108。隔离媒体与账本回归覆盖共用 NFO、不同作品混放、错误 NFO 继续在线补全、补空与覆盖分流,以及连续批准的版本回执;真实反馈的 NFO 样本尚未取得,无新增依赖。+本地 NFO 配对复用 `library_nfo`、`catalog_rules` 的番号与分卷识别、标准库 ElementTree 及现有资料补空流程。[Kodi NFO 文档](https://kodi.wiki/view/NFO_files/Movies)的同名文件与 `movie.nfo` 约定于 2026-10-17 核对;只参照公开格式,没有复制外部源码。Peach 保留同番号分卷共享、同名文件优先、多份匹配拒绝、内容番号冲突检查和输入安全限制。Kodi 整套媒体中心没有作为依赖引入;标准库随 Python 3.14 运行,无额外体积或许可证。NFO 读取后复用来源缓存与缺失缓存核查在线字段;`requires_review` 跟随候选标出核查差异,差异按 ADR-0137 的判据结算,判不了的交人,人工决定保存已展示的候选身份,见 ADR-0108。隔离媒体与账本回归覆盖共用 NFO、不同作品混放、错误 NFO 继续在线补全、补空与覆盖分流,以及连续批准的版本回执;真实反馈的 NFO 样本尚未取得,无新增依赖。## 本机设置与卸载diff --git a/docs/adr/0108-nfo-verification-and-reviewed-overwrites.md b/docs/adr/0108-nfo-verification-and-reviewed-overwrites.mdindex bb71e02f0..e41c4e3ad 100644--- a/docs/adr/0108-nfo-verification-and-reviewed-overwrites.md+++ b/docs/adr/0108-nfo-verification-and-reviewed-overwrites.md@@ -3,6 +3,7 @@- 状态:Accepted- 日期:2026-10-17- 依据:用户要求先读取本地 NFO,扫描刮削时仍查询来源;补漏无需复核,覆盖已有值必须复核。+- 修订:[ADR-0137](0137-verification-differences-settle-by-rule.md) 让核查差异按确定判据结算,只有判据给不出结论的、以及 NFO 与链首来源说法不一的仍交人## 决策diff --git a/docs/adr/0137-verification-differences-settle-by-rule.md b/docs/adr/0137-verification-differences-settle-by-rule.mdnew file mode 100644index 000000000..0c543e8f5--- /dev/null+++ b/docs/adr/0137-verification-differences-settle-by-rule.md@@ -0,0 +1,75 @@+# ADR-0137:核查差异按确定判据结算,复核页只留要人判的++- 状态:已采纳+- 日期:2026-11-04+- 关系:修订 [ADR-0108](0108-nfo-verification-and-reviewed-overwrites.md)「覆盖已有值必须复核」;ADR-0025 否决的归一化比对与来源优先级取舍只在本 ADR 划定的范围内放开;沿用 [ADR-0033](0033-online-sources-only-fill-empty-fields.md) 的社区来源只补空、[ADR-0038](0038-field-priority-chain-settles-dissent.md) 的字段优先级链与 [ADR-0052](0052-entity-results-land-when-evidence-is-sufficient.md) 的可撤回自动落库++## 背景++2026-11-04 复核页待处理 2819 条,其中元数据字段 2775 条。逐条核对后,绝大多数挂在同一道门上:++- 有 NFO 的资产整条走核查模式(`library_processing._read_local_metadata` 返回 `nfo is not None`),升级补修的影片补全又以 `recheck_existing=True` 跑处理任务。两条路上,在线来源与账本现值不同的取值一律带 `requires_review`。10-28 与 11-04 两轮升级补修就带回 2533 条。+- 复核页把这些行从其余过滤器外面加回来(`overrides`),处理任务对它们一律跳过。快照里 2591 条是这一道挡住的,与来源可信度、取值是否真有分歧无关。++ADR-0108 记的是用户 10-17 的要求:「补漏无需复核,覆盖已有值必须复核」。11-04 用户在补女优资料的会话里说:「允许填,而且这个逻辑应该通用,让人工复核尽量少让人工去复核」。两次决定并列,本 ADR 的范围是:确定判据给得出结论的差异不再交人,结论要写账本时只写能整批撤回的,写不了撤回的照旧交人。++核查差异里大致有四类:++| 类别 | 例子 | 快照条数 |+| --- | --- | --- |+| 没有新信息 | 标签候选是现值子集;标题只差全半角、标点、打码字,或是现值的一段、去掉【】装饰后是;出演者按实体是同一批人 | 约 710 |+| 社区来源对非空现值的异议 | javdb 的配信日比发售日早几天;FC2 促销前缀;合集出演表 | 约 590 |+| 证据确定、能撤回的补充 | 标签候选里有账本没有的;官方来源一致给出的标题与日期 | 约 1070 |+| 真冲突 | 三家出演者全不同(ACC-006);厂牌与 label 混写(HOISW-002);系列命名不一;厂牌实体缺别名(`Deep's` 与 `ディープス`) | 约 80 |++## 决策++**一、核查差异只走一套判据。** `metadata_auto_apply.verification_outcome` 给一行核查差异定去向:保留现值、并集、覆盖或交人。复核页、处理任务结算与升级补修调同一个函数;复核页只把「交人」那一种摆出来,其余三种不占队列。`metadata_auto_apply_candidate` 不再接核查差异,避免链首覆盖(ADR-0035、0038)绕过这套判据。++**二、零写入的保留现值。** 下列情况账本不变,也不写决定:++1. 现值归人(`user:`、`review:`);+2. 日期式番号的发行日期,现值就是番号那天(ADR-0034);+3. 每条候选对现值都没有新东西(`_adds_nothing`)。标题按 NFKC、大小写、空白与标点折叠后比;候选一侧的打码字(`●`、`○`、`*`,可盖住多个字)可对上任意字,现值打码、候选没打码的不算;候选是现值的一段,或去掉【】、[]装饰后是。出演者按实体身份是现值的子集,或整条剪不出艺名(企划名义与称呼)。厂牌、系列只差写法与码,或候选在现值后面加了读音与上级注记(`E-BODY(イーボディ)`、`Flower/妄想族`)。标签候选是现值子集;+4. 提出新东西的只有社区来源(ADR-0033);+5. 链首那一档(本地 NFO、官方来源、字段上提到链首的来源)里有 NFO 以外的来源与现值一致;+6. 现值由链上更靠前的来源自动写入(ADR-0038 已经取过舍),例如 `auto:makers` 写下的 `HHH` 不被 dmm 的 `ロイヤル` 挑战。++兜底来源 javbus 不挑战已有值(ADR-0038 决策三),r18dev 给厂牌、系列的英文译名(`Amateur Pussies` 之于 `しろうとまんまん`)既不挑战也不作证,判断前先剔掉。++这里的归一化只用来判「保留现值」,结论不写账本。ADR-0025 否决的是拿归一化判两家「一致」然后落库;放在这一侧没有写入,被否决的那个风险不存在。++**三、可撤回的写入只有两种。**++- **标签并集。** 证据候选里认得出、账本没有的标签按链上先后补上,一个不删。复用 ADR-0082 的并集写法,标签行归属是批次号 `auto:metadata-tags@<时间>`。决定记 `rule: adr-0137-verified-tags-union`、`added_tags`、各次 `batches` 与当时全部候选身份。之后又收录了生词时,下一轮照样补。+- **官方一致的标题与日期覆盖。** 链首那一档有异议的来源取值一致、现值不归人、没有更靠前的来源写过、番号身份核得上(`_auto_apply_targets`),按链首那一家覆盖,归属 `auto:<来源>`。决定记 `rule: adr-0137-official-replaces-verified`、批次号,以及每条资产覆盖前的取值与归属(`previous`)。++`scripts/revert_auto_landing.py --source <规则名> [--batch …]` 按决定撤回:并集删掉那一行补进的标签,覆盖把旧值与旧归属原样写回,之后被别人改过的资产不动。两种都删掉决定,下一轮按那时的判据重判,所以先改判据再撤。++**四、交人的只剩这些。** 本地 NFO 与链首来源说法不一(不论哪边是现值,核对 NFO 正是 ADR-0108 要做的事);出演者有官方或链首来源异议;链首来源之间说法不一;厂牌、系列的官方异议;番号身份核不上;日期式番号的官方日期不是番号那天。++厂牌与系列在账本里是实体,换值连带改作品关联,撤回还不了原样;快照里这一类多是 maker 与 label 混写、系列命名不一、实体缺别名,确实要人判,不进覆盖。++**五、存量由升级补修结算一次。** `upgrade_rules.VERIFICATION_SETTLEMENT` 记规则版本,`UpgradeRepairs.prepare` 在本地确定性补修之后,对候选件里带核查标记的行跑一遍自动落库,先备份账本,结果记进 `ledger_upgrade_repair` 的 `verification-settlement-<版本>`。判据再变时版本加一。不推进 `CATALOG`:那会重跑全部收集项,又以核查模式带回一批新差异。++## 理由++- 2591 条里需要人的判断只有几十条。其余要么什么都不用写,要么写的东西证据确定且能整批撤回,交给人只是让人重复代码已经得出的结论(ADR-0052)。+- 「覆盖已有值必须复核」防的是外部来源在无人知情时改掉判断。零写入的那几类不改任何东西;覆盖只发生在现值不归人、官方来源一致、链上没有更靠前的写入者时,旧值留在决定里,一条命令还原。+- NFO 是用户自己整理的资料,核查要回答的正是「它和发行方对不对得上」,所以 NFO 与链首来源的分歧仍然交人;社区来源对 NFO 的异议按 ADR-0033 不算。+- 判据放在领域层、复核页与处理任务共用,复核页上看不见的行,处理任务也不会悄悄跳过不落。++## 被否决的方案++- **只在复核页过滤。** 处理任务仍对这些行跳过,标签与日期一直不落;真实用户那边照样攒着这批待办。+- **厂牌、系列也按官方一致覆盖。** 写入要改作品与实体的关联,还可能新建实体;快照里的真实样例几乎都是 label 与 maker 的取舍或别名缺失,覆盖等于替人做身份判断。+- **有码作品的核查标签按 ADR-0100 整套换成 JavDB 的。** 换掉的旧标签不在可撤回的范围里;并集只增不删,旧的宽泛标签仍可由人在详情页删。+- **推进 `CATALOG` 让升级重跑处理任务。** 每部片会以核查模式再带回一批差异,正是这次要收的那种。++## 后果++- 对 2026-11-04 快照重放:2775 条里保留现值 1446、标签并集 967、官方覆盖 100、交人 78;另有 184 条不是核查差异(候选变了的过期决定、等收录的生词、资产已不在的旧行),不归本 ADR。+- 在真实账本的拷贝上跑升级补修结算:标签并集 688 行、官方覆盖 93 行,撤回计划逐条认得回。+- 复核页的元数据队列每次多做一轮核查判断;资产按番号一次查齐,取数耗时与此前同一量级。+- 处理任务摘要多出 `kept`(核查差异保留现值的行数)。+- 核查行里来源还不认的生词不再单独摆上复核页;词在补空的行上照常等人收录,收录后下一轮并集照样补。