3.4 KiB
3.4 KiB
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. 典型使用流程
- 在前端选择源目录与目标目录
- 选择模式（移动 / 复制）
- 点击开始任务，前端调用后端
/aggregate类接口 - 后端创建任务并异步执行，周期性通过 WebSocket 推送进度
- 前端展示列表或进度条，任务完成时给出汇总信息
6. 与其他模块的配合
- 通常作为 音频格式智能处理、音乐整理 等功能的预处理步骤
- 通过汇聚将文件位置统一到一个目录,简化后续模块的输入路径配置
7. 测试用例需求
7.1 后端测试
单元测试:
- 测试音频格式白名单过滤逻辑
- 测试文件名冲突解决机制(自动重命名为"文件名(1).ext")
- 测试深度递归遍历的准确性
- 测试移动模式下空目录清理功能
- 测试复制模式下文件完整性保证
集成测试:
- 准备多层级测试目录结构,包含各种音频格式
- 测试汇聚任务的完整执行流程
- 测试进度推送的准确性(总数/已处理/当前文件)
- 测试异常场景:磁盘空间不足、权限不足、文件被占用等
7.2 前端测试
单元测试:
- 测试源目录与目标目录的路径校验
- 测试模式选择(移动/复制)的状态管理
- 测试进度条与统计信息的实时更新
集成测试:
- 测试完整的用户操作流程:选择目录→选择模式→提交任务→查看进度→查看结果
- 测试任务中断与恢复的用户体验
测试数据:
- 小规模场景:10 个文件,3 层目录
- 中等规模场景:1000 个文件,10 层目录
- 大规模场景:10000+ 个文件,包含重复文件名
- 边界场景:空目录、单个文件、超长文件名、特殊字符文件名