## 06 - 整理入库

### 1. 功能概述

- **功能名称**：整理入库
- **后端服务**：`LibraryMergeService`
- **前端组件**：`MergeTab.vue`

**主要用途**：

- 将整理好的 staging 目录智能合并到 Navidrome 主库中，统一升级音频、歌词与封面资源。

### 2. 全资源同步策略

- **音频文件同步**：
  - 按 `艺术家/专辑/曲目` 结构合并
  - 若目标库已存在同路径文件，则进入“智能升级决策”
- **歌词文件同步**：
  - 同步 `.lrc` 文件，与对应音频文件保持相对路径一致
- **封面图片同步**：
  - 比较已有封面与新封面
  - 优先保留分辨率/体积更大的版本

### 3. 智能升级策略

- **文件大小优先**：
  - 对于同一首歌曲的多份文件，一般认为文件越大音质越好
  - 若新文件明显“更大”，则视为可升级版本
- **关联资源同步**：
  - 当音频被升级替换时，对应歌词文件也一并同步
- **图片优选**：
  - 对比封面图片分辨率和文件大小
  - 保留清晰度更高的一份，避免重复占用

### 4. 前端交互流程

1. 用户选择：
   - **源目录**：整理完成后的 staging 目录
   - **目标目录**：Navidrome 主库根目录
2. 配置合并策略（如：是否启用智能升级、是否保留旧版本备份）
3. 启动任务后，通过 WebSocket 订阅：
   - 已合并的专辑/曲目数
   - 升级替换的文件数
   - 发生冲突和跳过的条目
4. 任务完成后，可查看合并报告（若有实现）或通过日志排查异常情况。

### 5. 使用建议与整体流程位置

- 整理入库通常作为音乐处理流水线的最后一步：
  1. 01-音频文件汇聚
  2. 02-音频格式智能处理
  3. 03-音乐去重
  4. 04-音乐元数据繁体转简体
  5. 05-音乐整理
  6. **06-整理入库（本模块）**

- 建议在正式合并前:
  - 对 staging 目录做一次整体浏览(目录浏览组件或文件管理器)
  - 确认结构与文件数量基本符合预期,再执行"整理入库"。

### 6. 测试用例需求

#### 6.1 后端测试

**单元测试**:
- 测试文件大小比较逻辑(判断是否需要升级)
- 测试路径匹配算法(艺术家/专辑/曲目结构)
- 测试封面图片优选逻辑(分辨率、文件大小)
- 测试歌词文件同步逻辑
- 测试冲突处理策略

**集成测试**:
- 准备测试数据:
  - Staging 目录:新整理的音乐库
  - 主库目录:已有部分内容的 Navidrome 库
  - 包含升级场景:同一歌曲的低质量与高质量版本
  - 包含冲突场景:同路径不同内容
- 测试完整的合并流程
- 验证智能升级策略的准确性
- 验证关联资源(歌词/封面)的同步
- 测试合并结果的完整性
- 测试备份功能(如果启用)
- 测试异常场景:磁盘空间不足、权限不足、文件被占用

#### 6.2 前端测试

**单元测试**:
- 测试源目录与目标目录的路径校验
- 测试合并策略配置的状态管理
- 测试合并结果统计的展示

**集成测试**:
- 测试完整的用户操作流程
- 测试合并进度的实时更新
- 测试冲突与跳过条目的展示
- 测试合并报告的查看

**测试数据**:
- 全新合并场景:主库为空,全部是新增
- 增量合并场景:主库已有内容,部分新增部分升级
- 纯升级场景:所有文件都是已有歌曲的高质量版本
- 边界场景:
  - 同一歌曲的多个版本(Live、Remix、不同母带)
  - 封面分辨率差异巨大的情况
  - 歌词文件编码不一致
  - 超大文件合并(测试性能)

**质量验证**:
- 合并后在 Navidrome 中验证:
  - 艺术家与专辑列表的完整性
  - 歌曲播放的正常性
  - 封面显示的正确性
  - 歌词显示的正确性
- 验证升级决策的合理性
- 抽查合并前后的文件完整性

**安全性测试**:
- 验证备份机制(如果启用)
- 测试合并失败后的回滚能力
- 测试主库数据不会因合并失败而损坏