## 01 - 音频文件汇聚

### 1. 功能概述

- **功能名称**：音频文件汇聚
- **后端服务**：`AggregatorService`
- **前端组件**：`AggregateTab.vue`

**主要用途**：

- 将分散在多级子目录中的音频文件全部扁平化汇聚到一个目标目录，便于后续统一转换、整理或入库。

### 2. 前端交互设计（AggregateTab.vue）

- **核心参数**：
  - **源目录**：递归扫描的起始目录
  - **目标目录**：所有音频文件最终聚合到的目录
  - **模式选择**：移动模式 / 复制模式
- **交互要点**：
  - 使用统一的目录浏览组件选择路径
  - 提交后通过 WebSocket 订阅后台任务进度（总数/已处理/当前文件等）
  - 任务完成后给出简单统计信息（成功/失败数量）

### 3. 后端核心设计（AggregatorService）

#### 3.1 支持的音频格式

- 支持常见格式：`MP3`, `FLAC`, `WAV`, `M4A`, `AAC`, `OGG`, `WMA`, `APE` 等
- 文件过滤通常通过扩展名白名单实现

#### 3.2 目录遍历策略

- 使用 `Files.walkFileTree()` 或等价方式进行深度递归遍历
- 忽略非文件或不在白名单中的扩展名
- 移动模式下，在任务结束后可清理空目录

#### 3.3 冲突解决机制

当目标目录中已存在同名文件时：

- **不覆盖原文件**
- 自动重命名为：`文件名 (1).ext`, `文件名 (2).ext` ...
- 确保每个文件都有唯一文件名，不丢数据

### 4. 任务模式

- **移动模式**：
  - 汇聚成功后删除源目录中的原始文件
  - 适合“整理后不再保留原结构”的场景
- **复制模式**：
  - 保留源目录结构，只在目标目录生成一份扁平化副本
  - 适合试运行或备份场景

### 5. 典型使用流程

1. 在前端选择源目录与目标目录
2. 选择模式（移动 / 复制）
3. 点击开始任务，前端调用后端 `/aggregate` 类接口
4. 后端创建任务并异步执行，周期性通过 WebSocket 推送进度
5. 前端展示列表或进度条，任务完成时给出汇总信息

### 6. 与其他模块的配合

- 通常作为 **音频格式智能处理**、**音乐整理** 等功能的预处理步骤
- 通过汇聚将文件位置统一到一个目录,简化后续模块的输入路径配置

### 7. 测试用例需求

#### 7.1 后端测试

**单元测试**:
- 测试音频格式白名单过滤逻辑
- 测试文件名冲突解决机制(自动重命名为"文件名(1).ext")
- 测试深度递归遍历的准确性
- 测试移动模式下空目录清理功能
- 测试复制模式下文件完整性保证

**集成测试**:
- 准备多层级测试目录结构,包含各种音频格式
- 测试汇聚任务的完整执行流程
- 测试进度推送的准确性(总数/已处理/当前文件)
- 测试异常场景:磁盘空间不足、权限不足、文件被占用等

#### 7.2 前端测试

**单元测试**:
- 测试源目录与目标目录的路径校验
- 测试模式选择(移动/复制)的状态管理
- 测试进度条与统计信息的实时更新

**集成测试**:
- 测试完整的用户操作流程:选择目录→选择模式→提交任务→查看进度→查看结果
- 测试任务中断与恢复的用户体验

**测试数据**:
- 小规模场景:10 个文件,3 层目录
- 中等规模场景:1000 个文件,10 层目录
- 大规模场景:10000+ 个文件,包含重复文件名
- 边界场景:空目录、单个文件、超长文件名、特殊字符文件名