fix(transfer): 修复订阅自定义识别词在整理时失效 (#6018)

app/chain/download.py

@@ -478,7 +478,8 @@ class DownloadChain(ChainBase):
                         userid: Union[str, int] = None,
                         username: Optional[str] = None,
                         label: Optional[str] = None,
-                        return_detail: bool = False) -> Union[Optional[str], Tuple[Optional[str], Optional[str]]]:
+                        return_detail: bool = False,
+                        custom_words: Optional[str] = None) -> Union[Optional[str], Tuple[Optional[str], Optional[str]]]:
         """
         下载及发送通知
         :param context: 资源上下文
@@ -493,6 +494,7 @@ class DownloadChain(ChainBase):
         :param username: 调用下载的用户名/插件名
         :param label: 自定义标签
         :param return_detail: 是否返回详细结果；False 时返回下载任务 hash 或 None，True 时返回 (hash, error_msg)
+        :param custom_words: 下载来源（如订阅）的完整自定义识别词文本，随下载记录存档，供整理时原样复现识别
         :return: return_detail=False 时返回下载任务 hash 或 None；return_detail=True 时返回 (hash, error_msg)
         """
         _torrent = context.torrent_info
@@ -649,7 +651,8 @@ class DownloadChain(ChainBase):
                 date=time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()),
                 media_category=_media.category,
                 episode_group=_media.episode_group,
-                note={"source": source}
+                note={"source": source},
+                custom_words=custom_words
             )
 
             # 登记下载文件
@@ -738,7 +741,8 @@ class DownloadChain(ChainBase):
                        source: Optional[str] = None,
                        userid: Optional[str] = None,
                        username: Optional[str] = None,
-                       downloader: Optional[str] = None
+                       downloader: Optional[str] = None,
+                       custom_words: Optional[str] = None
                        ) -> Tuple[List[Context], Dict[Union[int, str], Dict[int, NotExistMediaInfo]]]:
         """
         根据缺失数据，自动种子列表中组合择优下载
@@ -750,6 +754,7 @@ class DownloadChain(ChainBase):
         :param userid:  用户ID
         :param username: 调用下载的用户名/插件名
         :param downloader: 下载器
+        :param custom_words: 下载来源（如订阅）的完整自定义识别词文本，随下载记录存档，供整理时原样复现识别
         :return: 已经下载的资源列表、剩余未下载到的剧集 no_exists[tmdb_id/douban_id] = {season: NotExistMediaInfo}
         """
         # 已下载的项目
@@ -890,7 +895,7 @@ class DownloadChain(ChainBase):
                 logger.info(f"开始下载电影 {context.torrent_info.title} ...")
                 if self.download_single(context, save_path=save_path, channel=channel,
                                         source=source, userid=userid, username=username,
-                                        downloader=downloader):
+                                        downloader=downloader, custom_words=custom_words):
                     # 下载成功
                     logger.info(f"{context.torrent_info.title} 添加下载成功")
                     downloaded_list.append(context)
@@ -993,7 +998,8 @@ class DownloadChain(ChainBase):
                                         source=source,
                                         userid=userid,
                                         username=username,
-                                        downloader=downloader
+                                        downloader=downloader,
+                                        custom_words=custom_words
                                     )
                             else:
                                 # 下载
@@ -1001,7 +1007,8 @@ class DownloadChain(ChainBase):
                                 download_id = self.download_single(context, save_path=save_path,
                                                                    channel=channel, source=source,
                                                                    userid=userid, username=username,
-                                                                   downloader=downloader)
+                                                                   downloader=downloader,
+                                                                   custom_words=custom_words)
 
                             if download_id:
                                 # 下载成功
@@ -1085,7 +1092,8 @@ class DownloadChain(ChainBase):
                                 download_id = self.download_single(context, save_path=save_path,
                                                                    channel=channel, source=source,
                                                                    userid=userid, username=username,
-                                                                   downloader=downloader)
+                                                                   downloader=downloader,
+                                                                   custom_words=custom_words)
                                 if download_id:
                                     # 下载成功
                                     if __requires_complete_coverage(tv):
@@ -1182,7 +1190,8 @@ class DownloadChain(ChainBase):
                                 source=source,
                                 userid=userid,
                                 username=username,
