## 03 - 音乐去重

### 1. 功能概述

- **功能名称**：音乐去重
- **后端服务**：`DedupService`
- **前端组件**：`DedupTab.vue`

**主要用途**：

- 在大型音乐库中识别并处理重复文件，减少存储占用，保持库结构干净整洁。

> 去重结果高度依赖音频元数据（标签）的质量，建议先用专业刮削工具整理好标签。

### 2. 前置条件与推荐工具

- 去重算法依赖以下标签信息：
  - 艺术家（Artist）
  - 标题（Title）
  - 专辑（Album）
  - 时长（带一定误差容忍）
- **推荐刮削工具**：
  - `MusicBrainz Picard`（开源免费，专业级）
  - `音乐标签` PC 版（中文界面，更易上手）

### 3. 双重去重策略

#### 3.1 MD5 哈希去重

- 对每个音频文件计算 MD5 值
- 相同 MD5 值视为完全相同的二进制文件
- 适用于“完全拷贝”的重复场景（如不同目录下的同一文件）

#### 3.2 元数据匹配去重

- 按以下字段组合匹配：
  - 艺术家 + 标题 + 专辑 + 时长（允许 ±5 秒误差）
- 对候选重复组内的文件进行打分，选出“保留对象”：
  - **格式优先**：`FLAC` > 其他无损 > 有损
  - **码率优先**：码率越高得分越多
  - **文件大小**：更大的文件通常音质更好
  - **文件名匹配度**：文件名包含艺术家/标题会加分

### 4. 智能评分与选择策略

- 为候选重复组内每个文件计算综合评分：
  - 格式加权：FLAC 加较高权重
  - 码率加权：高码率文件加分
  - 文件大小：极小文件（疑似样本或损坏）会被减分
  - 文件名噪声惩罚：数字前缀、无意义后缀、过多符号会被扣分
- 最终选择得分最高的文件作为“保留文件”，其他作为“候选删除/移动对象”。

### 5. 安全机制与执行模式

- **移动模式**：
  - 将重复文件移动到指定“回收站”目录，可后续人工检查与恢复
- **复制模式**：
  - 将重复文件复制到回收站目录，原库保持不变，适合试运行和验证规则
- 建议先使用 **复制模式** 验证规则效果，再切换到 **移动模式** 正式清理。

### 6. 前端交互流程

1. 用户选择音乐库根目录和回收站目录
2. 勾选去重策略（是否启用 MD5、是否启用元数据匹配）
3. 执行任务后，通过 WebSocket 获取去重进度与当前处理文件
4. 任务结束时展示：
   - 扫描文件总数
   - 识别的重复组数量
   - 实际移动/复制的文件数量

### 7. 建议使用顺序

- 通常在完成以下步骤后使用去重:
  1. 使用刮削软件整理标签
  2. 可选:使用 **01-音频文件汇聚** 汇总散落文件
  3. 可选:使用 **02-音频格式智能处理** 统一为 FLAC
- 去重完成后再交由 **05-音乐整理** 和 **06-整理入库** 进一步规范库结构。

### 8. 测试用例需求

#### 8.1 后端测试

**单元测试**:
- 测试 MD5 哈希计算的准确性与性能
- 测试元数据匹配逻辑(艺术家+标题+专辑+时长容差)
- 测试文件评分算法(格式、码率、文件大小、文件名匹配度)
- 测试重复组筛选与保留文件选择逻辑
- 测试文件名噪声识别与惩罚规则

**集成测试**:
- 准备测试数据集:
  - 完全相同的文件副本(MD5 去重场景)
  - 相同歌曲的不同版本(不同格式、不同码率)
  - 标签不完整的文件(测试容错性)
- 测试完整的去重任务执行流程
- 验证去重结果的准确性:保留文件是否为最优选择
- 测试移动/复制模式的正确执行
- 测试异常场景:无标签文件、损坏文件、权限不足

#### 8.2 前端测试

**单元测试**:
- 测试音乐库与回收站目录的路径校验
- 测试去重策略勾选的状态管理
- 测试去重结果统计的展示

**集成测试**:
- 测试完整的用户操作流程
- 测试去重结果预览(如果有)
- 测试任务进度与当前处理文件展示

**测试数据**:
- 小规模场景:100 个文件,10 对重复
- 中等规模场景:5000 个文件,500 对重复
- 大规模场景:50000+ 个文件,测试性能
- 边界场景:
  - 全部文件都是重复
  - 完全没有重复
  - 标签缺失或错误
  - 多个版本的重复组(3 个以上相同歌曲)

**质量验证**:
- 人工抽查去重结果,验证保留文件的合理性
- 对比专业去重工具(如 Mp3tag)的结果
- 验证不同格式/码率的优先级规则