Remove outdated documentation files for audio processing modules, including development guidelines, audio file aggregation, format conversion, deduplication, metadata conversion, organization, and library integration. This cleanup enhances project maintainability and clarity.

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

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