## 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 分组的准确性
- 验证封面图片的完整性与格式
- 验证歌词文件的格式与内容
- 验证整理报告的统计准确性