From 2e495e81295a7754e146e88f4e2e0c6fb5fd8a57 Mon Sep 17 00:00:00 2001 From: jxxghp Date: Thu, 12 Nov 2026 09:55:25 +0800 Subject: [PATCH] fix(scraping): honor music album track overwrite policy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 按音乐标签覆盖策略对专辑曲目做批次唯一匹配,保留有歧义或身份冲突的标签,并在响应和日志中说明处理结果。 Refs #7368 --- app/api/endpoints/media.py | 3 + app/chain/scraping.py | 314 ++++++++- docs/mcp-api.md | 2 + skills/moviepilot-api/SKILL.md | 7 +- skills/organize-files/SKILL.md | 5 +- tests/test_music_album_scrape_overwrite.py | 782 +++++++++++++++++++++ 6 files changed, 1087 insertions(+), 26 deletions(-) create mode 100644 tests/test_music_album_scrape_overwrite.py diff --git a/app/api/endpoints/media.py b/app/api/endpoints/media.py index c2b0cda22..f502a517e 100644 --- a/app/api/endpoints/media.py +++ b/app/api/endpoints/media.py @@ -638,6 +638,9 @@ def scrape( ) -> Any: """ 按请求级媒体身份、剧集组和音乐实体设置刮削单项媒体;会覆盖目标目录的图片和 NFO,与文件管理一样要求管理权限。 + + 专辑曲目标题、艺人和曲序仅在音乐标签策略为覆盖且曲目可靠对位时更新; + 未匹配或保留的情况通过响应消息说明。 """ return _scrape_impl( fileitem, diff --git a/app/chain/scraping.py b/app/chain/scraping.py index d2f1e7310..6c6611f30 100644 --- a/app/chain/scraping.py +++ b/app/chain/scraping.py @@ -16,7 +16,7 @@ from threading import Lock from typing import Any, Iterable, List, Optional, Protocol, Self, Tuple, Union, cast from urllib.parse import urlsplit -from app.application.audio import AudioMetadataHelper +from app.application.audio import AudioMetadataHelper, music_cue_enabled from app.application.configuration import ( get_chain_runtime_config_snapshot, get_configured_system_config, @@ -35,7 +35,12 @@ from app.domain.context import ( from app.domain.meta.metabase import MetaBase from app.domain.meta.metamusic import MetaMusic from app.domain.metainfo import MetaInfo, MetaInfoPath -from app.domain.music import music_cover_priority +from app.domain.music import ( + align_music_tracks, + music_album_has_consistent_tracks, + music_cover_priority, + music_isrc_conflicts, +) from app.foundation.singleton import Singleton from app.foundation.text import convert from app.runtime.cache import cached @@ -206,10 +211,12 @@ class _MusicScrapeFileResult: :param metadata_success: 当前文件标签刮削是否成功,未发生标签写入错误时默认 True :param lyrics_status: 歌词处理状态:disabled 表示未启用,saved 为新增,upgraded 为升级,existing 为已存在, protected 为防降级保留,missing 为未匹配,budget_exceeded 为预算耗尽,failed 为失败 + :param album_track_matched: 专辑标签写入时是否采用可靠匹配的曲目;未写入标签或写入失败时为 None """ metadata_success: bool = True lyrics_status: str = "disabled" + album_track_matched: Optional[bool] = None class ScrapingOption: @@ -392,6 +399,8 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton): } MUSIC_LEGACY_LYRICS_EXTENSIONS = (".lyricsfile.yaml", ".txt") + # 与音频元数据读取器对同目录 CUE 的数量上限保持一致 + MUSIC_MAX_CUE_FILES = 32 IMAGE_EXTENSIONS = frozenset({".jpg", ".jpeg", ".png", ".webp"}) _music_track_prefix_pattern = re.compile( r"^\s*(?:(?:cd|disc)\s*\d+\s*[-_. ]+)?(?:\d+\s*[-_. ]+)+", @@ -1496,8 +1505,16 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton): 音乐识别由 MediaChain 提供,标签、封面和歌词写入仅由当前刮削链编排。 - :param audio_files: 已确认属于本批次的音频文件;为空时按 fileitem 展开 + 音乐标签设为覆盖时,只有可靠对位的专辑曲目才可替换本地曲目字段; + 手动覆盖允许以唯一曲序纠正曲名,自动刮削继续使用严格证据。 + + :param fileitem: 待刮削的音频文件或目录 + :param mediainfo: 用户或识别流程指定的音乐身份 + :param overwrite: 是否按手动覆盖语义处理已有产物 + :param media_source: 未指定身份时用于识别音频的来源 + :param audio_files: 已确认属于本批次的音频文件;为 None 时按 fileitem 展开 :param media_by_path: 每个音频文件对应的音乐身份,避免批次内不同单曲互相覆盖 + :return: 刮削是否成功及标签、歌词的处理说明 """ files = self._normalize_music_audio_fileitems( audio_files if audio_files is not None else self._music_audio_fileitems(fileitem) @@ -1535,9 +1552,13 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton): deadline=time.monotonic() + max(self.runtime_config.lyrics_batch_timeout, 0) ) cover_cache: dict[str, tuple[Optional[bytes], str]] = {} - album_cache: dict[tuple[str, str], Optional[MusicAlbumInfo]] = {} + album_cache: dict[tuple[MediaSource, str, Optional[str]], Optional[MusicAlbumInfo]] = {} + album_tracks = self._plan_music_album_tracks( + files, file_media, album_cache, allow_title_override=overwrite, + ) if nfo_option.is_overwrite and not nfo_option.is_skip else {} failures: list[str] = [] + track_counts = {True: 0, False: 0} lyrics_counts = { "saved": 0, "existing": 0, @@ -1559,20 +1580,7 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton): if cover_url not in cover_cache: cover_cache[cover_url] = self._download_music_cover(cover_url) item_cover = cover_cache[cover_url] - album_info = None - if ( - item_media - and item_media.music_type == MUSIC_ENTITY_ALBUM - and item_media.media_source - and item_media.media_id - ): - album_key = (item_media.media_source, item_media.media_id) - if album_key not in album_cache: - album_cache[album_key] = MediaChain().get_music_album( - media_source=item_media.media_source, - media_id=item_media.media_id, - ) - album_info = album_cache[album_key] + album_info = self._music_scrape_album(item_media, album_cache) result = self._scrape_music_file( audio_item, item_media, @@ -1586,6 +1594,7 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton): lyrics_chain=lyrics_chain, album_info=album_info, media_source=media_source, + album_track=album_tracks.get(self._music_file_key(audio_item)), ) if not result.metadata_success: failures.append( @@ -1595,8 +1604,14 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton): lyrics_counts[result.lyrics_status] += 1 if result.lyrics_status == "failed": failures.append(f"{audio_item.name or audio_item.path} 歌词保存失败") + if result.album_track_matched is not None: + track_counts[result.album_track_matched] += 1 message = f"已刮削 {len(files)} 个音频文件" + track_summary = self._music_album_track_summary(track_counts, nfo_option.is_overwrite) + if track_summary: + message += f",{track_summary}" + logger.info(f"音乐专辑刮削:{track_summary}") if not lyrics_option.is_skip: message += ( f",歌词新增 {lyrics_counts['saved']} 首" @@ -1613,6 +1628,203 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton): return False, f"{message};{';'.join(failures[:3])}" return True, message + @staticmethod + def _music_album_track_summary(counts: dict[bool, int], overwrite: bool) -> str: + """ + 说明已对位和保留的曲目,避免把专辑字段更新误认为曲目标签已覆盖。 + """ + matched, preserved = counts[True], counts[False] + if not matched and not preserved: + return "" + if not overwrite: + return f"{preserved} 个文件保留已有曲名、艺人和曲序;音乐标签设为覆盖可尝试更新" + if preserved: + return f"曲目匹配 {matched} 个,{preserved} 个文件未可靠匹配,保留已有曲名、艺人和曲序" + return f"曲目匹配 {matched} 个" + + @staticmethod + def _music_album_key(info: Optional[MusicInfo]) -> Optional[tuple[MediaSource, str, Optional[str]]]: + """ + 区分专辑来源、发行组和明确选择的 MusicBrainz 发行版本。 + """ + if not info or info.music_type != MUSIC_ENTITY_ALBUM or not info.media_source or not info.media_id: + return None + release_id = ( + info.musicbrainz_release_id.lower() + if info.media_source == MediaSource.MusicBrainz and info.musicbrainz_release_id + else None + ) + return info.media_source, info.media_id, release_id + + def _music_scrape_album( + self, + info: Optional[MusicInfo], + cache: dict[tuple[MediaSource, str, Optional[str]], Optional[MusicAlbumInfo]], + ) -> Optional[MusicAlbumInfo]: + """ + 获取并复用专辑曲目;显式发行版本不能被默认代表版本替换。 + """ + key = self._music_album_key(info) + if key is None: + return None + if key not in cache: + source, media_id, release_id = key + kwargs: dict[str, Any] = {"media_source": source, "media_id": media_id} + if release_id: + kwargs["musicbrainz_release_id"] = release_id + cache[key] = MediaChain().get_music_album(**kwargs) + return cache[key] + + @staticmethod + def _music_file_key(item: _SchemaFileItem) -> tuple[str, str]: + """ + 用存储和规范路径区分批次内的音频文件。 + """ + return item.storage or "local", Path(item.path or "").as_posix() + + @staticmethod + def _remote_music_copy_matches(item: _SchemaFileItem, path: Path, directory: Path) -> bool: + """ + 远端音轨必须以原文件名下载到指定目录,CUE 才能按原引用定位它。 + """ + return bool( + item.path and path.name == Path(item.path).name and path.parent.resolve() == directory.resolve() + ) + + def _read_music_track_evidence(self, item: _SchemaFileItem) -> Optional[MetaMusic]: + """ + 只读取得对位证据;远端副本逐个释放,避免把整张专辑常驻临时目录。 + """ + if item.storage == "local": + path = self.storagechain.download_file(item) + return AudioMetadataHelper.read(path) if path else None + with TemporaryDirectory(prefix="moviepilot-music-align-") as directory: + path = self.storagechain.download_file(item, path=Path(directory)) + if not path or not self._remote_music_copy_matches(item, path, Path(directory)): + return None + if not self._stage_remote_music_cues(item, Path(directory)): + return None + return AudioMetadataHelper.read(path) + + def _stage_remote_music_cues(self, item: _SchemaFileItem, directory: Path) -> bool: + """ + 将远端同目录 CUE 带到临时副本旁;目录或索引不可读取时不猜测曲目。 + """ + if not music_cue_enabled(): + return True + parent = self.storagechain.get_parent_item(item) + if not parent: + return False + siblings = self.storagechain.list_files(parent, recursion=False) + if siblings is None or not any( + sibling.type == "file" and self._music_file_key(sibling) == self._music_file_key(item) + for sibling in siblings + ): + # 普通目录列表可能把失败当成空列表;至少要能确认当前音轨在返回结果中。 + return False + cues = [ + sibling for sibling in siblings + if sibling.type == "file" + and (name := Path(sibling.path or sibling.name or "")).suffix.casefold() == ".cue" + and not name.name.startswith(".") + ] + if len(cues) > self.MUSIC_MAX_CUE_FILES: + return False + for sibling in cues: + cue = self.storagechain.download_file(sibling, path=directory) + if ( + not cue or cue.name != Path(sibling.path or "").name + or cue.suffix.casefold() != ".cue" or cue.parent.resolve() != directory.resolve() + ): + return False + return True + + @staticmethod + def _music_track_evidence_unchanged(expected: MetaMusic, current: MetaMusic) -> bool: + """ + 写入前复核对位所用的标签和 CUE 证据,避免使用过期匹配覆盖新内容。 + """ + fields = ( + "title", "artists", "track_number", "disc_number", "duration", "version", "isrc", + "media_source", "media_id", "music_type", "musicbrainz_release_id", + "musicbrainz_release_group_id", "musicbrainz_release_track_id", + "composers", "conductors", "orchestras", "performers", + "music_layout", "cue_tracks", "organization_error", + ) + return all(getattr(expected, key) == getattr(current, key) for key in fields) and all( + expected.field_sources.get(key) == current.field_sources.get(key) + for key in ("title", "artists") + ) + + @staticmethod + def _music_track_identity_conflicts(local: MetaMusic, track: MusicInfo) -> bool: + """ + 手动纠正曲名也不能忽略明确不同的录音、发行身份或 ISRC。 + """ + local_id, track_id = local.media_id, track.media_id + if local.media_source == track.media_source == MediaSource.MusicBrainz: + local_id = local_id.lower() if local_id else None + track_id = track_id.lower() if track_id else None + return bool( + music_isrc_conflicts(track, local) + or ( + local_id and track_id and local.media_source == track.media_source and local_id != track_id + ) + or any( + getattr(local, key) and getattr(track, key) + and getattr(local, key).lower() != getattr(track, key).lower() + for key in ("musicbrainz_release_id", "musicbrainz_release_group_id", "musicbrainz_release_track_id") + ) + ) + + def _plan_music_album_tracks( + self, + files: list[_SchemaFileItem], + file_media: list[Optional[MusicInfo]], + cache: dict[tuple[MediaSource, str, Optional[str]], Optional[MusicAlbumInfo]], + *, + allow_title_override: bool, + ) -> dict[tuple[str, str], tuple[MetaMusic, MusicInfo]]: + """ + 为每张专辑按整批双向唯一证据对位,拒绝整轨 CUE 和身份冲突。 + + 远端音频在对位与实际写入时分别下载,写入前重新核对证据; + 不依赖文件排序或把尚未匹配的剩余文件强行分配给曲目。 + """ + groups: dict[tuple[MediaSource, str, Optional[str]], list[_SchemaFileItem]] = {} + infos: dict[tuple[MediaSource, str, Optional[str]], MusicInfo] = {} + for item, info in zip(files, file_media): + key = self._music_album_key(info) + if key is not None and info is not None: + groups.setdefault(key, []).append(item) + infos[key] = info + + planned: dict[tuple[str, str], tuple[MetaMusic, MusicInfo]] = {} + for key, items in groups.items(): + album = self._music_scrape_album(infos[key], cache) + if not album or not album.tracks or not music_album_has_consistent_tracks(album): + continue + if album.media_source != key[0] or album.media_id != key[1] or (key[2] and album.musicbrainz_release_id != key[2]): + continue + tracks = [track for track in album.tracks if track.music_type == MUSIC_ENTITY_RECORDING] + evidence = [(item, self._read_music_track_evidence(item)) for item in items] + eligible = [ + (item, meta) for item, meta in evidence + if meta is not None and meta.music_layout != "image_cue" and not meta.organization_error + ] + if len(eligible) != len(items): + # 不完整的本地证据无法证明整批文件与线上曲目之间的双向唯一性。 + continue + aligned = align_music_tracks( + [meta for _, meta in eligible], tracks, allow_title_override=allow_title_override, + ) + for index, remote in aligned.items(): + item, meta = eligible[index] + track = tracks[remote] + if not self._music_track_identity_conflicts(meta, track): + planned[self._music_file_key(item)] = meta, deepcopy(track) + return planned + @staticmethod def _music_scrape_identity( info: MusicInfo, @@ -1768,6 +1980,7 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton): lyrics_chain: Optional[LyricsChain] = None, album_info: Optional[MusicAlbumInfo] = None, media_source: Optional[MediaSource] = None, + album_track: Optional[tuple[MetaMusic, MusicInfo]] = None, ) -> _MusicScrapeFileResult: """ 下载单个音轨并执行标签、封面和歌词刮削,远端产物写回原目录。 @@ -1799,12 +2012,18 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton): lyrics_chain=lyrics_chain, album_info=album_info, media_source=media_source, + album_track=album_track, ) with TemporaryDirectory(prefix="moviepilot-music-scrape-") as temp_dir: local_path = storage.download_file(fileitem, path=Path(temp_dir)) if not local_path: return download_failure + if album_track and ( + not self._remote_music_copy_matches(fileitem, local_path, Path(temp_dir)) + or not self._stage_remote_music_cues(fileitem, Path(temp_dir)) + ): + album_track = None return self._apply_music_file_scrape( fileitem=fileitem, local_path=local_path, @@ -1819,6 +2038,7 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton): lyrics_chain=lyrics_chain, album_info=album_info, media_source=media_source, + album_track=album_track, ) def _apply_music_file_scrape( @@ -1836,11 +2056,25 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton): lyrics_chain: Optional[LyricsChain], album_info: Optional[MusicAlbumInfo], media_source: Optional[MediaSource], + album_track: Optional[tuple[MetaMusic, MusicInfo]] = None, ) -> _MusicScrapeFileResult: """ 在本地音轨副本上执行刮削,并将变更后的音频和歌词写回目标存储。 """ - scrape_info = self._resolve_music_scrape_info(local_path, mediainfo, media_source=media_source) + album_track_matched = None + scrape_info: Optional[Union[MetaMusic, MusicInfo]] + if write_tags and mediainfo and mediainfo.music_type == MUSIC_ENTITY_ALBUM: + local_meta = AudioMetadataHelper.read(local_path) + track = ( + album_track[1] + if album_track and self._music_track_evidence_unchanged(album_track[0], local_meta) + else None + ) + album_track_matched = track is not None + self._preserve_music_image_tags(local_path, local_meta) + scrape_info = self._merge_music_album_metadata(local_meta, mediainfo, track) + else: + scrape_info = self._resolve_music_scrape_info(local_path, mediainfo, media_source=media_source) if with_cover: if cover is None: cover_url = getattr(mediainfo, "cover_url", None) or getattr(scrape_info, "cover_url", None) @@ -1886,14 +2120,43 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton): return _MusicScrapeFileResult( metadata_success=metadata_success, lyrics_status=lyrics_status, + album_track_matched=album_track_matched if metadata_success else None, ) @staticmethod - def _merge_music_album_metadata(local_meta: MetaMusic, album: MusicInfo) -> MetaMusic: + def _preserve_music_image_tags(path: Path, meta: MetaMusic) -> None: """ - 把专辑级字段合并到单个音轨标签,同时保留该文件自己的标题、艺术家和曲序。 + 整轨 CUE 的识别结果使用专辑标题,但已有音频标签仍须按保留策略留存。 + + :param path: 已下载的音频路径 + :param meta: 可原地调整的 CUE 合并元数据 + """ + if meta.music_layout != "image_cue": + return + tags = AudioMetadataHelper.read_tags(path) + if not tags: + return + meta.title = tags.title or meta.title + meta.artists = list(tags.artists or meta.artists) + meta.track_number = tags.track_number + + @staticmethod + def _merge_music_album_metadata( + local_meta: MetaMusic, + album: MusicInfo, + track: Optional[MusicInfo] = None, + ) -> MetaMusic: + """ + 把专辑级字段合并到音轨;仅在曲目已可靠对位时采用非空的线上曲目字段。 + 单碟专辑除外:线上碟数已确认为 1 时碟号必为 1,本地错标的碟号不能 - 再与 total_discs=1 配成 "2/1" 写进标签。 + 再与 total_discs=1 配成 "2/1" 写进标签。音轨身份仍使用本地录音 ID, + 不能用专辑 ID 补位。 + + :param local_meta: 当前音频读取的标签与路径证据 + :param album: 需要合并的专辑信息 + :param track: 已可靠对位的专辑曲目;为 None 时保留本地曲目字段 + :return: 不修改输入对象的合并结果 """ merged = deepcopy(local_meta) merged.artists = list(local_meta.artists or album.artists) @@ -1904,6 +2167,13 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton): merged.total_discs = album.total_discs or local_meta.total_discs if album.total_discs == 1: merged.disc_number = 1 + if track: + merged.title = track.title or merged.title + merged.artists = list(track.artists or merged.artists) + merged.track_number = track.track_number or merged.track_number + merged.total_tracks = track.total_tracks or merged.total_tracks + if album.total_discs != 1: + merged.disc_number = track.disc_number or merged.disc_number # MetaMusic 的身份代表音轨;保留已有单曲 ID,不能用专辑 ID 补位, # 否则会误写 musicbrainz_trackid,使下次拿 release-group 查询 recording。 return merged diff --git a/docs/mcp-api.md b/docs/mcp-api.md index 4204ebf23..fd89f748f 100644 --- a/docs/mcp-api.md +++ b/docs/mcp-api.md @@ -594,6 +594,8 @@ Emby、Jellyfin、Plex、Navidrome 的目录、条目、搜索、季集和活动 `media.scrape` 遇到不支持的媒体文件或 NFO 保存失败时返回 `success: false` 及原因,目录中的媒体保存失败也会向上传递。不要将这种响应报告为刮削完成。 +音乐专辑刮削默认保留已有曲名、艺人和曲序,响应 `message` 与日志会说明。需要尝试更新时,可在系统刮削设置中将“音乐标签”设为“覆盖”:只有与专辑曲目双向唯一对位、且录音身份和时长没有冲突的文件才会采用来源提供的曲目字段;未可靠匹配的文件继续保留本地字段。手动刮削可按唯一曲序纠正曲名,自动刮削使用更严格的证据;启用 CUE 读取时,整轨 CUE 不会被当作单曲覆盖。结果中的匹配数量不等同于实际发生变化的标签数量。远端音轨在对位和写入阶段分别下载;启用 CUE 读取时,目录未列出当前音轨或索引下载失败会保留曲目字段。普通远端存储列表不保证返回全部子项,使用此类存储前应核对 CUE 或通过本地挂载操作。 + ### 分页与截断 - 按选定操作的合同使用分页字段。例如 `subscription.list` 使用 `page` / `count`,`subscription.execution.list` 使用 `limit`,原生服务列表常用 `offset` / `limit`。 diff --git a/skills/moviepilot-api/SKILL.md b/skills/moviepilot-api/SKILL.md index 12ca5f2e7..62c2d591d 100644 --- a/skills/moviepilot-api/SKILL.md +++ b/skills/moviepilot-api/SKILL.md @@ -374,8 +374,11 @@ token exchange downloads retain their existing credential rules. - Treat `success=false`, HTTP error data, empty results, and validation errors as real outcomes. Do not claim success without checking the response. - `media.scrape` reports rejected media and failed NFO writes as business failures, - including failures within a directory. For concurrent custom-filter changes, - re-read the rules and confirm the intended change before retrying a conflict. + including failures within a directory. For music albums, report its `message`: + track titles, artists and numbers are retained by default; the music tag + overwrite policy only updates reliably aligned tracks. An aligned count does + not prove every tag changed. For concurrent custom-filter changes, re-read + the rules and confirm the intended change before retrying a conflict. - Respect an explicit `execution_outcome`: `pending` is accepted but unfinished, `unknown` means a write may have happened, and `replayed` means this call did not execute; `previous_status` describes the earlier receipt. Do not repeat an diff --git a/skills/organize-files/SKILL.md b/skills/organize-files/SKILL.md index 7cbf5428c..4efc41b92 100644 --- a/skills/organize-files/SKILL.md +++ b/skills/organize-files/SKILL.md @@ -40,8 +40,9 @@ recognition, transfer, and history tools are not available. 7. Call `transfer.file` once per verified unit. For an album, transfer the album directory once only after its supported audio-file count is consistent with the selected album detail. -8. If requested, call `media.scrape` after a successful transfer. Report actual - tag, cover, and lyrics counts; never assume all lyrics were found. +8. If requested, call `media.scrape` after a successful transfer. Report its + actual message, including any preserved album track fields and lyrics counts; + never assume all tracks were overwritten or all lyrics were found. ## Structured Calls diff --git a/tests/test_music_album_scrape_overwrite.py b/tests/test_music_album_scrape_overwrite.py new file mode 100644 index 000000000..59d0e34c6 --- /dev/null +++ b/tests/test_music_album_scrape_overwrite.py @@ -0,0 +1,782 @@ +""" +验证专辑刮削对曲目标签的覆盖策略、对位保护和结果提示。 +""" + +import os +import shutil +from pathlib import Path +from types import SimpleNamespace +from typing import Optional +from unittest.mock import Mock + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient +from mutagen.flac import FLAC + +from app.api.dependencies.auth import get_current_active_user +from app.api.endpoints import media as media_endpoint +from app.application.audio import AudioMetadataHelper, use_music_cue +from app.chain.scraping import ScrapingChain, ScrapingConfig +from app.domain.context import MusicAlbumInfo, MusicInfo +from app.schemas.file import FileItem +from app.schemas.types import MediaSource + +_GROUP = "25aa1b18-5e85-43c2-94c4-4b07ad96268a" +_RECORDINGS = ( + "38035858-f990-4fbb-b3b2-f2f8b958eeba", + "f4f1b7b2-22b0-4ce0-9ac6-31c336c52812", +) +_OTHER_RECORDING = "70b71113-b078-4f07-9d24-374482016a41" + + +def _album() -> MusicAlbumInfo: + """ + 构造包含两首不同曲目和独立录音身份的专辑。 + """ + return MusicAlbumInfo( + media_source=MediaSource.MusicBrainz, + media_id=_GROUP, + musicbrainz_release_group_id=_GROUP, + title="正确专辑", + artists=["专辑歌手"], + total_discs=1, + tracks=[ + MusicInfo( + media_source=MediaSource.MusicBrainz, + media_id=recording_id, + album_id=_GROUP, + musicbrainz_release_group_id=_GROUP, + title=title, + artists=[artist], + disc_number=1, + track_number=number, + total_tracks=2, + ) + for number, (recording_id, title, artist) in enumerate( + zip(_RECORDINGS, ("正确一", "正确二"), ("线上歌手一", "线上歌手二")), + start=1, + ) + ], + ) + + +def _audio(path: Path, title: str, artist: str, track: int, recording_id: str = "") -> Path: + """ + 创建真实 FLAC 文件并写入待修正的本地标签。 + """ + path.parent.mkdir(parents=True, exist_ok=True) + shutil.copyfile(Path(__file__).parent / "fixtures/audio/silence.flac", path) + tags = FLAC(path) + tags["title"] = [title] + tags["artist"] = [artist] + tags["album"] = ["旧专辑"] + tags["tracknumber"] = [str(track)] + tags["discnumber"] = ["1"] + if recording_id: + tags["musicbrainz_trackid"] = [recording_id] + tags.save() + return path + + +def _item(path: Path, storage: str = "local") -> FileItem: + """ + 将测试音频路径转换为刮削链使用的文件项。 + """ + return FileItem(storage=storage, path=path.as_posix(), type="file", name=path.name) + + +def _chain(monkeypatch: pytest.MonkeyPatch, album: MusicAlbumInfo, policy: str) -> ScrapingChain: + """ + 构造隔离的刮削链,专辑详情使用离线替身,封面和歌词关闭。 + """ + chain = object.__new__(ScrapingChain) + chain.storagechain = Mock() + chain.storagechain.download_file.side_effect = lambda item, **_kwargs: Path(item.path) + chain.scraping_policies = ScrapingConfig({ + "music_nfo": policy, + "music_poster": "skip", + "music_lyrics": "skip", + }) + media_chain = Mock() + media_chain.get_music_album.return_value = album + monkeypatch.setattr("app.chain.scraping.MediaChain", lambda: media_chain) + return chain + + +def _scrape(chain: ScrapingChain, album: MusicAlbumInfo, files: list[FileItem], *, overwrite: bool = True): + """ + 按指定专辑刮削测试文件,保持文件顺序由调用方决定。 + """ + return chain.scrape_music_metadata( + fileitem=FileItem(storage=files[0].storage, path="/music/album", type="dir"), + mediainfo=album.to_music_info(), + audio_files=files, + overwrite=overwrite, + ) + + +def _remote_storage(chain: ScrapingChain, audio: Path, cue: Optional[Path] = None): + """ + 用临时文件模拟远端目录、逐次下载和上传,不访问真实存储服务。 + """ + audio_item = _item(Path("/music/album") / audio.name, "u115") + cue_item = _item(Path("/music/album") / cue.name, "u115") if cue else None + contents = {audio_item.path: audio} + if cue_item: + contents[cue_item.path] = cue + storage = Mock() + storage.get_parent_item.return_value = FileItem(storage="u115", path="/music/album", type="dir") + storage.list_files.return_value = [audio_item, *([cue_item] if cue_item else [])] + + def download(item, path=None): + """ + 把远端测试文件复制到每次调用自己的临时目录。 + """ + target = path / item.name + shutil.copyfile(contents[item.path], target) + return target + + def upload(_parent, path, new_name=None): + """ + 模拟上传更新后的音频,不修改同目录 CUE。 + """ + assert new_name == audio.name + shutil.copyfile(path, audio) + return audio_item + + storage.download_file.side_effect = download + storage.upload_file.side_effect = upload + chain.storagechain = storage + return audio_item, cue_item, storage + + +def test_missing_only_preserves_track_tags_and_explains_how_to_overwrite(tmp_path, monkeypatch): + """ + 手动刮削也保留仅缺失策略下的本地曲目字段,并告知可切换音乐标签策略。 + """ + album = _album() + path = _audio(tmp_path / "01.flac", "旧拼接标题", "本地歌手", 1) + chain = _chain(monkeypatch, album, "missingOnly") + + success, message = _scrape(chain, album, [_item(path)]) + + result = AudioMetadataHelper.read_tags(path) + assert success + assert (result.title, result.artists, result.track_number) == ("旧拼接标题", ["本地歌手"], 1) + assert result.album == "正确专辑" + assert "保留" in message and "曲名" in message and "艺人" in message and "曲序" in message + assert "音乐标签" in message and "覆盖" in message + + +def test_overwrite_aligns_each_track_and_preserves_linked_source(tmp_path, monkeypatch): + """ + 覆盖策略按整批唯一证据纠正曲名、艺人和错序,同时不修改硬链接源文件。 + """ + album = _album() + seeds = [ + _audio(tmp_path / "seed" / "first.flac", "旧拼接标题", "本地一", 1), + _audio(tmp_path / "seed" / "second.flac", "正确二", "本地二", 1), + ] + library = tmp_path / "library" + library.mkdir() + files = [library / f"{number}.flac" for number in (1, 2)] + for seed, target in zip(seeds, files): + os.link(seed, target) + before = [seed.read_bytes() for seed in seeds] + chain = _chain(monkeypatch, album, "overwrite") + + success, message = _scrape(chain, album, [_item(path) for path in files]) + + assert success + assert "匹配 2" in message + for index, (seed, target) in enumerate(zip(seeds, files)): + result = AudioMetadataHelper.read_tags(target) + track = album.tracks[index] + assert (result.title, result.artists, result.track_number) == (track.title, track.artists, track.track_number) + assert result.album == "正确专辑" + assert result.media_id is None + assert seed.read_bytes() == before[index] + assert not os.path.samefile(seed, target) + + +def test_overwrite_preserves_duplicate_and_ambiguous_local_tracks(tmp_path, monkeypatch): + """ + 两个文件争用相同曲目时不得按遍历顺序决定谁被覆盖。 + """ + album = _album() + paths = [_audio(tmp_path / f"{number}.flac", "未知旧标题", "本地歌手", 1) for number in (1, 2)] + chain = _chain(monkeypatch, album, "overwrite") + + success, message = _scrape(chain, album, [_item(path) for path in paths]) + + assert success + assert "未可靠匹配" in message and "保留" in message + assert all(AudioMetadataHelper.read_tags(path).title == "未知旧标题" for path in paths) + assert all(AudioMetadataHelper.read_tags(path).track_number == 1 for path in paths) + + +def test_overwrite_preserves_conflicting_recording_identity(tmp_path, monkeypatch): + """ + 不同录音 ID 不能仅凭相同曲序被改成另一首歌,也不能污染原身份。 + """ + album = _album() + path = _audio(tmp_path / "01.flac", "旧标题", "本地歌手", 1, _OTHER_RECORDING) + chain = _chain(monkeypatch, album, "overwrite") + + success, message = _scrape(chain, album, [_item(path)]) + + result = AudioMetadataHelper.read_tags(path) + assert success + assert "未可靠匹配" in message and "保留" in message + assert (result.title, result.artists, result.media_id) == ("旧标题", ["本地歌手"], _OTHER_RECORDING) + + +def test_overwrite_preserves_track_on_duration_conflict(tmp_path, monkeypatch): + """ + 本地时长与线上曲目显著冲突时,即使曲序相同也不覆盖标题。 + """ + album = _album() + album.tracks[0].duration = 300 + path = _audio(tmp_path / "01.flac", "旧标题", "本地歌手", 1) + chain = _chain(monkeypatch, album, "overwrite") + + success, message = _scrape(chain, album, [_item(path)]) + + assert success + assert "未可靠匹配" in message + assert AudioMetadataHelper.read_tags(path).title == "旧标题" + + +def test_automatic_overwrite_does_not_guess_from_position_alone(tmp_path, monkeypatch): + """ + 自动刮削即使启用覆盖,也不能把手动选择专辑时的曲名纠正放宽到普通自动识别。 + """ + album = _album() + path = _audio(tmp_path / "01.flac", "本地不同曲名", "本地歌手", 1) + chain = _chain(monkeypatch, album, "overwrite") + + success, message = _scrape(chain, album, [_item(path)], overwrite=False) + + assert success + assert "未可靠匹配" in message + assert AudioMetadataHelper.read_tags(path).title == "本地不同曲名" + + +def test_automatic_overwrite_corrects_position_with_strict_title_evidence(tmp_path, monkeypatch): + """ + 自动刮削在曲名和艺人有严格证据时,覆盖策略仍可修正错标曲序。 + """ + album = _album() + path = _audio(tmp_path / "01.flac", "正确一", "线上歌手一", 2) + chain = _chain(monkeypatch, album, "overwrite") + + success, message = _scrape(chain, album, [_item(path)], overwrite=False) + + assert success and "匹配 1" in message + assert AudioMetadataHelper.read_tags(path).track_number == 1 + + +def test_partial_track_matches_report_both_updated_and_preserved_files(tmp_path, monkeypatch): + """ + 一个曲目成功对位、另一个录音身份冲突时,应分别报告匹配与保留数量。 + """ + album = _album() + first = _audio(tmp_path / "01.flac", "旧一", "本地一", 1) + second = _audio(tmp_path / "02.flac", "旧二", "本地二", 2, _OTHER_RECORDING) + chain = _chain(monkeypatch, album, "overwrite") + + success, message = _scrape(chain, album, [_item(first), _item(second)]) + + assert success and "曲目匹配 1 个" in message and "1 个文件未可靠匹配" in message + assert AudioMetadataHelper.read_tags(first).title == "正确一" + assert AudioMetadataHelper.read_tags(second).title == "旧二" + + +def test_matched_track_with_missing_fields_keeps_local_values(tmp_path, monkeypatch): + """ + 线上曲目缺少标题或艺人时不能用空值清除本地标签。 + """ + album = _album() + album.tracks[0].title = None + album.tracks[0].artists = [] + path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1) + chain = _chain(monkeypatch, album, "overwrite") + + success, message = _scrape(chain, album, [_item(path)]) + + result = AudioMetadataHelper.read_tags(path) + assert success and "匹配 1" in message + assert (result.title, result.artists) == ("本地标题", ["本地歌手"]) + + +def test_overwrite_rechecks_metadata_before_writing(tmp_path, monkeypatch): + """ + 对位后用户修改了音轨证据时,不能按过期快照覆盖新标签。 + """ + album = _album() + path = _audio(tmp_path / "01.flac", "旧标题", "本地歌手", 1) + chain = _chain(monkeypatch, album, "overwrite") + downloads = [] + + def download(item, **_kwargs): + """ + 在计划读取后模拟用户修改标签,再交还同一个本地文件。 + """ + downloads.append(item.path) + if len(downloads) == 2: + tags = FLAC(path) + tags["title"] = ["用户新标题"] + tags.save() + return path + + chain.storagechain.download_file.side_effect = download + success, message = _scrape(chain, album, [_item(path)]) + + assert success + assert "未可靠匹配" in message + assert AudioMetadataHelper.read_tags(path).title == "用户新标题" + + +def test_incomplete_batch_evidence_cannot_authorize_other_track_overwrites(tmp_path, monkeypatch): + """ + 一个文件无法读取时,剩余文件不能声称已在整个批次中唯一对位。 + """ + album = _album() + paths = [_audio(tmp_path / f"{number}.flac", "旧标题", "本地歌手", 1) for number in (1, 2)] + chain = _chain(monkeypatch, album, "overwrite") + calls = [] + + def download(item, **_kwargs): + """ + 仅让计划阶段的第二个文件读取失败,后续写入阶段仍可访问。 + """ + calls.append(item.path) + return None if len(calls) == 2 else Path(item.path) + + chain.storagechain.download_file.side_effect = download + success, message = _scrape(chain, album, [_item(path) for path in paths]) + + assert success and "未可靠匹配" in message + assert all(AudioMetadataHelper.read_tags(path).title == "旧标题" for path in paths) + + +def test_overwrite_applies_simplified_track_text_supplied_by_source(tmp_path, monkeypatch): + """ + 专辑曲目已按系统设置转为简体时,覆盖应实际写入曲名和艺人。 + """ + album = _album() + album.tracks[0].title = "后来" + album.tracks[0].artists = ["优里"] + path = _audio(tmp_path / "01.flac", "後來", "優里", 1) + chain = _chain(monkeypatch, album, "overwrite") + + success, message = _scrape(chain, album, [_item(path)]) + + result = AudioMetadataHelper.read_tags(path) + assert success and "匹配 1" in message + assert (result.title, result.artists) == ("后来", ["优里"]) + + +def test_overwrite_preserves_track_if_album_details_are_unavailable(tmp_path, monkeypatch): + """ + 专辑详情无曲目时仍可刮削专辑字段,但必须报告保留本地曲目。 + """ + album = _album() + path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1) + chain = _chain(monkeypatch, album, "overwrite") + provider = Mock() + provider.get_music_album.return_value = None + monkeypatch.setattr("app.chain.scraping.MediaChain", lambda: provider) + + success, message = _scrape(chain, album, [_item(path)]) + + result = AudioMetadataHelper.read_tags(path) + assert success and "未可靠匹配" in message and "保留" in message + assert (result.title, result.artists, result.album) == ("本地标题", ["本地歌手"], "正确专辑") + + +def test_overwrite_rejects_conflicting_isrc(tmp_path, monkeypatch): + """ + 两个有效 ISRC 明确不同时,不能用匹配曲序覆盖另一录音的标签。 + """ + album = _album() + album.tracks[0].isrc = "USQX91300105" + path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1) + tags = FLAC(path) + tags["isrc"] = ["USRC17607839"] + tags.save() + chain = _chain(monkeypatch, album, "overwrite") + + success, message = _scrape(chain, album, [_item(path)]) + + result = AudioMetadataHelper.read_tags(path) + assert success and "未可靠匹配" in message + assert (result.title, result.isrc) == ("本地标题", "USRC17607839") + + +def test_overwrite_preserves_conflicting_release_identity(tmp_path, monkeypatch): + """ + 已知具体发行版本冲突时不覆写曲目,以免标签与保留的发行 ID 自相矛盾。 + """ + album = _album() + album.musicbrainz_release_id = _RECORDINGS[1] + for track in album.tracks: + track.musicbrainz_release_id = album.musicbrainz_release_id + path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1) + tags = FLAC(path) + tags["musicbrainz_albumid"] = [_OTHER_RECORDING] + tags.save() + chain = _chain(monkeypatch, album, "overwrite") + + success, message = _scrape(chain, album, [_item(path)]) + + result = AudioMetadataHelper.read_tags(path) + assert success and "未可靠匹配" in message + assert (result.title, result.musicbrainz_release_id) == ("本地标题", _OTHER_RECORDING) + + +def test_overwrite_requests_selected_release_and_rejects_other_release(tmp_path, monkeypatch): + """ + 已选择具体发行时必须传递该 ID,来源返回另一版本时不能套用其曲目。 + """ + album = _album() + requested = album.to_music_info() + requested.musicbrainz_release_id = _OTHER_RECORDING.upper() + album.musicbrainz_release_id = _RECORDINGS[0] + path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1) + chain = _chain(monkeypatch, album, "overwrite") + provider = Mock() + provider.get_music_album.return_value = album + monkeypatch.setattr("app.chain.scraping.MediaChain", lambda: provider) + + success, message = chain.scrape_music_metadata( + fileitem=_item(path), mediainfo=requested, overwrite=True, + ) + + assert success and "未可靠匹配" in message + assert AudioMetadataHelper.read_tags(path).title == "本地标题" + provider.get_music_album.assert_called_once_with( + media_source=MediaSource.MusicBrainz, media_id=_GROUP, musicbrainz_release_id=_OTHER_RECORDING, + ) + + +def test_overwrite_uses_confirmed_selected_release(tmp_path, monkeypatch): + """ + 已确认的具体发行版本按规范化 ID 获取一次并用于曲目覆盖。 + """ + album = _album() + album.musicbrainz_release_id = _OTHER_RECORDING + for track in album.tracks: + track.musicbrainz_release_id = _OTHER_RECORDING + requested = album.to_music_info() + requested.musicbrainz_release_id = _OTHER_RECORDING.upper() + path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1) + chain = _chain(monkeypatch, album, "overwrite") + provider = Mock() + provider.get_music_album.return_value = album + monkeypatch.setattr("app.chain.scraping.MediaChain", lambda: provider) + + success, message = chain.scrape_music_metadata(fileitem=_item(path), mediainfo=requested, overwrite=True) + + assert success and "匹配 1" in message + assert AudioMetadataHelper.read_tags(path).title == "正确一" + provider.get_music_album.assert_called_once_with( + media_source=MediaSource.MusicBrainz, media_id=_GROUP, musicbrainz_release_id=_OTHER_RECORDING, + ) + + +def test_overwrite_does_not_guess_between_discs_without_disc_number(tmp_path, monkeypatch): + """ + 多碟发行中同一曲序重复且本地缺少碟号时不能选第一碟。 + """ + album = _album() + album.total_discs = 2 + album.tracks[1].disc_number = 2 + album.tracks[1].track_number = 1 + path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1) + tags = FLAC(path) + del tags["discnumber"] + tags.save() + chain = _chain(monkeypatch, album, "overwrite") + + success, message = _scrape(chain, album, [_item(path)]) + + assert success and "未可靠匹配" in message + assert AudioMetadataHelper.read_tags(path).title == "本地标题" + + +def test_overwrite_keeps_image_cue_as_album_instead_of_one_track(tmp_path, monkeypatch): + """ + 整轨 CUE 是包含多首歌的物理文件,不能将任意单曲标题写入该文件。 + """ + album = _album() + path = _audio(tmp_path / "image.flac", "本地整轨", "本地歌手", 1) + cue = tmp_path / "album.cue" + cue.write_text( + 'PERFORMER "本地歌手"\nTITLE "整轨专辑"\nFILE "image.flac" WAVE\n' + ' TRACK 01 AUDIO\n TITLE "第一首"\n INDEX 01 00:00:00\n' + ' TRACK 02 AUDIO\n TITLE "第二首"\n INDEX 01 00:01:00\n', + encoding="utf-8", + ) + before = cue.read_bytes() + chain = _chain(monkeypatch, album, "overwrite") + + with use_music_cue(True): + assert AudioMetadataHelper.read(path).music_layout == "image_cue" + success, message = _scrape(chain, album, [_item(path)]) + + result = AudioMetadataHelper.read_tags(path) + assert success and "未可靠匹配" in message + assert (result.title, result.artists, result.track_number) == ("本地整轨", ["本地歌手"], 1) + assert result.media_id is None and cue.read_bytes() == before + + +def test_remote_overwrite_rechecks_and_uploads_real_audio(tmp_path, monkeypatch): + """ + 远端音轨使用隔离副本两次确认后上传,匹配结果和实际标签一致。 + """ + album = _album() + path = _audio(tmp_path / "remote" / "01.flac", "旧标题", "本地歌手", 1) + chain = _chain(monkeypatch, album, "overwrite") + audio_item, _, storage = _remote_storage(chain, path) + + with use_music_cue(True): + success, message = _scrape(chain, album, [audio_item]) + + result = AudioMetadataHelper.read_tags(path) + assert success and "匹配 1" in message + assert (result.title, result.artists) == ("正确一", ["线上歌手一"]) + assert storage.download_file.call_count == 2 + assert storage.list_files.call_count == 2 + storage.upload_file.assert_called_once() + + +def test_remote_image_cue_does_not_receive_a_single_track_title(tmp_path, monkeypatch): + """ + 远端整轨的 CUE 必须参与对位,不能因临时目录只有音频而误认为普通单曲。 + """ + album = _album() + path = _audio(tmp_path / "remote" / "image.flac", "本地整轨", "本地歌手", 1) + cue = path.parent / "album.cue" + cue.write_text( + 'PERFORMER "本地歌手"\nTITLE "整轨专辑"\nFILE "image.flac" WAVE\n' + ' TRACK 01 AUDIO\n TITLE "第一首"\n INDEX 01 00:00:00\n' + ' TRACK 02 AUDIO\n TITLE "第二首"\n INDEX 01 00:01:00\n', + encoding="utf-8", + ) + before = cue.read_bytes() + chain = _chain(monkeypatch, album, "overwrite") + audio_item, _, storage = _remote_storage(chain, path, cue) + + with use_music_cue(True): + success, message = _scrape(chain, album, [audio_item]) + + assert success and "未可靠匹配" in message + assert AudioMetadataHelper.read_tags(path).title == "本地整轨" + assert cue.read_bytes() == before + storage.upload_file.assert_called_once() + + +def test_remote_cue_added_after_planning_invalidates_track_match(tmp_path, monkeypatch): + """ + 对位后出现整轨 CUE 时,写入阶段必须重新读取并取消过期的单曲匹配。 + """ + album = _album() + path = _audio(tmp_path / "remote" / "image.flac", "本地整轨", "本地歌手", 1) + cue = path.parent / "album.cue" + cue.write_text( + 'PERFORMER "本地歌手"\nTITLE "整轨专辑"\nFILE "image.flac" WAVE\n' + ' TRACK 01 AUDIO\n TITLE "第一首"\n INDEX 01 00:00:00\n' + ' TRACK 02 AUDIO\n TITLE "第二首"\n INDEX 01 00:01:00\n', + encoding="utf-8", + ) + chain = _chain(monkeypatch, album, "overwrite") + audio_item, cue_item, storage = _remote_storage(chain, path, cue) + storage.list_files.side_effect = [[audio_item], [audio_item, cue_item]] + + with use_music_cue(True): + success, message = _scrape(chain, album, [audio_item]) + + assert success and "未可靠匹配" in message + assert AudioMetadataHelper.read_tags(path).title == "本地整轨" + assert storage.list_files.call_count == 2 + + +def test_remote_upload_failure_is_not_reported_as_matched(tmp_path, monkeypatch): + """ + 临时音轨完成对位但上传失败时,响应必须报告失败而非声称远端已匹配。 + """ + album = _album() + path = _audio(tmp_path / "remote" / "01.flac", "本地标题", "本地歌手", 1) + before = path.read_bytes() + chain = _chain(monkeypatch, album, "overwrite") + audio_item, _, storage = _remote_storage(chain, path) + storage.upload_file.side_effect = None + storage.upload_file.return_value = None + + with use_music_cue(True): + success, message = _scrape(chain, album, [audio_item]) + + assert not success and "写入失败" in message + assert "曲目匹配" not in message + assert path.read_bytes() == before + + +def test_remote_overwrite_honors_disabled_cue_policy(tmp_path, monkeypatch): + """ + 用户关闭 CUE 读取时,曲目对位不能额外扫描远端目录或下载索引。 + """ + album = _album() + path = _audio(tmp_path / "remote" / "01.flac", "旧标题", "本地歌手", 1) + chain = _chain(monkeypatch, album, "overwrite") + audio_item, _, storage = _remote_storage(chain, path) + storage.list_files.side_effect = AssertionError("CUE 关闭时不得扫描目录") + + with use_music_cue(False): + success, message = _scrape(chain, album, [audio_item]) + + assert success and "匹配 1" in message + assert AudioMetadataHelper.read_tags(path).title == "正确一" + storage.list_files.assert_not_called() + + +def test_remote_directory_with_too_many_cues_is_not_guessed(tmp_path, monkeypatch): + """ + 远端 CUE 数量超过读取器上限时应保留标签,不能下载部分索引后猜测。 + """ + album = _album() + path = _audio(tmp_path / "remote" / "01.flac", "本地标题", "本地歌手", 1) + chain = _chain(monkeypatch, album, "overwrite") + audio_item, _, storage = _remote_storage(chain, path) + storage.list_files.return_value = [ + audio_item, + *[_item(Path(f"/music/album/{number}.cue"), "u115") for number in range(33)], + ] + + with use_music_cue(True): + success, message = _scrape(chain, album, [audio_item]) + + assert success and "未可靠匹配" in message + assert AudioMetadataHelper.read_tags(path).title == "本地标题" + assert all(call.args[0] == audio_item for call in storage.download_file.call_args_list) + + +@pytest.mark.parametrize("failure", ["list", "empty", "missing_audio", "cue"]) +def test_remote_unknown_cue_state_preserves_track_tags(tmp_path, monkeypatch, failure): + """ + 远端目录或 CUE 读取失败时不能假设音轨没有整轨索引。 + """ + album = _album() + path = _audio(tmp_path / "remote" / "01.flac", "本地标题", "本地歌手", 1) + cue = path.parent / "album.cue" + cue.write_text("FILE \"01.flac\" WAVE\n", encoding="utf-8") + chain = _chain(monkeypatch, album, "overwrite") + audio_item, cue_item, storage = _remote_storage(chain, path, cue) + if failure == "list": + storage.list_files.return_value = None + elif failure == "empty": + storage.list_files.return_value = [] + elif failure == "missing_audio": + storage.list_files.return_value = [cue_item] + else: + original_download = storage.download_file.side_effect + storage.download_file.side_effect = lambda item, path=None: ( + None if item == cue_item else original_download(item, path=path) + ) + + with use_music_cue(True): + success, message = _scrape(chain, album, [audio_item]) + + assert success and "未可靠匹配" in message + assert AudioMetadataHelper.read_tags(path).title == "本地标题" + + +def test_remote_renamed_download_does_not_authorize_track_overwrite(tmp_path, monkeypatch): + """ + 音频下载名不等于远端原名时,CUE 无法可靠引用,必须保留已有曲目。 + """ + album = _album() + path = _audio(tmp_path / "remote" / "01.flac", "本地标题", "本地歌手", 1) + chain = _chain(monkeypatch, album, "overwrite") + audio_item, _, storage = _remote_storage(chain, path) + + def download(_item, path=None): + """ + 模拟存储提供方意外更改本地副本文件名。 + """ + target = path / "renamed.flac" + shutil.copyfile(audio_item_path, target) + return target + + audio_item_path = path + storage.download_file.side_effect = download + with use_music_cue(True): + success, message = _scrape(chain, album, [audio_item]) + + assert success and "未可靠匹配" in message + assert AudioMetadataHelper.read_tags(path).title == "本地标题" + + +def test_album_preservation_summary_is_logged(tmp_path, monkeypatch): + """ + 手动调用不仅返回保留提示,也应在刮削日志中留下同样的信息。 + """ + album = _album() + path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1) + chain = _chain(monkeypatch, album, "missingOnly") + logger = Mock() + monkeypatch.setattr("app.chain.scraping.logger", logger) + + success, message = _scrape(chain, album, [_item(path)]) + + assert success and "保留" in message + assert any("保留" in call.args[0] and "音乐标签" in call.args[0] for call in logger.info.call_args_list) + + +def test_album_lyrics_counts_and_track_preservation_are_both_reported(tmp_path, monkeypatch): + """ + 歌词成功数量和专辑曲目保留提示必须同时返回,不能互相覆盖。 + """ + album = _album() + path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1) + chain = _chain(monkeypatch, album, "missingOnly") + chain.scraping_policies = ScrapingConfig({ + "music_nfo": "missingOnly", "music_poster": "skip", "music_lyrics": "upgrade", + }) + chain._scrape_music_lyrics = Mock(return_value="saved") + monkeypatch.setattr("app.chain.scraping.LyricsChain", Mock(return_value=Mock())) + + success, message = _scrape(chain, album, [_item(path)]) + + assert success and "保留已有曲名、艺人和曲序" in message + assert "歌词新增 1 首" in message + + +@pytest.mark.parametrize("policy,expected", [("missingOnly", "保留"), ("overwrite", "匹配 1")]) +def test_music_album_http_response_reports_track_outcome(tmp_path, monkeypatch, policy, expected): + """ + 真实管理权限路由必须把专辑曲目处理说明返回给 REST 调用方。 + """ + album = _album() + path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1) + chain = _chain(monkeypatch, album, policy) + recognizer = Mock() + recognizer.return_value.recognize_media.return_value = album.to_music_info() + monkeypatch.setattr(media_endpoint, "MediaChain", recognizer) + monkeypatch.setattr(media_endpoint, "ScrapingChain", lambda: chain) + app = FastAPI() + app.include_router(media_endpoint.router, prefix="/api/v1/media") + app.dependency_overrides[get_current_active_user] = lambda: SimpleNamespace( + is_active=True, is_superuser=True, permissions={}, + ) + + response = TestClient(app).post( + "/api/v1/media/scrape/local", + params={"media_source": "musicbrainz", "media_id": _GROUP, "type_name": "音乐", "music_type": "album"}, + json=_item(path).model_dump(mode="json"), + ) + + assert response.status_code == 200 + assert response.json()["success"] is True + assert expected in response.json()["message"]