feat(music): 音乐订阅刷新与识别缓存

tests/test_indexer_spider_search_url.py

@@ -32,6 +32,14 @@ def _get_search_url(indexer: dict, keyword: str | list[str], mtype: MediaType =
     return spider._SiteSpider__get_search_url()
 
 
+def _get_browse_url(indexer: dict, mtype: MediaType = None, page: int = 0) -> str:
+    """
+    调用 SiteSpider 无关键词浏览的 URL 构造逻辑，模拟订阅刷新抓取首页。
+    """
+    spider = SiteSpider(indexer=indexer, keyword=None, mtype=mtype, page=page)
+    return spider._SiteSpider__get_search_url()
+
+
 def _get_haidan_params(keyword: str | None, mtype: MediaType = None) -> dict:
     """
     调用 HaiDanSpider 私有参数构造逻辑，避免真实请求站点。
@@ -217,6 +225,64 @@ def test_typed_search_path_falls_back_to_all_path():
     assert parsed_url.path == "/torrents.php"
 
 
+def test_music_browse_uses_dedicated_music_entry():
+    """
+    订阅刷新浏览音乐资源时应使用站点的音乐专用入口，而不是默认首页。
+    """
+    indexer = _build_indexer(
+        id="hhanclub",
+        domain="https://hhanclub.net/",
+        search={
+            "paths": [
+                {"path": "torrents.php", "type": "all"},
+                {"path": "special.php", "type": "music"},
+            ],
+            "params": {"search": "{keyword}"},
+        },
+    )
+
+    assert urlparse(_get_browse_url(indexer, MediaType.MUSIC)).path == "/special.php"
+    # 未指定媒体类型时仍浏览默认首页，保持影视刷新行为不变
+    assert urlparse(_get_browse_url(indexer)).path == "/torrents.php"
+
+
+def test_music_browse_overrides_browse_config_path():
+    """
+    同时配置 browse 路径和音乐专用路径时，音乐浏览应优先使用专用入口。
+    """
+    indexer = _build_indexer(
+        search={
+            "paths": [
+                {"path": "torrents.php", "type": "all"},
+                {"path": "music.php", "type": "music"},
+            ],
+            "params": {"search": "{keyword}"},
+        },
+        browse={"path": "browse.php"},
+    )
+
+    assert urlparse(_get_browse_url(indexer, MediaType.MUSIC)).path == "/music.php"
+    assert urlparse(_get_browse_url(indexer)).path == "/browse.php"
+
+
+def test_browse_pagination_appends_existing_query_string():
+    """
+    浏览路径自带查询参数时翻页应追加 & 连接符，不能拼出两个问号。
+    """
+    indexer = _build_indexer(
+        search={
+            "paths": [{"path": "torrents.php?action=advanced&searchstr={keyword}"}],
+        },
+    )
+
+    browse_url = _get_browse_url(indexer, page=1)
+
+    assert browse_url.count("?") == 1
+    query = parse_qs(urlparse(browse_url).query)
+    assert query["page"] == ["1"]
+    assert query["action"] == ["advanced"]
+
+
 def test_category_item_can_use_distinct_search_parameter_value():
     """
     DiscuzX 子分类可以用展示分类 ID 解析结果，同时用父分类值构造搜索参数。

tests/test_music_recognize_cache.py

@@ -0,0 +1,436 @@
+"""MusicBrainz 音乐识别本地持久化缓存测试。
+
+覆盖缓存键生成、读写回环、负缓存、持久化恢复与保存、管理端点
+统计与权限，以及 MusicBrainzModule 识别流程对缓存的命中与回填。
+"""
+import asyncio
+import inspect
+import pickle
+from unittest.mock import Mock
+
+from app.api.endpoints import music as music_endpoint
+from app.core.context import MusicInfo
+from app.core.meta import MetaMusic
+from app.db.user_oper import get_current_active_superuser_async
+from app.modules.musicbrainz import music_cache as music_cache_module
+from app.modules.musicbrainz import MusicBrainzModule
+from app.modules.musicbrainz.music_cache import MusicBrainzCache
+
+
+class _MemoryCacheStub:
+    """提供音乐缓存管理测试所需的最小内存后端。"""
+
+    def __init__(self, data: dict):
+        """使用给定字典初始化测试缓存。"""
+        self.data = data
+
+    @staticmethod
+    def is_redis() -> bool:
+        """测试替身固定使用非 Redis 后端。"""
+        return False
+
+    def items(self):
+        """返回全部缓存条目。"""
+        return self.data.items()
+
+    def get(self, key: str):
+        """读取指定缓存条目。"""
+        return self.data.get(key)
+
+    def delete(self, key: str):
+        """删除指定缓存条目。"""
+        self.data.pop(key, None)
+
+    def set(self, key: str, value, ttl=None):
+        """写入指定缓存条目。"""
+        self.data[key] = value
+
+    def clear(self):
+        """清空全部缓存条目。"""
+        self.data.clear()
+
+
+class _TTLCacheStub(_MemoryCacheStub):
+    """记录每条数据恢复时剩余 TTL 的内存缓存替身。"""
+
+    def __init__(self):
+        """初始化空缓存和 TTL 记录。"""
+        super().__init__({})
+        self.ttls = {}
+
+    def set(self, key: str, value, ttl=None):
+        """写入缓存并记录本次设置的 TTL。"""
+        super().set(key, value, ttl=ttl)
+        self.ttls[key] = ttl
+
+
+class _FileCacheStub:
+    """提供音乐缓存持久化测试所需的统一文件缓存替身。"""
+
+    def __init__(self, content: bytes = None):
+        """使用预置序列化内容初始化文件缓存。"""
+        self.content = content
+        self.set_calls = []
+        self.delete_calls = []
+
+    def get(self, key: str, region: str):
+        """读取预置缓存内容。"""
+        return self.content
+
+    def set(self, key: str, value: bytes, region: str):
+        """记录统一文件缓存写入。"""
+        self.content = value
+        self.set_calls.append((key, region))
+
+    def delete(self, key: str, region: str):
+        """记录统一文件缓存删除。"""
+        self.content = None
+        self.delete_calls.append((key, region))
+
+
+def _build_music_cache(data: dict) -> MusicBrainzCache:
+    """构造绕过单例初始化的音乐识别缓存测试实例。"""
+    cache = object.__new__(MusicBrainzCache)
+    cache.maxsize = 256
+    cache.ttl = 3600
+    cache.region = "__musicbrainz_cache__"
+    cache._cache = _MemoryCacheStub(data)
+    cache._expires_at = {key: float("inf") for key in data}
+    cache._dirty = False
+    cache._file_cache = None
+    cache.save = lambda force=False: None
+    return cache
+
+
+def _build_initialized_music_cache(monkeypatch, file_cache: _FileCacheStub,
+                                   runtime_cache: _TTLCacheStub,
+                                   now: float = 1000) -> MusicBrainzCache:
+    """使用可控时间和缓存替身初始化完整音乐识别缓存实例。"""
+    monkeypatch.setattr(music_cache_module, "time", lambda: now)
+    monkeypatch.setattr(music_cache_module, "TTLCache", lambda **kwargs: runtime_cache)
+    monkeypatch.setattr(music_cache_module, "FileCache", lambda **kwargs: file_cache)
+    cache = object.__new__(MusicBrainzCache)
+    cache.__init__()
+    return cache
+
+
+def _music_info(**kwargs) -> MusicInfo:
+    """构造标准音乐识别结果，默认携带远端身份。"""
+    defaults = {
+        "source": "musicbrainz",
+        "media_id": "rec-1",
+        "title": "晴天",
+        "artists": ["周杰伦"],
+        "album": "叶惠美",
+        "year": 2003,
+    }
+    defaults.update(kwargs)
+    return MusicInfo(**defaults)
+
+
+def test_music_cache_endpoints_require_superuser():
+    """音乐识别缓存管理接口必须仅允许超级管理员访问。"""
+    endpoints = [
+        music_endpoint.music_recognition_cache,
+        music_endpoint.delete_music_recognition_cache,
+        music_endpoint.clear_music_recognition_cache,
+    ]
+
+    for endpoint in endpoints:
+        dependency = inspect.signature(endpoint).parameters["_"].default.dependency
+        assert dependency is get_current_active_superuser_async
+
+
+def test_music_cache_key_prefers_media_id():
+    """携带数据源原生 ID 的元数据应以 ID 作为缓存键主身份。"""
+    cache = _build_music_cache({})
+    meta = MetaMusic(title="晴天", artists=["周杰伦"], media_id="rec-1")
+
+    cache.update(meta, _music_info())
+
+    # 缓存键取自请求元数据，携带原生 ID 时以 ID 为主身份
+    assert list(cache._cache.data.keys()) == ["[音乐]rec-1-周杰伦-None-None"]
+
+
+def test_music_cache_update_and_get_roundtrip():
+    """识别结果入缓存后应能还原出标准音乐信息，且不保存上游原始响应。"""
+    cache = _build_music_cache({})
+    meta = MetaMusic(title="晴天", artists=["周杰伦"], album="叶惠美", year=2003)
+    info = _music_info(raw_data={"payload": "large"})
+
+    cache.update(meta, info)
+    hit = cache.get(meta)
+
+    assert hit is not None
+    assert hit.media_id == "rec-1"
+    assert hit.title == "晴天"
+    assert hit.artists == ["周杰伦"]
+    stored = next(iter(cache._cache.data.values()))
+    assert "raw_data" not in stored
+
+
+def test_music_cache_get_miss_returns_none():
+    """未命中的缓存查询应返回 None 而不是抛错。"""
+    cache = _build_music_cache({})
+    meta = MetaMusic(title="未知曲目")
+
+    assert cache.get(meta) is None
+
+
+def test_music_cache_list_items_normalizes_and_sorts():
+    """管理列表应输出稳定顺序和前端展示所需字段。"""
+    cache = _build_music_cache({
+        "z-key": {
+            "media_id": "rec-2",
+            "title": "Zulu",
+            "artists": ["歌手B"],
+            "album": "专辑B",
+            "year": 2024,
+            "music_type": "recording",
+        },
+        "a-key": {
+            "media_id": "",
+            "title": "Alpha",
+            "year": 2023,
+        },
+    })
+
+    items = cache.list_items()
+
+    assert [item["key"] for item in items] == ["a-key", "z-key"]
+    assert items[0]["media_id"] == ""
+    assert items[0]["artists"] == []
+    assert items[0]["music_type"] == "recording"
+    assert items[1]["artists"] == ["歌手B"]
+
+
+def test_music_cache_delete_and_clear_persist_immediately(monkeypatch):
+    """管理操作应修改运行时缓存并立即触发本地持久化。"""
+    cache = _build_music_cache({"first": {"media_id": "rec-1"}, "second": {"media_id": "rec-2"}})
+    saved_forces = []
+    monkeypatch.setattr(cache, "save", lambda force=False: saved_forces.append(force))
+
+    assert cache.delete("first") == {"media_id": "rec-1"}
+    assert cache.delete("missing") == {}
+    cache.clear()
+
+    assert cache.list_items() == []
+    assert saved_forces == [True, True]
+
+
+def test_music_cache_restores_only_unexpired_persisted_items(monkeypatch):
+    """持久化恢复应保留每条数据原有期限并跳过已过期条目。"""
+    payload = {
+        "version": music_cache_module.PERSISTENCE_VERSION,
+        "items": {
+            "fresh": {
+                "value": {"media_id": "rec-1", "title": "有效"},
+                "expires_at": 1030,
+            },
+            "expired": {
+                "value": {"media_id": "rec-2", "title": "过期"},
+                "expires_at": 999,
+            },
+        },
+    }
+    file_cache = _FileCacheStub(pickle.dumps(payload))
+    runtime_cache = _TTLCacheStub()
+
+    cache = _build_initialized_music_cache(
+        monkeypatch=monkeypatch,
+        file_cache=file_cache,
+        runtime_cache=runtime_cache,
+    )
+
+    assert runtime_cache.data == {"fresh": {"media_id": "rec-1", "title": "有效"}}
+    assert runtime_cache.ttls == {"fresh": 30}
+    assert cache._expires_at == {"fresh": 1030}
+
+
+def test_music_cache_persists_only_items_with_media_id(monkeypatch):
+    """持久化应跳过未识别的负缓存条目，只保存携带远端身份的结果。"""
+    file_cache = _FileCacheStub()
+    runtime_cache = _TTLCacheStub()
+    cache = _build_initialized_music_cache(
+        monkeypatch=monkeypatch,
+        file_cache=file_cache,
+        runtime_cache=runtime_cache,
+    )
+    runtime_cache.data = {
+        "recognized": {"media_id": "rec-1", "title": "晴天"},
+        "negative": {"media_id": "", "title": "未知曲目"},
+    }
+    cache._expires_at = {
+        "recognized": 1060,
+        "negative": 1070,
+    }
+    cache._dirty = True
+
+    cache.save()
+
+    payload = pickle.loads(file_cache.content)
+    assert file_cache.set_calls == [(
+        music_cache_module.PERSISTENCE_KEY,
+        music_cache_module.PERSISTENCE_REGION,
+    )]
+    assert payload == {
+        "version": music_cache_module.PERSISTENCE_VERSION,
+        "items": {
+            "recognized": {
+                "value": {"media_id": "rec-1", "title": "晴天"},
+                "expires_at": 1060,
+            },
+        },
+    }
+
+
+def test_music_cache_save_removes_file_when_empty(monkeypatch):
+    """全部条目失效后保存应删除持久化文件。"""
+    file_cache = _FileCacheStub(pickle.dumps({"version": 1, "items": {}}))
+    runtime_cache = _TTLCacheStub()
+    cache = _build_initialized_music_cache(
+        monkeypatch=monkeypatch,
+        file_cache=file_cache,
+        runtime_cache=runtime_cache,
+    )
+    cache._dirty = True
+
+    cache.save()
+
+    assert file_cache.delete_calls == [(
+        music_cache_module.PERSISTENCE_KEY,
+        music_cache_module.PERSISTENCE_REGION,
+    )]
+
+
+def test_music_cache_endpoint_returns_management_statistics(monkeypatch):
+    """查询接口应返回识别成功和失败条目的统计。"""
+    cache = _build_music_cache({
+        "recognized": {"media_id": "rec-1", "title": "晴天"},
+        "unrecognized": {"media_id": "", "title": "未知曲目"},
+    })
+    monkeypatch.setattr(music_endpoint, "MusicBrainzCache", lambda: cache)
+
+    response = asyncio.run(music_endpoint.music_recognition_cache(None))
+
+    assert response.success is True
+    assert response.data["count"] == 2
+    assert response.data["recognized"] == 1
+    assert response.data["unrecognized"] == 1
+    assert len(response.data["data"]) == 2
+
+
+def test_music_cache_delete_endpoint_reports_missing_item(monkeypatch):
+    """删除接口应区分成功删除与缓存不存在。"""
+    cache = _build_music_cache({"existing": {"media_id": "rec-1"}})
+    monkeypatch.setattr(music_endpoint, "MusicBrainzCache", lambda: cache)
+
+    deleted_response = asyncio.run(
+        music_endpoint.delete_music_recognition_cache("existing", None)
+    )
+    missing_response = asyncio.run(
+        music_endpoint.delete_music_recognition_cache("missing", None)
+    )
+
+    assert deleted_response.success is True
+    assert missing_response.success is False
+
+
+def test_music_cache_clear_endpoint_removes_all_items(monkeypatch):
+    """清空接口应删除全部音乐识别缓存。"""
+    cache = _build_music_cache({"existing": {"media_id": "rec-1"}})
+    monkeypatch.setattr(music_endpoint, "MusicBrainzCache", lambda: cache)
+
+    response = asyncio.run(music_endpoint.clear_music_recognition_cache(None))
+
+    assert response.success is True
+    assert cache.list_items() == []
+
+
+def _build_module_with_cache(cache: MusicBrainzCache) -> MusicBrainzModule:
+    """构造挂载测试缓存的 MusicBrainz 模块实例。"""
+    module = MusicBrainzModule()
+    module.cache = cache
+    return module
+
+
+def test_module_recognize_media_hits_cache_without_search(monkeypatch):
+    """识别缓存命中时应直接返回缓存结果，不再触发 MusicBrainz 搜索。"""
+    cache = _build_music_cache({})
+    module = _build_module_with_cache(cache)
+    meta = MetaMusic(title="晴天", artists=["周杰伦"], album="叶惠美", year=2003)
+    cache.update(meta, _music_info())
+    search_mock = Mock()
+    monkeypatch.setattr(module, "_search_recordings", search_mock)
+
+    result = module.recognize_media(meta=meta)
+
+    assert result is not None
+    assert result.media_id == "rec-1"
+    assert getattr(result, "recognize_cache_hit") is True
+    search_mock.assert_not_called()
+
+
+def test_module_recognize_media_bypasses_cache_when_disabled(monkeypatch):
+    """cache=False 时不读取缓存，重新走搜索识别流程。"""
+    cache = _build_music_cache({})
+    module = _build_module_with_cache(cache)
+    meta = MetaMusic(title="晴天", artists=["周杰伦"], album="叶惠美", year=2003)
+    cache.update(meta, _music_info())
+    fresh = _music_info(media_id="rec-2")
+    monkeypatch.setattr(module, "_search_recordings", Mock(return_value=[fresh]))
+    monkeypatch.setattr(module, "_select_candidate", Mock(return_value=fresh))
+
+    result = module.recognize_media(meta=meta, cache=False)
+
+    assert result is fresh
+    assert getattr(result, "recognize_cache_hit", False) is False
+
+
+def test_module_recognize_media_writes_search_result_to_cache(monkeypatch):
+    """搜索识别成功后应回填本地识别缓存。"""
+    cache = _build_music_cache({})
+    module = _build_module_with_cache(cache)
+    meta = MetaMusic(title="晴天", artists=["周杰伦"], album="叶惠美", year=2003)
+    matched = _music_info()
+    monkeypatch.setattr(module, "_search_recordings", Mock(return_value=[matched]))
+    monkeypatch.setattr(module, "_select_candidate", Mock(return_value=matched))
+
+    result = module.recognize_media(meta=meta)
+
+    assert result is matched
+    hit = cache.get(meta)
+    assert hit is not None
+    assert hit.media_id == "rec-1"
+
+
+def test_module_recognize_media_caches_offline_fallback(monkeypatch):
+    """搜索无结果的兜底信息也应进入负缓存，避免重复请求。"""
+    cache = _build_music_cache({})
+    module = _build_module_with_cache(cache)
+    meta = MetaMusic(title="未知曲目", artists=["未知艺术家"])
+    monkeypatch.setattr(module, "_search_recordings", Mock(return_value=[]))
+    monkeypatch.setattr(module, "_search_albums", Mock(return_value=[]))
+
+    result = module.recognize_media(meta=meta)
+
+    assert result is not None
+    assert result.media_id is None
+    cached = cache.get(meta)
+    assert cached is not None
+    assert cached.media_id is None
+    assert cached.title == "未知曲目"
+
+
+def test_module_update_recognize_cache_only_for_musicbrainz_music():
+    """共享识别回填仅处理本数据源的音乐结果。"""
+    cache = _build_music_cache({})
+    module = _build_module_with_cache(cache)
+    meta = MetaMusic(title="晴天", artists=["周杰伦"])
+
+    assert module.update_recognize_cache(meta=meta, mediainfo=_music_info()) is True
+    assert cache.get(meta) is not None
+
+    other_source = _music_info(source="other", media_id="x-1")
+    assert module.update_recognize_cache(meta=meta, mediainfo=other_source) is None
+    assert module.update_recognize_cache(meta=None, mediainfo=_music_info()) is None

tests/test_music_subscribe.py

@@ -593,3 +593,21 @@ def test_follow_preserves_album_entity_and_track_count():
     assert subscribe_oper.exist_history.call_args.kwargs["music_type"] == MUSIC_ENTITY_ALBUM
     assert add.call_args.kwargs["music_type"] == MUSIC_ENTITY_ALBUM
     assert add.call_args.kwargs["total_tracks"] == 11
+
+
+def test_refresh_enables_music_entry_fetch_when_music_subscribe_exists():
+    """存在音乐订阅时，订阅刷新应要求种子链额外抓取站点音乐专用入口。"""
+    chain = SubscribeChain()
+    subscribe_oper = Mock()
+    # get_subscribed_sites 不带状态查询，has_music_subscribe 按可搜索状态查询
+    subscribe_oper.list.side_effect = lambda state=None: [_subscribe(state="R")]
+    torrents_chain = Mock()
+    torrents_chain.refresh.return_value = {}
+
+    with patch("app.chain.subscribe.SubscribeOper", return_value=subscribe_oper), \
+            patch("app.chain.subscribe.SystemConfigOper") as system_config, \
+            patch("app.chain.subscribe.TorrentsChain", return_value=torrents_chain):
+        system_config.return_value.get.return_value = []
+        chain.refresh()
+
+    assert torrents_chain.refresh.call_args.kwargs["include_music"] is True

tests/test_music_torrents.py

@@ -1,9 +1,12 @@
 import asyncio
+import copy
+from types import SimpleNamespace
 from unittest.mock import AsyncMock, Mock, patch
 
 from app.chain.torrents import TorrentsChain
 from app.core.meta import MetaMusic
-from app.core.context import MusicInfo
+from app.core.context import Context, MusicInfo, TorrentInfo
+from app.modules.indexer.spider import SiteSpider
 from app.schemas.types import MediaType
 
 
@@ -67,3 +70,274 @@ def test_music_cache_context_uses_music_models():
     assert context.media_info.title == "Get Lucky"
     assert context.candidate_recognized is False
     media_chain.assert_not_called()
+
+
+def test_rss_sets_music_category_from_site_media_type():
+    """RSS 报文不带分类，音乐站点的种子应按站点媒体类型补充音乐分类。"""
+    chain = TorrentsChain()
+    site = {
+        "id": 9,
+        "name": "音乐站",
+        "domain": "https://music.example.com",
+        "media_type": "music",
+        "rss": "https://music.example.com/rss.php?passkey=key",
+        "proxy": False,
+        "timeout": 30,
+        "ua": None,
+    }
+    rss_items = [{
+        "title": "Daft Punk - Random Access Memories [FLAC]",
+        "enclosure": "https://music.example.com/download.php?id=1",
+        "link": "https://music.example.com/details.php?id=1",
+        "size": 1024,
+        "pubdate": None,
+    }]
+    sites_helper = Mock()
+    sites_helper.get_indexer.return_value = site
+
+    with (
+        patch("app.chain.torrents.SitesHelper", return_value=sites_helper),
+        patch("app.chain.torrents.RssHelper") as rss_helper,
+    ):
+        rss_helper.return_value.parse.return_value = rss_items
+        torrents = chain.rss("music.example.com")
+
+    assert len(torrents) == 1
+    assert torrents[0].category == MediaType.MUSIC.value
+
+
+def test_music_browse_paths_detects_dedicated_entry():
+    """站点用 type=music 声明的独立音乐入口应被识别，默认入口已覆盖时不重复抓取。"""
+    mixed_site = {
+        "search": {
+            "paths": [
+                {"path": "torrents.php", "type": "all"},
+                {"path": "special.php", "type": "music"},
+            ]
+        }
+    }
+    assert TorrentsChain._music_browse_paths(mixed_site) == ["special.php"]
+
+    # 音乐站点全站都是音乐，无需额外入口
+    music_site = {"media_type": "music", "search": {"paths": [
+        {"path": "torrents.php", "type": "all"},
+        {"path": "torrents.php", "type": "music"},
+    ]}}
+    assert TorrentsChain._music_browse_paths(music_site) == []
+
+    # 音乐入口与默认入口相同无需重复抓取
+    same_entry_site = {"search": {"paths": [
+        {"path": "torrents.php", "type": "all"},
+        {"path": "torrents.php", "type": "music"},
+    ]}}
+    assert TorrentsChain._music_browse_paths(same_entry_site) == []
+
+
+def test_spider_music_entry_browse_resolves_music_category():
+    """音乐入口浏览应请求专用页面，并把音乐分类种子解析为音乐类型。"""
+    indexer = {
+        "id": "hhanclub",
+        "name": "憨憨",
+        "domain": "https://hhanclub.net/",
+        "search": {
+            "paths": [
+                {"path": "torrents.php", "type": "all"},
+                {"path": "special.php", "type": "music"},
+            ],
+            "params": {"search": "{keyword}"},
+        },
+        "category": {
+            "param": "cat",
+            "movie": [{"id": "401", "cat": "Movies"}],
+            "music": [{"id": "410", "cat": "Music"}],
+        },
+        "torrents": {
+            "list": {"selector": "table tr.torrent"},
+            "fields": {
+                "title": {"selector": "a.t"},
+                "category": {
+                    "selector": "a.c",
+                    "attribute": "href",
+                    "filters": [{"name": "querystring", "args": "cat"}],
+                },
+                "download": {"selector": "a.d", "attribute": "href"},
+            },
+        },
+    }
+    html = """
+    <table>
+      <tr class="torrent">
+        <td><a class="c" href="torrents.php?cat=410">Music</a></td>
+        <td><a class="t">Daft Punk - Random Access Memories [FLAC]</a></td>
+        <td><a class="d" href="download.php?id=9">下载</a></td>
+      </tr>
+    </table>
+    """
+    request_utils = Mock()
+    request_utils.return_value.get_res.return_value = Mock()
+    request_utils.get_decoded_html_content.return_value = html
+
+    with (
+        patch("app.modules.indexer.spider.RequestUtils", request_utils),
+        patch(
+            "app.modules.indexer.spider.rust_accel.parse_indexer_torrents",
+            return_value=None,
+        ),
+    ):
+        torrents = SiteSpider(indexer=indexer, mtype=MediaType.MUSIC).get_torrents()
+
+    # 请求必须命中音乐专用入口而不是默认首页
+    requested_url = request_utils.return_value.get_res.call_args[0][0]
+    assert "/special.php" in requested_url
+    assert len(torrents) == 1
+    assert torrents[0]["category"] == MediaType.MUSIC.value
+    assert torrents[0]["title"] == "Daft Punk - Random Access Memories [FLAC]"
+
+
+def test_refresh_include_music_fetches_music_entry():
+    """存在音乐订阅时，spider 刷新应额外抓取音乐专用入口，并把音乐写入独立缓存。"""
+    chain = TorrentsChain()
+    default_torrent = TorrentInfo(
+        site=1, site_name="Test",
+        title="Some.Movie.2026.1080p",
+        enclosure="https://example.com/download?id=1",
+        category=MediaType.MOVIE.value,
+        pubdate="2026-08-07 00:00:00",
+    )
+    music_torrent = TorrentInfo(
+        site=1, site_name="Test",
+        title="Daft Punk - Get Lucky [FLAC]",
+        enclosure="https://example.com/download?id=2",
+        category=MediaType.MUSIC.value,
+        pubdate="2026-08-08 00:00:00",
+    )
+    duplicated_torrent = TorrentInfo(
+        site=1, site_name="Test",
+        title="Daft Punk - Get Lucky [FLAC]",
+        enclosure="https://example.com/download?id=2",
+        category=MediaType.MUSIC.value,
+        pubdate="2026-08-08 00:00:00",
+    )
+
+    def _fake_browse(domain, keyword=None, cat=None, page=None, mtype=None):
+        if mtype == MediaType.MUSIC:
+            # 第二页返回空，验证分页提前结束；首页返回音乐种子
+            return [] if page else [music_torrent, duplicated_torrent]
+        return [default_torrent] if not page else []
+
+    sites_helper = Mock()
+    sites_helper.get_indexers.return_value = [{
+        "id": 1,
+        "name": "Test",
+        "domain": "https://example.com",
+        "search": {
+            "paths": [
+                {"path": "torrents.php", "type": "all"},
+                {"path": "special.php", "type": "music"},
+            ]
+        },
+    }]
+    # 保存时对入参做快照，避免后续合并返回值修改同一字典引用
+    saved = {}
+    save_cache = Mock(side_effect=lambda data, filename: saved.__setitem__(filename, copy.deepcopy(data)))
+
+    with (
+        patch.object(chain, "load_cache", return_value=None),
+        patch.object(chain, "browse", side_effect=_fake_browse),
+        patch.object(chain, "save_cache", save_cache),
+        patch("app.chain.torrents.SitesHelper", return_value=sites_helper),
+        patch("app.chain.torrents.MediaChain"),
+    ):
+        result = chain.refresh(stype="spider", sites=[1], include_music=True)
+
+    # 返回值供订阅匹配，包含影视与音乐完整候选且去重
+    contexts = result["example.com"]
+    titles = {context.torrent_info.title for context in contexts}
+    assert titles == {"Some.Movie.2026.1080p", "Daft Punk - Get Lucky [FLAC]"}
+    music_context = next(
+        context for context in contexts
+        if context.torrent_info.title.startswith("Daft Punk")
+    )
+    assert isinstance(music_context.meta_info, MetaMusic)
+    assert isinstance(music_context.media_info, MusicInfo)
+    # 音乐不应经过影视识别链的媒体回填
+    assert music_context.candidate_recognized is False
+
+    # 影视与音乐分别写入各自缓存文件，音乐不占用影视缓存空间
+    assert set(saved) == {TorrentsChain._spider_file, TorrentsChain._music_spider_file}
+    video_titles = {
+        context.torrent_info.title for context in saved[TorrentsChain._spider_file]["example.com"]
+    }
+    music_titles = {
+        context.torrent_info.title for context in saved[TorrentsChain._music_spider_file]["example.com"]
+    }
+    assert video_titles == {"Some.Movie.2026.1080p"}
+    assert music_titles == {"Daft Punk - Get Lucky [FLAC]"}
+
+
+def test_music_cache_not_evicted_by_video_torrents():
+    """影视缓存按配额裁剪时，音乐独立缓存中的资源不应被挤出。"""
+    chain = TorrentsChain()
+
+    def _music_context(title, enclosure, pubdate):
+        torrent = TorrentInfo(
+            site=1, site_name="Test", title=title, enclosure=enclosure,
+            category=MediaType.MUSIC.value, pubdate=pubdate,
+        )
+        return Context(
+            meta_info=MetaMusic(org_string=title, title=title),
+            media_info=MusicInfo(title=title),
+            torrent_info=torrent,
+        )
+
+    existing_music = [
+        _music_context(f"Album {i}", f"https://example.com/download?id=m{i}",
+                       f"2026-08-0{i + 1} 00:00:00")
+        for i in range(2)
+    ]
+    video_torrents = [
+        TorrentInfo(
+            site=1, site_name="Test", title=f"Movie.{i}.1080p",
+            enclosure=f"https://example.com/download?id=v{i}",
+            category=MediaType.MOVIE.value, pubdate=f"2026-08-1{i} 00:00:00",
+        )
+        for i in range(3)
+    ]
+
+    def _fake_load(filename):
+        if filename == TorrentsChain._music_spider_file:
+            return {"example.com": existing_music}
+        return None
+
+    def _fake_browse(domain, keyword=None, cat=None, page=None, mtype=None):
+        return video_torrents if not page else []
+
+    sites_helper = Mock()
+    sites_helper.get_indexers.return_value = [{
+        "id": 1, "name": "Test", "domain": "https://example.com",
+    }]
+    saved = {}
+    save_cache = Mock(side_effect=lambda data, filename: saved.__setitem__(filename, copy.deepcopy(data)))
+    fake_settings = Mock()
+    # 公共参数：缓存上限 2，刷新配额 5，音乐与影视各自独立计算
+    fake_settings.CONF = SimpleNamespace(torrents=2, refresh=5)
+    fake_settings.NO_CACHE_SITE_KEY = "no-cache-site.invalid"
+
+    with (
+        patch("app.chain.torrents.settings", fake_settings),
+        patch.object(chain, "load_cache", side_effect=_fake_load),
+        patch.object(chain, "browse", side_effect=_fake_browse),
+        patch.object(chain, "save_cache", save_cache),
+        patch("app.chain.torrents.SitesHelper", return_value=sites_helper),
+        patch("app.chain.torrents.MediaChain"),
+    ):
+        chain.refresh(stype="spider", sites=[1])
+
+    # 影视缓存独立按配额裁剪，仅保留最新的两条
+    assert len(saved[TorrentsChain._spider_file]["example.com"]) == 2
+    # 音乐独立缓存不受影视种子大量涌入影响，既有的两条音乐完整保留
+    music_titles = {
+        context.torrent_info.title
+        for context in saved[TorrentsChain._music_spider_file]["example.com"]
+    }
+    assert music_titles == {"Album 0", "Album 1"}