Initial setup of project files and directory structure.

01-音频文件汇聚.md

@@ -0,0 +1,99 @@
+## 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+ 个文件,包含重复文件名
+- 边界场景:空目录、单个文件、超长文件名、特殊字符文件名