121 lines
3.9 KiB
Markdown
121 lines
3.9 KiB
Markdown
## 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 中验证:
|
||
- 艺术家与专辑列表的完整性
|
||
- 歌曲播放的正常性
|
||
- 封面显示的正确性
|
||
- 歌词显示的正确性
|
||
- 验证升级决策的合理性
|
||
- 抽查合并前后的文件完整性
|
||
|
||
**安全性测试**:
|
||
- 验证备份机制(如果启用)
|
||
- 测试合并失败后的回滚能力
|
||
- 测试主库数据不会因合并失败而损坏
|