Initial setup of project files and directory structure.

06-整理入库.md

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