Initial setup of project files and directory structure.

02-音频格式智能处理.md

@@ -0,0 +1,103 @@
+## 02 - 音频格式智能处理
+
+### 1. 功能概述
+
+- **功能名称**：音频格式智能处理
+- **后端服务**：`ConvertService`
+- **前端组件**：`ConvertTab.vue`
+
+**主要用途**：
+
+- 针对无损音频格式（如 WAV/APE 等）智能转换为 FLAC，提高兼容性和标签支持能力；
+- 对于有损格式和已为 FLAC 的文件自动跳过，避免无意义的二次压缩。
+
+### 2. 智能分类策略
+
+- **无损格式转 FLAC**：
+  - 支持：`WAV`, `APE`, `AIFF`, `WV`, `TTA` 等
+  - 统一转换为 `FLAC`，保证后续工具（如标签编辑器、Navidrome）有良好兼容性
+- **有损格式自动跳过**：
+  - 包括：`MP3`, `M4A`, `AAC`, `OGG`, `OPUS`, `WMA` 等
+  - 保持原样，不做任何处理
+- **已是 FLAC 的文件直接跳过**：
+  - 避免重复转换和无意义的文件改动
+
+### 3. FFmpeg 集成方案
+
+- 使用 `ProcessBuilder` 调用系统中的 `ffmpeg` 命令行进行转码：
+  - 典型命令示例（伪代码）：
+    - `ffmpeg -i input.wav -compression_level 5 output.flac`
+- **转码参数约定**：
+  - 压缩级别：`5`（在压缩率与速度之间做平衡）
+  - 保留原始采样率、声道数和位深度，确保音质无损
+- **错误处理**：
+  - 转码失败时记录日志，并在进度信息中体现失败计数
+
+### 4. 任务模式（移动 / 复制）
+
+- **移动模式**：
+  - 转换成功后删除源文件，仅保留 FLAC 文件
+  - 适用于已经确认不再需要原始无损格式的场景
+- **复制模式**：
+  - 保留源文件，在目标目录生成 FLAC 副本
+  - 适合试运行或希望保留源文件做长期归档的场景
+
+### 5. 前端交互流程
+
+1. 用户在前端选择：
+   - 输入目录（待扫描的音频文件目录）
+   - 输出目录（FLAC 目标目录，可与输入目录相同或独立）
+   - 模式（移动 / 复制）
+2. 点击开始任务后，前端调用后端 `/convert` 类接口
+3. 后端创建异步任务并开始遍历、分类、转码
+4. 通过 WebSocket 周期性推送进度：
+   - 总文件数、已处理数量、成功/失败数
+   - 当前处理文件路径
+5. 前端组件展示进度条与当前文件，并在任务完成时弹出结果摘要
+
+### 6. 与其他模块的配合
+
+- 常与 **01-音频文件汇聚** 搭配:先汇聚到一个扁平目录,再执行智能转码
+- 转码完成后通常交由 **05-音乐整理** 进行目录重组和标签检查
+- 在 **06-整理入库** 前确保所有无损源文件已经统一为 FLAC,减少后续维护成本
+
+### 7. 测试用例需求
+
+#### 7.1 后端测试
+
+**单元测试**:
+- 测试音频格式分类逻辑(无损/有损/FLAC)
+- 测试 FFmpeg 命令构建的正确性
+- 测试转码参数配置(压缩级别、采样率保留等)
+- 测试转码失败时的错误处理与日志记录
+- 测试文件删除逻辑(移动模式下的源文件清理)
+
+**集成测试**:
+- 准备各种格式的测试音频文件(WAV、APE、FLAC、MP3、M4A 等)
+- 测试完整的转码任务执行流程
+- 验证转码后的 FLAC 文件音质无损(采样率、位深度、声道数)
+- 测试混合格式目录的智能分类与跳过逻辑
+- 测试异常场景:FFmpeg 未安装、损坏的音频文件、磁盘空间不足
+
+#### 7.2 前端测试
+
+**单元测试**:
+- 测试输入/输出目录的路径校验
+- 测试模式选择的状态管理
+- 测试进度信息展示(成功/失败/跳过计数)
+
+**集成测试**:
+- 测试完整的用户操作流程
+- 测试任务进度的实时更新
+- 测试结果摘要的准确性
+
+**测试数据**:
+- 纯无损文件目录:WAV、APE、AIFF 混合
+- 纯有损文件目录:MP3、M4A、OGG 混合
+- 混合格式目录:包含无损、有损、FLAC
+- 边界场景:超大文件(>1GB)、损坏文件、无效文件扩展名
+
+**性能测试**:
+- 测试批量转码任务的并发性能
+- 测试大文件转码的内存占用
+- 测试 WebSocket 进度推送的频率与性能影响