-                                downloader=downloader
+                                downloader=downloader,
+                                custom_words=custom_words
                             )
                             if not download_id:
                                 continue

app/chain/subscribe.py

@@ -586,6 +586,7 @@ class SubscribeChain(ChainBase):
                 save_path=save_path,
                 downloader=downloader,
                 source=source,
+                custom_words=subscribe.custom_words,
             )
             if downloads:
                 return downloads, lefts
@@ -598,6 +599,7 @@ class SubscribeChain(ChainBase):
             save_path=save_path,
             downloader=downloader,
             source=source,
+            custom_words=subscribe.custom_words,
         )
 
     @staticmethod

app/chain/transfer.py

@@ -2439,6 +2439,32 @@ class TransferChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
             self.__normalize_dir_path(Path(current_item.path).parent),
         )
 
+    @staticmethod
+    def _get_subscribe_custom_words(
+            history_record: Optional[DownloadHistory],
+    ) -> Optional[List[str]]:
+        """
+        获取整理用自定义识别词：优先使用下载时保存的快照，无快照（历史旧记录）时再按来源实时反查订阅。
+
+        快照优先可避免整理阶段因订阅季号漂移、来源解析失败或订阅完成被删导致识别词丢失，从而原样入库到偏移前的季集。
+        """
+        if not history_record:
+            return None
+        # 下载时保存的完整订阅识别词快照优先
+        if history_record.custom_words:
+            return history_record.custom_words.split("\n")
+        # 兜底：历史旧记录无快照时，按下载来源实时反查订阅
+        if not isinstance(history_record.note, dict):
+            return None
+        subscribe = SubscribeChain().get_subscribe_by_source(
+            history_record.note.get("source")
+        )
+        return (
+            subscribe.custom_words.split("\n")
+            if subscribe and subscribe.custom_words
+            else None
+        )
+
     def do_transfer(
             self,
             fileitem: FileItem,
@@ -2515,24 +2541,6 @@ class TransferChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
         # 汇总错误信息
         err_msgs: List[str] = []
 
-        def _get_subscribe_custom_words(
-                history_record: Optional[DownloadHistory],
-        ) -> Optional[List[str]]:
-            """
-            根据下载记录获取订阅自定义识别词。
-            """
-            if not history_record or not isinstance(history_record.note, dict):
-                return None
-            # 使用source动态获取订阅
-            subscribe = SubscribeChain().get_subscribe_by_source(
-                history_record.note.get("source")
-            )
-            return (
-                subscribe.custom_words.split("\n")
-                if subscribe and subscribe.custom_words
-                else None
-            )
-
         def _build_file_meta(
                 source_path: Path,
                 custom_word_list: Optional[List[str]] = None,
@@ -2656,7 +2664,7 @@ class TransferChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
             )
             return _build_file_meta(
                 main_path,
-                custom_word_list=_get_subscribe_custom_words(main_download_history),
+                custom_word_list=self._get_subscribe_custom_words(main_download_history),
             )
 
         def _append_item(
@@ -2814,7 +2822,7 @@ class TransferChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
                     bluray_dir=main_bluray_dir,
                     download_hash=download_hash,
                 )
-                subscribe_custom_words = _get_subscribe_custom_words(
+                subscribe_custom_words = self._get_subscribe_custom_words(
                     main_download_history
                 )
                 main_meta = _build_file_meta(
@@ -2937,7 +2945,7 @@ class TransferChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
                     else:
                         file_meta = _build_file_meta(
                             file_path,
-                            custom_word_list=_get_subscribe_custom_words(download_history),
+                            custom_word_list=self._get_subscribe_custom_words(download_history),
                         )
                 else:
                     file_meta = _build_file_meta(file_path)

tests/test_download_chain.py

@@ -158,6 +158,61 @@ def test_download_single_submits_download_added_to_background(monkeypatch):
     )
 
 
+def test_download_single_persists_custom_words_snapshot(monkeypatch):
+    """下载成功登记历史时，应把传入的订阅识别词原样存入快照，供整理时原样复现识别。"""
+    captured = {}
+
+    class _CapturingDownloadHistoryOper:
+        """捕获写入下载历史的字段，验证识别词快照确实落库。"""
+
+        def add(self, **kwargs):
+            captured.update(kwargs)
+
+        def add_files(self, _files):
+            pass
+
+    _FakeThreadHelper.submitted = []
+    monkeypatch.setattr(download_module, "ThreadHelper", _FakeThreadHelper)
+    monkeypatch.setattr(download_module, "DownloadHistoryOper", _CapturingDownloadHistoryOper)
+    monkeypatch.setattr(download_module, "TorrentHelper", _FakeTorrentHelper)
+
+    chain = DownloadChain.__new__(DownloadChain)
+    chain.download = MagicMock(return_value=("qb", "hash123", "Original", "添加下载成功"))
+    chain.download_added = MagicMock()
+    chain.eventmanager = MagicMock()
+    chain.eventmanager.send_event.return_value = None
+    chain.post_message = MagicMock()
+
+    context = Context(
+        meta_info=MetaInfo("Demo Show 2024"),
+        media_info=MediaInfo(
+            type=MediaType.TV,
+            title="Demo Show",
+            year="2024",
+            tmdb_id=1,
+            genre_ids=[18],
+        ),
+        torrent_info=TorrentInfo(
+            title="Demo Show 2024",
+            enclosure="https://example.com/demo.torrent",
+            site_cookie="uid=1",
+            site_name="TestSite",
+        ),
+    )
+
+    custom_words = "S04 => S01\n第 <> 集 >> EP+66"
+    result = chain.download_single(
+        context=context,
+        torrent_content=b"torrent-content",
+        save_path="/downloads",
+        username="tester",
+        custom_words=custom_words,
+    )
+
+    assert result == "hash123"
+    assert captured["custom_words"] == custom_words
+
+
 def test_save_subtitle_response_creates_missing_temp_directory(monkeypatch, tmp_path):
     """
     下载字幕 API 保存响应前应自动创建缺失的临时目录。
@@ -468,6 +523,29 @@ def test_batch_download_does_not_download_duplicate_movie_after_success(monkeypa
     assert chain.download_single.call_args.args[0] is first_context
 
 
+def test_batch_download_threads_custom_words_to_download_single(monkeypatch):
+    """订阅识别词须经 batch_download 透传到 download_single，作为整理快照随下载存档。"""
+    _FakeBatchTorrentHelper.episodes = []
+    monkeypatch.setattr(download_module, "TorrentHelper", _FakeBatchTorrentHelper)
+    monkeypatch.setattr(download_module.eventmanager, "send_event", lambda *args, **kwargs: None)
+
+    chain = DownloadChain.__new__(DownloadChain)
+    chain.download_single = MagicMock(return_value="hash")
+
+    context = SimpleNamespace(
+        media_info=SimpleNamespace(type=MediaType.MOVIE, title_year="Demo Movie (2026)"),
+        meta_info=SimpleNamespace(season_episode=""),
+        torrent_info=SimpleNamespace(title="Demo Movie"),
+    )
+
+    custom_words = "S04 => S01\n第 <> 集 >> EP+66"
+    downloads, _lefts = chain.batch_download(contexts=[context], custom_words=custom_words)
+
+    assert downloads == [context]
+    chain.download_single.assert_called_once()
+    assert chain.download_single.call_args.kwargs["custom_words"] == custom_words
+
+
 def test_batch_download_accepts_complete_coverage_when_files_cover_target_range(monkeypatch):
     """
     自定义起始集场景按目标范围覆盖判断，100-143 可满足 start=100、total=143。

tests/test_subscribe_chain.py

@@ -385,6 +385,7 @@ class SubscribeChainTest(TestCase):
             "description": None,
             "last_update": None,
             "username": None,
+            "custom_words": None,
             "to_dict": lambda: {},
         }
         data.update(overrides)
@@ -1247,7 +1248,11 @@ class SubscribeChainTest(TestCase):
         )
 
     def test_episode_best_version_downloads_full_pack_before_episode_fallback(self):
