## 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 进度推送的频率与性能影响