100 lines
3.4 KiB
Markdown
100 lines
3.4 KiB
Markdown
## 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+ 个文件,包含重复文件名
|
||
- 边界场景:空目录、单个文件、超长文件名、特殊字符文件名
|