-        subscribe = self._build_subscribe(best_version_full=0, total_episode=3)
+        subscribe = self._build_subscribe(
+            best_version_full=0,
+            total_episode=3,
+            custom_words="S04 => S01\n第 <> 集 >> EP+66",
+        )
         full_pack_context = SimpleNamespace(
             torrent_info=SimpleNamespace(pri_order=90),
             media_info=SimpleNamespace(type=MediaType.TV),
@@ -1295,6 +1300,8 @@ class SubscribeChainTest(TestCase):
         self.assertEqual(len(calls), 1)
         self.assertEqual(calls[0]["contexts"], [full_pack_context])
         self.assertEqual(calls[0]["no_exists"]["media-key"][1].episodes, [])
+        # 订阅识别词须作为入参随下载下传，供整理时复现识别（避免下载模块反查订阅的循环依赖）
+        self.assertEqual(calls[0]["custom_words"], "S04 => S01\n第 <> 集 >> EP+66")
 
     def test_episode_best_version_falls_back_when_full_pack_not_downloaded(self):
         subscribe = self._build_subscribe(best_version_full=0, total_episode=3)

tests/test_transfer_custom_words.py

@@ -0,0 +1,76 @@
+# -*- coding: utf-8 -*-
+"""订阅自定义识别词快照用例：下载时保存完整识别词，整理时快照优先、实时反查兜底。
+
+回归场景：订阅做季+集组合偏移（如 S04E05→S01E71），下载阶段生效但整理阶段因实时反查订阅
+返回空而静默回退全局识别词、丢失偏移。修复后由订阅链在发起下载时将完整识别词作为入参传入
+下载模块并存档（避免下载模块反查订阅的同级循环依赖），整理时优先复用该快照。
+"""
+from types import SimpleNamespace
+
+import app.chain.transfer as transfer_module
+from app.chain.transfer import TransferChain
+
+
+def _fake_history(custom_words=None, note=None):
+    """构造仅含测试所需字段的下载历史替身。"""
+    return SimpleNamespace(custom_words=custom_words, note=note)
+
+
+def test_transfer_prefers_snapshot_over_live_lookup(monkeypatch):
+    """整理时存在下载快照，应直接使用快照且不触发实时反查订阅。"""
+    called = {"lookup": False}
+
+    class _GuardSubscribeChain:
+        def get_subscribe_by_source(self, source):
+            # 一旦走到实时反查即视为失败：快照存在时不应触发
+            called["lookup"] = True
+            return SimpleNamespace(custom_words="不应使用\n实时反查")
+
+    monkeypatch.setattr(transfer_module, "SubscribeChain", _GuardSubscribeChain)
+
+    history = _fake_history(
+        custom_words="S04 => S01\n第 <> 集 >> EP+66",
+        note={"source": "Subscribe|{...}"},
+    )
+    result = TransferChain._get_subscribe_custom_words(history)
+
+    assert result == ["S04 => S01", "第 <> 集 >> EP+66"]
+    assert called["lookup"] is False
+
+
+def test_transfer_falls_back_to_live_lookup_without_snapshot(monkeypatch):
+    """整理时无快照（历史旧记录），应按下载来源实时反查订阅取识别词。"""
+
+    class _FakeSubscribeChain:
+        def get_subscribe_by_source(self, source):
+            assert source == "Subscribe|{...}"
+            return SimpleNamespace(custom_words="A => B")
+
+    monkeypatch.setattr(transfer_module, "SubscribeChain", _FakeSubscribeChain)
+
+    history = _fake_history(custom_words=None, note={"source": "Subscribe|{...}"})
+    result = TransferChain._get_subscribe_custom_words(history)
+
+    assert result == ["A => B"]
+
+
+def test_transfer_returns_none_when_unavailable(monkeypatch):
+    """无下载记录、note 非字典、或来源反查不到订阅时返回 None（回退全局识别词）。"""
+
+    class _NoneSubscribeChain:
+        def get_subscribe_by_source(self, source):
+            return None
+
+    monkeypatch.setattr(transfer_module, "SubscribeChain", _NoneSubscribeChain)
+
+    # 无下载记录
+    assert TransferChain._get_subscribe_custom_words(None) is None
+    # 无快照且 note 非字典：不应触发实时反查
+    assert TransferChain._get_subscribe_custom_words(_fake_history(note="不是字典")) is None
+    # 无快照、来源可解析但反查不到订阅
+    assert (
+        TransferChain._get_subscribe_custom_words(
+            _fake_history(note={"source": "Subscribe|{}"})
+        )
+        is None
+    )