3.9 KiB
3.9 KiB
06 - 整理入库
1. 功能概述
- 功能名称：整理入库
- 后端服务：
LibraryMergeService - 前端组件：
MergeTab.vue
主要用途：
- 将整理好的 staging 目录智能合并到 Navidrome 主库中，统一升级音频、歌词与封面资源。
2. 全资源同步策略
- 音频文件同步：
- 按
艺术家/专辑/曲目结构合并 - 若目标库已存在同路径文件，则进入“智能升级决策”
- 按
- 歌词文件同步：
- 同步
.lrc文件，与对应音频文件保持相对路径一致
- 同步
- 封面图片同步：
- 比较已有封面与新封面
- 优先保留分辨率/体积更大的版本
3. 智能升级策略
- 文件大小优先：
- 对于同一首歌曲的多份文件，一般认为文件越大音质越好
- 若新文件明显“更大”，则视为可升级版本
- 关联资源同步：
- 当音频被升级替换时，对应歌词文件也一并同步
- 图片优选：
- 对比封面图片分辨率和文件大小
- 保留清晰度更高的一份，避免重复占用
4. 前端交互流程
- 用户选择：
- 源目录：整理完成后的 staging 目录
- 目标目录：Navidrome 主库根目录
- 配置合并策略（如：是否启用智能升级、是否保留旧版本备份）
- 启动任务后，通过 WebSocket 订阅：
- 已合并的专辑/曲目数
- 升级替换的文件数
- 发生冲突和跳过的条目
- 任务完成后，可查看合并报告（若有实现）或通过日志排查异常情况。
5. 使用建议与整体流程位置
-
整理入库通常作为音乐处理流水线的最后一步：
- 01-音频文件汇聚
- 02-音频格式智能处理
- 03-音乐去重
- 04-音乐元数据繁体转简体
- 05-音乐整理
- 06-整理入库（本模块）
-
建议在正式合并前:
- 对 staging 目录做一次整体浏览(目录浏览组件或文件管理器)
- 确认结构与文件数量基本符合预期,再执行"整理入库"。
6. 测试用例需求
6.1 后端测试
单元测试:
- 测试文件大小比较逻辑(判断是否需要升级)
- 测试路径匹配算法(艺术家/专辑/曲目结构)
- 测试封面图片优选逻辑(分辨率、文件大小)
- 测试歌词文件同步逻辑
- 测试冲突处理策略
集成测试:
- 准备测试数据:
- Staging 目录:新整理的音乐库
- 主库目录:已有部分内容的 Navidrome 库
- 包含升级场景:同一歌曲的低质量与高质量版本
- 包含冲突场景:同路径不同内容
- 测试完整的合并流程
- 验证智能升级策略的准确性
- 验证关联资源(歌词/封面)的同步
- 测试合并结果的完整性
- 测试备份功能(如果启用)
- 测试异常场景:磁盘空间不足、权限不足、文件被占用
6.2 前端测试
单元测试:
- 测试源目录与目标目录的路径校验
- 测试合并策略配置的状态管理
- 测试合并结果统计的展示
集成测试:
- 测试完整的用户操作流程
- 测试合并进度的实时更新
- 测试冲突与跳过条目的展示
- 测试合并报告的查看
测试数据:
- 全新合并场景:主库为空,全部是新增
- 增量合并场景:主库已有内容,部分新增部分升级
- 纯升级场景:所有文件都是已有歌曲的高质量版本
- 边界场景:
- 同一歌曲的多个版本(Live、Remix、不同母带)
- 封面分辨率差异巨大的情况
- 歌词文件编码不一致
- 超大文件合并(测试性能)
质量验证:
- 合并后在 Navidrome 中验证:
- 艺术家与专辑列表的完整性
- 歌曲播放的正常性
- 封面显示的正确性
- 歌词显示的正确性
- 验证升级决策的合理性
- 抽查合并前后的文件完整性
安全性测试:
- 验证备份机制(如果启用)
- 测试合并失败后的回滚能力
- 测试主库数据不会因合并失败而损坏