MyTool/开发文档/05-音乐整理.md

05 - 音乐整理

1. 功能概述

• 功能名称：音乐整理
• 后端服务：RenameService + OrganizeService
• 前端组件：RenameTab.vue

主要用途：

• 将已整理好标签的音频文件按 Navidrome 标准目录结构重命名、分组，并生成封面、歌词与整理报告。

2. 目标目录结构规范

• 标准结构示例：
  • 艺术家/专辑(年份)/曲号 - 标题.ext
• 示例：
  • 周杰伦/七里香(2004)/01 - 七里香.flac
  • Adele/21(2011)/01 - Rolling In The Deep.flac

3. A-Z 索引分组策略

• 正常艺术家：
  • 中文艺术家：按拼音首字母分组（如“周杰伦” → Z/周杰伦/...）
  • 英文艺术家：按首字母分组（如“Adele” → A/Adele/...）
• 合辑：
  • 统一归入 Various Artists 目录，不参与 A-Z 分组
• 特殊字符开头：
  • 数字或特殊符号开头的艺术家统一归入 #/ 分组
• 多音字处理：
  • 使用 Pinyin4j 默认取第一个读音，绝大多数场景可以接受

4. 质量隔离机制

• 根据标签完整度对文件进行分层处理：
  • 严格模式：必须同时包含 Title + Artist + Album 才参与整理
  • 宽松模式：只要有 Title 即可参与整理
• 对于缺少必要标签的文件：
  • 自动移动到 _Manual_Fix_Required_/Missing_XXX/ 等目录
  • 便于后续集中使用标签工具（如 MusicBrainz Picard）修复

5. 附加功能

5.1 封面提取

• 从音频文件内嵌封面中提取 cover.jpg 到专辑目录
• 按专辑粒度判断：
  • 只要专辑中任一文件含有封面，即视为该专辑有封面，并提取一次

5.2 歌词提取

• 从音频文件中提取内嵌歌词到 .lrc 文件
• 按单曲粒度判断：
  • 每个文件独立检查是否含有歌词

5.3 整理报告生成

• 整理结束后自动生成报告文件：
  • 文件名：report_YYYYMMDD_HHMMSS.txt
  • 位置：目标目录下 _Reports/ 子目录
• 报告内容包括：
  • 生成时间、扫描文件数
  • 缺失封面的专辑列表
  • 缺失歌词的文件列表
  • 统计摘要（总专辑数、无封面专辑数及百分比、无歌词文件数及百分比）

6. 前端交互流程

1. 用户选择“源目录”（通常是经过汇聚、转码、去重后的 staging 目录）
2. 选择“目标目录”（正式库或 staging 输出目录）
3. 配置：
   • 严格 / 宽松 模式
   • 是否提取封面
   • 是否提取歌词
   • 是否生成报告
4. 执行任务，通过 WebSocket 订阅进度与当前处理文件
5. 整理完成后，可在 _Reports/ 中查看整理报告，对问题文件做二次处理。

7. 建议使用顺序

• 推荐整体流水线：

  1. 01-音频文件汇聚
  2. 02-音频格式智能处理
  3. 03-音乐去重
  4. 04-音乐元数据繁体转简体
  5. 05-音乐整理（本模块）
  6. 06-整理入库

• 这样可以保证进入主库前,目录结构、文件命名、标签内容和资源(封面/歌词)都已基本规范。

8. 测试用例需求

8.1 后端测试

单元测试:

• 测试中文拼音首字母提取的准确性(含多音字)
• 测试英文首字母分组逻辑
• 测试特殊字符处理(数字、符号归入"#"分组)
• 测试合辑识别与 Various Artists 归类
• 测试标签完整度检查(严格/宽松模式)
• 测试目录结构生成:"艺术家/专辑(年份)/曲号 - 标题.ext"
• 测试封面提取逻辑(按专辑粒度)
• 测试歌词提取逻辑(按单曲粒度)
• 测试整理报告生成(缺失封面/歌词统计)

集成测试:

• 准备测试音频文件:
  • 完整标签的文件(中文/英文/日文艺术家)
  • 标签不完整的文件(缺 Title/Artist/Album)
  • 含内嵌封面的文件
  • 含内嵌歌词的文件
  • 合辑文件(AlbumArtist = Various Artists)
• 测试严格模式:缺标签文件移动到 Manual_Fix_Required/
• 测试宽松模式:只要有 Title 即可整理
• 测试 A-Z 分组的正确性
• 验证生成的目录结构符合 Navidrome 规范
• 验证封面与歌词文件的提取与命名
• 验证整理报告的准确性
• 测试异常场景:无效标签、特殊字符、超长文件名

8.2 前端测试

单元测试:

• 测试源目录与目标目录的路径校验
• 测试模式选择(严格/宽松)的状态管理
• 测试功能开关(提取封面/歌词/生成报告)的状态管理
• 测试进度信息的实时更新

集成测试:

• 测试完整的用户操作流程
• 测试整理报告的查看与下载
• 测试不同配置组合的效果

测试数据:

• 小规模场景:50 首歌曲,5 个艺术家,10 个专辑
• 中等规模场景:5000 首歌曲,200 个艺术家,500 个专辑
• 大规模场景:50000+ 首歌曲,测试性能与报告生成
• 边界场景:
  • 中英日混合艺术家
  • 多音字艺术家(如:曲婉婷、单依纯)
  • 特殊字符开头的艺术家
  • 合辑专辑
  • 缺失各种标签的文件
  • 超长文件名与路径

质量验证:

• 验证生成的目录结构在 Navidrome 中的兼容性
• 抽查 A-Z 分组的准确性
• 验证封面图片的完整性与格式
• 验证歌词文件的格式与内容
• 验证整理报告的统计准确性