Initial setup of project files and directory structure.

00-开发前后端格式.md

@@ -0,0 +1,142 @@
+## 00 - 开发前后端格式
+
+### 1. 项目概述
+
+**MangTool** 是一个基于 **Java Spring Boot + Vue 3** 的个人开发工具箱，专注于音乐库管理和日志处理两大核心模块，特点是：**开箱即用、模块化扩展、安全可靠**。
+
+- **后端技术栈**：Spring Boot、WebSocket、异步任务、文件处理引擎（FFmpeg、Jaudiotagger、SVNKit 等）
+- **前端技术栈**：Vue 3、Vite、Element Plus、组合式 API、基于组件的单页应用
+
+### 1.1 开发环境版本
+
+- **Node.js**：v20.19.5
+- **npm**：10.8.2
+- **Java**：1.8.0_472（OpenJDK 64-Bit Server VM）
+- **Maven**：Apache Maven 3.8.7
+
+### 2. 前后端整体架构
+
+```mermaid
+graph TB
+    subgraph "前端 (Vue 3)"
+        A[前端组件] --> B[API 封装层]
+        B --> C[WebSocket 客户端]
+    end
+
+    subgraph "后端 (Spring Boot)"
+        D[REST 控制器] --> E[业务服务层]
+        E --> F[文件处理引擎]
+        E --> G[WebSocket 服务]
+        F --> H[FFmpeg 集成]
+        F --> I[Jaudiotagger]
+        F --> J[SVNKit]
+    end
+
+    C -- WebSocket 实时进度 --> G
+    B -- HTTP REST API --> D
+    F --> K[本地文件系统]
+```
+
+- **HTTP API**：前端通过 axios 封装的请求模块调用后端 REST 接口
+- **WebSocket**：用于长时间批处理任务的实时进度推送
+- **文件系统访问**：所有音频、日志等文件操作都集中在后端完成，前端只处理路径和参数
+
+### 3. 项目目录结构
+
+```text
+mangtool/
+├── backend/                    # Spring Boot 后端
+│   ├── src/main/java/com/music/
+│   │   ├── config/            # 配置类 (CORS, WebSocket, Async)
+│   │   ├── controller/        # REST 控制器
+│   │   ├── service/           # 业务服务层（核心逻辑）
+│   │   ├── dto/               # 数据传输对象
+│   │   ├── common/            # 通用工具 (Result, ErrorCode)
+│   │   └── exception/         # 全局异常处理
+│   └── pom.xml                # Maven 依赖配置
+├── frontend/                   # Vue 3 前端
+│   ├── src/
+│   │   ├── components/        # 功能模块组件 (*Tab.vue)
+│   │   ├── api/               # API 模块化封装
+│   │   ├── composables/       # 组合式函数 (useWebSocket)
+│   │   └── App.vue            # 主界面与导航
+│   └── vite.config.js         # Vite 配置
+└── docker/                    # 容器化部署配置
+```
+
+### 4. 统一后端返回格式
+
+- **强制要求**：所有后端接口统一返回 `Result<T>`，禁止直接返回实体类或 `ResponseEntity`。
+
+```java
+public class Result<T> {
+    private int code;      // 0=成功，非0=错误
+    private String message; // 提示信息
+    private T data;        // 业务数据
+}
+```
+
+- **全局异常处理**：通过 `GlobalExceptionHandler` 捕获 `BusinessException`，并转换为统一的 `Result` 响应
+
+### 5. 前端 API 调用规范
+
+- **模块划分**：`frontend/src/api/` 下按功能拆分：`aggregate.js`, `convert.js`, `dedup.js` 等
+- **统一请求实例**：所有 API 模块都通过封装好的 axios 实例 `request` 发送请求
+
+**响应拦截器约定**：
+
+- 后端只返回 `Result<T>` 格式
+- 前端拦截器自动判断 `code`：
+  - `code === 0`：直接返回 `data`
+  - 其他：弹出错误信息，并返回 `Promise.reject`
+
+### 6. WebSocket 进度推送规范
+
+**消息结构（ProgressMessage DTO）**：
+
+```java
+public class ProgressMessage {
+    private String taskId;      // 任务 ID
+    private String type;        // 任务类型
+    private int total;          // 总数
+    private int processed;      // 已处理
+    private int success;        // 成功数
+    private int failed;         // 失败数
+    private String currentFile; // 当前处理文件
+    private String message;     // 进度消息
+    private boolean completed;  // 是否完成
+}
+```
+
+- **服务端**:通过 WebSocket 节流推送进度,避免频繁推送导致前端卡顿
+- **前端**:统一封装 `useWebSocket` 组合式函数,在各个 Tab 组件中复用,用于展示进度条 / 当前文件 / 完成状态
+
+### 7. 测试用例需求
+
+#### 7.1 后端测试
+
+**单元测试**:
+- 测试统一返回格式 `Result<T>` 的构建与序列化
+- 测试全局异常处理器对 `BusinessException` 的捕获与转换
+- 测试 WebSocket 消息推送的节流机制
+- 测试路径验证拦截器的安全规则
+
+**集成测试**:
+- 测试完整的 HTTP 请求响应流程(包含正常与异常情况)
+- 测试 WebSocket 连接建立、消息推送、断开重连
+- 测试 CORS 配置是否正确允许前端跨域访问
+
+#### 7.2 前端测试
+
+**单元测试**:
+- 测试 API 响应拦截器对不同 code 值的处理逻辑
+- 测试 `useWebSocket` 组合式函数的连接管理与消息接收
+- 测试各个组件的参数校验与错误提示
+
+**集成测试**:
+- 测试前后端联调:完整的任务提交、进度推送、结果展示流程
+- 测试异常场景:网络断开、后端服务异常、超时等情况的用户提示
+
+**E2E 测试**:
+- 模拟真实用户操作,验证完整的业务流程
+- 测试不同浏览器的兼容性

01-音频文件汇聚.md

@@ -0,0 +1,99 @@
+## 01 - 音频文件汇聚
+
+### 1. 功能概述
+
+- **功能名称**：音频文件汇聚
+- **后端服务**：`AggregatorService`
+- **前端组件**：`AggregateTab.vue`
+
+**主要用途**：
+
+- 将分散在多级子目录中的音频文件全部扁平化汇聚到一个目标目录，便于后续统一转换、整理或入库。
+
+### 2. 前端交互设计（AggregateTab.vue）
+
+- **核心参数**：
+  - **源目录**：递归扫描的起始目录
+  - **目标目录**：所有音频文件最终聚合到的目录
+  - **模式选择**：移动模式 / 复制模式
+- **交互要点**：
+  - 使用统一的目录浏览组件选择路径
+  - 提交后通过 WebSocket 订阅后台任务进度（总数/已处理/当前文件等）
+  - 任务完成后给出简单统计信息（成功/失败数量）
+
+### 3. 后端核心设计（AggregatorService）
+
+#### 3.1 支持的音频格式
+
+- 支持常见格式：`MP3`, `FLAC`, `WAV`, `M4A`, `AAC`, `OGG`, `WMA`, `APE` 等
+- 文件过滤通常通过扩展名白名单实现
+
+#### 3.2 目录遍历策略
+
+- 使用 `Files.walkFileTree()` 或等价方式进行深度递归遍历
+- 忽略非文件或不在白名单中的扩展名
+- 移动模式下，在任务结束后可清理空目录
+
+#### 3.3 冲突解决机制
+
+当目标目录中已存在同名文件时：
+
+- **不覆盖原文件**
+- 自动重命名为：`文件名 (1).ext`, `文件名 (2).ext` ...
+- 确保每个文件都有唯一文件名，不丢数据
+
+### 4. 任务模式
+
+- **移动模式**：
+  - 汇聚成功后删除源目录中的原始文件
+  - 适合“整理后不再保留原结构”的场景
+- **复制模式**：
+  - 保留源目录结构，只在目标目录生成一份扁平化副本
+  - 适合试运行或备份场景
+
+### 5. 典型使用流程
+
+1. 在前端选择源目录与目标目录
+2. 选择模式（移动 / 复制）
+3. 点击开始任务，前端调用后端 `/aggregate` 类接口
+4. 后端创建任务并异步执行，周期性通过 WebSocket 推送进度
+5. 前端展示列表或进度条，任务完成时给出汇总信息
+
+### 6. 与其他模块的配合
+
+- 通常作为 **音频格式智能处理**、**音乐整理** 等功能的预处理步骤
+- 通过汇聚将文件位置统一到一个目录,简化后续模块的输入路径配置
+
+### 7. 测试用例需求
+
+#### 7.1 后端测试
+
+**单元测试**:
+- 测试音频格式白名单过滤逻辑
+- 测试文件名冲突解决机制(自动重命名为"文件名(1).ext")
+- 测试深度递归遍历的准确性
+- 测试移动模式下空目录清理功能
+- 测试复制模式下文件完整性保证
+
+**集成测试**:
+- 准备多层级测试目录结构,包含各种音频格式
+- 测试汇聚任务的完整执行流程
+- 测试进度推送的准确性(总数/已处理/当前文件)
+- 测试异常场景:磁盘空间不足、权限不足、文件被占用等
+
+#### 7.2 前端测试
+
+**单元测试**:
+- 测试源目录与目标目录的路径校验
+- 测试模式选择(移动/复制)的状态管理
+- 测试进度条与统计信息的实时更新
+
+**集成测试**:
+- 测试完整的用户操作流程:选择目录→选择模式→提交任务→查看进度→查看结果
+- 测试任务中断与恢复的用户体验
+
+**测试数据**:
+- 小规模场景:10 个文件,3 层目录
+- 中等规模场景:1000 个文件,10 层目录
+- 大规模场景:10000+ 个文件,包含重复文件名
+- 边界场景:空目录、单个文件、超长文件名、特殊字符文件名

02-音频格式智能处理.md

@@ -0,0 +1,103 @@
+## 02 - 音频格式智能处理
+
+### 1. 功能概述
+
+- **功能名称**：音频格式智能处理
+- **后端服务**：`ConvertService`
+- **前端组件**：`ConvertTab.vue`
+
+**主要用途**：
+
+- 针对无损音频格式（如 WAV/APE 等）智能转换为 FLAC，提高兼容性和标签支持能力；
+- 对于有损格式和已为 FLAC 的文件自动跳过，避免无意义的二次压缩。
+
+### 2. 智能分类策略
+
+- **无损格式转 FLAC**：
+  - 支持：`WAV`, `APE`, `AIFF`, `WV`, `TTA` 等
+  - 统一转换为 `FLAC`，保证后续工具（如标签编辑器、Navidrome）有良好兼容性
+- **有损格式自动跳过**：
+  - 包括：`MP3`, `M4A`, `AAC`, `OGG`, `OPUS`, `WMA` 等
+  - 保持原样，不做任何处理
+- **已是 FLAC 的文件直接跳过**：
+  - 避免重复转换和无意义的文件改动
+
+### 3. FFmpeg 集成方案
+
+- 使用 `ProcessBuilder` 调用系统中的 `ffmpeg` 命令行进行转码：
+  - 典型命令示例（伪代码）：
+    - `ffmpeg -i input.wav -compression_level 5 output.flac`
+- **转码参数约定**：
+  - 压缩级别：`5`（在压缩率与速度之间做平衡）
+  - 保留原始采样率、声道数和位深度，确保音质无损
+- **错误处理**：
+  - 转码失败时记录日志，并在进度信息中体现失败计数
+
+### 4. 任务模式（移动 / 复制）
+
+- **移动模式**：
+  - 转换成功后删除源文件，仅保留 FLAC 文件
+  - 适用于已经确认不再需要原始无损格式的场景
+- **复制模式**：
+  - 保留源文件，在目标目录生成 FLAC 副本
+  - 适合试运行或希望保留源文件做长期归档的场景
+
+### 5. 前端交互流程
+
+1. 用户在前端选择：
+   - 输入目录（待扫描的音频文件目录）
+   - 输出目录（FLAC 目标目录，可与输入目录相同或独立）
+   - 模式（移动 / 复制）
+2. 点击开始任务后，前端调用后端 `/convert` 类接口
+3. 后端创建异步任务并开始遍历、分类、转码
+4. 通过 WebSocket 周期性推送进度：
+   - 总文件数、已处理数量、成功/失败数
+   - 当前处理文件路径
+5. 前端组件展示进度条与当前文件，并在任务完成时弹出结果摘要
+
+### 6. 与其他模块的配合
+
+- 常与 **01-音频文件汇聚** 搭配:先汇聚到一个扁平目录,再执行智能转码
+- 转码完成后通常交由 **05-音乐整理** 进行目录重组和标签检查
+- 在 **06-整理入库** 前确保所有无损源文件已经统一为 FLAC,减少后续维护成本
+
+### 7. 测试用例需求
+
+#### 7.1 后端测试
+
+**单元测试**:
+- 测试音频格式分类逻辑(无损/有损/FLAC)
+- 测试 FFmpeg 命令构建的正确性
+- 测试转码参数配置(压缩级别、采样率保留等)
+- 测试转码失败时的错误处理与日志记录
+- 测试文件删除逻辑(移动模式下的源文件清理)
+
+**集成测试**:
+- 准备各种格式的测试音频文件(WAV、APE、FLAC、MP3、M4A 等)
+- 测试完整的转码任务执行流程
+- 验证转码后的 FLAC 文件音质无损(采样率、位深度、声道数)
+- 测试混合格式目录的智能分类与跳过逻辑
+- 测试异常场景:FFmpeg 未安装、损坏的音频文件、磁盘空间不足
+
+#### 7.2 前端测试
+
+**单元测试**:
+- 测试输入/输出目录的路径校验
+- 测试模式选择的状态管理
+- 测试进度信息展示(成功/失败/跳过计数)
+
+**集成测试**:
+- 测试完整的用户操作流程
+- 测试任务进度的实时更新
+- 测试结果摘要的准确性
+
+**测试数据**:
+- 纯无损文件目录:WAV、APE、AIFF 混合
+- 纯有损文件目录:MP3、M4A、OGG 混合
+- 混合格式目录:包含无损、有损、FLAC
+- 边界场景:超大文件(>1GB)、损坏文件、无效文件扩展名
+
+**性能测试**:
+- 测试批量转码任务的并发性能
+- 测试大文件转码的内存占用
+- 测试 WebSocket 进度推送的频率与性能影响

03-音乐去重.md

@@ -0,0 +1,125 @@
+## 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)的结果
+- 验证不同格式/码率的优先级规则

04-音乐元数据繁体转简体.md

@@ -0,0 +1,120 @@
+## 04 - 音乐元数据繁体转简体
+
+### 1. 功能概述
+
+- **功能名称**：音乐元数据繁体转简体
+- **后端服务**：`ZhConvertService` + `TraditionalFilterService`
+- **前端组件**：`TraditionalFilterTab.vue`
+
+**主要用途**：
+
+- 批量检测并转换音乐标签中的繁体中文，统一为简体中文，提升搜索与展示的一致性。
+
+> 本功能为独立模块，建议在“音乐整理”和“整理入库”之前执行，保持处理流程清晰。
+
+### 2. 繁体检测逻辑
+
+- 对字段内容逐字符扫描，判断是否为繁体字
+- 统计：
+  - 中文字符总数
+  - 其中繁体字符数量
+- 计算繁体占比：
+  - \( ratio = 繁体字符数 / 总中文字符数 \)
+- 支持配置“触发阈值”，只有繁体比例超过阈值的内容才会被列入待处理列表
+
+### 3. 支持字段
+
+- 标题（Title）
+- 艺术家（Artist）
+- 专辑（Album）
+- 专辑艺人（AlbumArtist）
+
+### 4. 处理模式
+
+- **预览模式**：
+  - 只扫描并列出检测到繁体的文件与字段
+  - 不对原文件做任何修改
+  - 适合先评估影响范围
+- **执行模式**：
+  - 对选中的字段进行繁体→简体转换
+  - 可选择“覆盖原文件”或“输出到目标目录”
+
+### 5. 前端交互流程
+
+1. 用户选择扫描目录和输出目录（可选）
+2. 配置繁体占比阈值（例如 10%）
+3. 选择处理模式（预览 / 执行）
+4. 启动任务后，通过 WebSocket 获取进度：
+   - 已扫描文件数
+   - 检测到的繁体标签条目数量
+5. 对于预览模式，前端可展示：
+   - 文件路径
+   - 原始标签内容
+   - 转换后的预览内容
+
+### 6. 使用建议与流水线位置
+
+- 推荐使用顺序：
+  1. 通过刮削工具（如 MusicBrainz Picard）补全英文/日文等元数据
+  2. 使用本模块统一处理中文标签的繁简体问题
+  3. 再通过 **05-音乐整理** 做目录重组和命名规范化
+  4. 最后通过 **06-整理入库** 将整理好的内容合并入主库
+
+- 这样可以保证:
+  - 标签内容在进入主库前已完成繁简统一
+  - 同一艺人/专辑不会因繁简混用出现在不同目录下。
+
+### 7. 测试用例需求
+
+#### 7.1 后端测试
+
+**单元测试**:
+- 测试繁体字符识别逻辑的准确性
+- 测试繁体占比计算算法
+- 测试繁简转换的正确性(覆盖常用繁体字)
+- 测试阈值判断逻辑(不同占比的处理)
+- 测试各标签字段(Title/Artist/Album/AlbumArtist)的独立处理
+
+**集成测试**:
+- 准备测试音频文件:
+  - 纯繁体标签
+  - 繁简混合标签
+  - 纯简体标签(验证不会误转)
+  - 英文/日文标签(验证不受影响)
+- 测试预览模式:只扫描不修改
+- 测试执行模式:实际修改标签
+- 验证转换后的标签准确性
+- 测试覆盖原文件与输出到目标目录两种模式
+- 测试异常场景:无标签文件、只读文件、损坏文件
+
+#### 7.2 前端测试
+
+**单元测试**:
+- 测试繁体占比阈值配置的校验
+- 测试处理模式选择的状态管理
+- 测试预览结果的展示格式
+
+**集成测试**:
+- 测试完整的预览流程
+- 测试完整的执行流程
+- 测试转换前后对比展示
+
+**测试数据**:
+- 标准繁体:
+  - 周杰倫 → 周杰伦
+  - 我的歌聲裡 → 我的歌声里
+  - 愛情轉移 → 爱情转移
+- 繁简混合:
+  - 周杰倫的愛情故事 → 周杰伦的爱情故事
+- 多音字与特殊字:
+  - 幹什麼 → 干什么
+  - 後來 → 后来
+- 边界场景:
+  - 纯英文标签(不应改变)
+  - 日文汉字(部分繁体,需谨慎处理)
+  - 空标签或特殊字符
+
+**质量验证**:
+- 对比专业繁简转换工具的结果
+- 人工抽查转换结果,确保无误转
+- 验证不同繁体占比阈值的效果

05-音乐整理.md

@@ -0,0 +1,151 @@
+## 05 - 音乐整理
+
+### 1. 功能概述
+
+- **功能名称**：音乐整理
+- **后端服务**：`RenameService` + `OrganizeService`
+- **前端组件**：`RenameTab.vue`
+
+**主要用途**：
+
+- 将已整理好标签的音频文件按 Navidrome 标准目录结构重命名、分组，并生成封面、歌词与整理报告。
+
+### 2. 目标目录结构规范
+
+- 标准结构示例：
+  - `艺术家/专辑(年份)/曲号 - 标题.ext`
+- 示例：
+  - `周杰伦/七里香(2004)/01 - 七里香.flac`
+  - `Adele/21(2011)/01 - Rolling In The Deep.flac`
+
+### 3. A-Z 索引分组策略
+
+- **正常艺术家**：
+  - 中文艺术家：按拼音首字母分组（如“周杰伦” → `Z/周杰伦/...`）
+  - 英文艺术家：按首字母分组（如“Adele” → `A/Adele/...`）
+- **合辑**：
+  - 统一归入 `Various Artists` 目录，不参与 A-Z 分组
+- **特殊字符开头**：
+  - 数字或特殊符号开头的艺术家统一归入 `#/` 分组
+- **多音字处理**：
+  - 使用 Pinyin4j 默认取第一个读音，绝大多数场景可以接受
+
+### 4. 质量隔离机制
+
+- 根据标签完整度对文件进行分层处理：
+  - **严格模式**：必须同时包含 `Title + Artist + Album` 才参与整理
+  - **宽松模式**：只要有 `Title` 即可参与整理
+- 对于缺少必要标签的文件：
+  - 自动移动到 `_Manual_Fix_Required_/Missing_XXX/` 等目录
+  - 便于后续集中使用标签工具（如 MusicBrainz Picard）修复
+
+### 5. 附加功能
+
+#### 5.1 封面提取
+
+- 从音频文件内嵌封面中提取 `cover.jpg` 到专辑目录
+- 按专辑粒度判断：
+  - 只要专辑中任一文件含有封面，即视为该专辑有封面，并提取一次
+
+#### 5.2 歌词提取
+
+- 从音频文件中提取内嵌歌词到 `.lrc` 文件
+- 按单曲粒度判断：
+  - 每个文件独立检查是否含有歌词
+
+#### 5.3 整理报告生成
+
+- 整理结束后自动生成报告文件：
+  - 文件名：`report_YYYYMMDD_HHMMSS.txt`
+  - 位置：目标目录下 `_Reports/` 子目录
+- 报告内容包括：
+  - 生成时间、扫描文件数
+  - 缺失封面的专辑列表
+  - 缺失歌词的文件列表
+  - 统计摘要（总专辑数、无封面专辑数及百分比、无歌词文件数及百分比）
+
+### 6. 前端交互流程
+
+1. 用户选择“源目录”（通常是经过汇聚、转码、去重后的 staging 目录）
+2. 选择“目标目录”（正式库或 staging 输出目录）
+3. 配置：
+   - 严格 / 宽松 模式
+   - 是否提取封面
+   - 是否提取歌词
+   - 是否生成报告
+4. 执行任务，通过 WebSocket 订阅进度与当前处理文件
+5. 整理完成后，可在 `_Reports/` 中查看整理报告，对问题文件做二次处理。
+
+### 7. 建议使用顺序
+
+- 推荐整体流水线：
+  1. 01-音频文件汇聚
+  2. 02-音频格式智能处理
+  3. 03-音乐去重
+  4. 04-音乐元数据繁体转简体
+  5. **05-音乐整理（本模块）**
+  6. 06-整理入库
+
+- 这样可以保证进入主库前,目录结构、文件命名、标签内容和资源(封面/歌词)都已基本规范。
+
+### 8. 测试用例需求
+
+#### 8.1 后端测试
+
+**单元测试**:
+- 测试中文拼音首字母提取的准确性(含多音字)
+- 测试英文首字母分组逻辑
+- 测试特殊字符处理(数字、符号归入"#"分组)
+- 测试合辑识别与 Various Artists 归类
+- 测试标签完整度检查(严格/宽松模式)
+- 测试目录结构生成:"艺术家/专辑(年份)/曲号 - 标题.ext"
+- 测试封面提取逻辑(按专辑粒度)
+- 测试歌词提取逻辑(按单曲粒度)
+- 测试整理报告生成(缺失封面/歌词统计)
+
+**集成测试**:
+- 准备测试音频文件:
+  - 完整标签的文件(中文/英文/日文艺术家)
+  - 标签不完整的文件(缺 Title/Artist/Album)
+  - 含内嵌封面的文件
+  - 含内嵌歌词的文件
+  - 合辑文件(AlbumArtist = Various Artists)
+- 测试严格模式:缺标签文件移动到 _Manual_Fix_Required_/
+- 测试宽松模式:只要有 Title 即可整理
+- 测试 A-Z 分组的正确性
+- 验证生成的目录结构符合 Navidrome 规范
+- 验证封面与歌词文件的提取与命名
+- 验证整理报告的准确性
+- 测试异常场景:无效标签、特殊字符、超长文件名
+
+#### 8.2 前端测试
+
+**单元测试**:
+- 测试源目录与目标目录的路径校验
+- 测试模式选择(严格/宽松)的状态管理
+- 测试功能开关(提取封面/歌词/生成报告)的状态管理
+- 测试进度信息的实时更新
+
+**集成测试**:
+- 测试完整的用户操作流程
+- 测试整理报告的查看与下载
+- 测试不同配置组合的效果
+
+**测试数据**:
+- 小规模场景:50 首歌曲,5 个艺术家,10 个专辑
+- 中等规模场景:5000 首歌曲,200 个艺术家,500 个专辑
+- 大规模场景:50000+ 首歌曲,测试性能与报告生成
+- 边界场景:
+  - 中英日混合艺术家
+  - 多音字艺术家(如:曲婉婷、单依纯)
+  - 特殊字符开头的艺术家
+  - 合辑专辑
+  - 缺失各种标签的文件
+  - 超长文件名与路径
+
+**质量验证**:
+- 验证生成的目录结构在 Navidrome 中的兼容性
+- 抽查 A-Z 分组的准确性
+- 验证封面图片的完整性与格式
+- 验证歌词文件的格式与内容
+- 验证整理报告的统计准确性

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

07-全局配置_路径配置.md

@@ -0,0 +1,59 @@
+## 07 - 全局配置: 路径配置
+
+### 1. 功能概述
+
+- **功能名称**：全局路径配置
+- **核心逻辑**：通过配置一个**全局根目录 (WorkDir)**，自动派生出音频处理流水线（汇聚 -> 转换 -> 去重 -> 繁简转换 -> 整理 -> 入库）中各个阶段所需的标准子目录。
+- **设计目标**：一键配置，全流程自动化运行，减少用户在每个环节手动输入路径的操作。
+
+### 2. 全局根路径设计
+
+用户只需在设置界面指定一个 `根路径 (BasePath)`，系统将自动在该路径下维护以下结构：
+
+| 目录名称 | 变量名示例 | 物理路径 (假设根为 `/MusicWork`) | 用途说明 |
+| :--- | :--- | :--- | :--- |
+| **Input** | `SRC_ACC_DIR` | `/MusicWork/Input` | 默认存放待处理的原始杂乱音频 |
+| **Staging_Aggregated** | `DST_ACC_DIR` | `/MusicWork/Staging_Aggregated` | 扁平化汇聚后的核心工作区 |
+| **Staging_Format_Issues**| `DST_CONV_ISSUE` | `/MusicWork/Staging_Format_Issues` | 存放转换失败或格式不达标的文件 |
+| **Staging_Duplicates** | `DST_DEDUP_TRASH`| `/MusicWork/Staging_Duplicates` | 存放被识别为重复的文件 |
+| **Staging_T2S_Output** | `DST_ZH_CONV` | `/MusicWork/Staging_T2S_Output` | 存放完成繁简转换后的文件 |
+| **Staging_Organized** | `DST_ORG_DIR` | `/MusicWork/Staging_Organized` | 存放最终按 A-Z 结构整理好的文件 |
+| **Library_Final** | `DST_LIB_FINAL` | `/MusicWork/Library_Final` | 最终入库合并的目标主库 |
+
+### 3. 各模块路径映射关系 (Pipeline)
+
+根据流水线顺序，各模块的路径使用逻辑如下：
+
+1.  **音频文件汇聚 (01)**
+    - **源目录**：`${ROOT}/Input` (用户可自定义修改，默认从此开始)
+    - **目标目录**：`${ROOT}/Staging_Aggregated` (固定)
+2.  **音频格式智能处理 (02)**
+    - **源目录**：`${ROOT}/Staging_Aggregated` (固定，使用汇聚后的结果)
+    - **转换后异常目录**：`${ROOT}/Staging_Format_Issues` (固定)
+3.  **音乐去重 (03)**
+    - **源目录**：`${ROOT}/Staging_Aggregated` (固定)
+    - **重复文件存放目录**：`${ROOT}/Staging_Duplicates` (固定)
+4.  **元数据繁简转换 (04)**
+    - **源目录**：`${ROOT}/Staging_Aggregated` (固定)
+    - **转换后输出目录**：`${ROOT}/Staging_T2S_Output` (固定)
+5.  **音乐整理 (05)**
+    - **源目录**：`${ROOT}/Staging_Aggregated` (或根据流程选择输出目录)
+    - **整理后固定目录**：`${ROOT}/Staging_Organized` (固定)
+6.  **整理入库 (06)**
+    - **源目录**：`${ROOT}/Staging_Organized` (固定，取自音乐整理的输出)
+    - **主库固定目录**：`${ROOT}/Library_Final` (固定)
+
+### 4. 前端交互设计
+
+- **配置入口**：全局设置 (Settings) 页面。
+- **交互流程**：
+    1. 用户点击“选择根目录”。
+    2. 系统展示派生出的子目录预览列表。
+    3. 点击“保存”，系统自动创建尚未存在的子目录。
+    4. 各功能页面的路径输入框默认填充上述对应的自动路径。
+
+### 5. 后端实现建议
+
+- **ConfigService**: 负责保存 `BasePath` 并提供获取各子路径的方法（如 `getAggregatedDir()`）。
+- **初始化逻辑**: 在保存 `BasePath` 时，调用 `Files.createDirectories()` 确保整个工作流目录结构就绪。
+- **路径解析**: 使用 `Paths.get(basePath, subDirName)` 确保跨平台路径兼容。

08-路径.md

@@ -0,0 +1,202 @@
+# 路径配置跨平台兼容性优化方案
+
+## 1. 问题背景
+
+在跨平台部署后端服务时，不同操作系统（Windows、Linux、macOS）的路径格式存在差异，可能导致路径处理错误。主要问题包括：
+- 路径分隔符不同：Windows使用`\`，Linux/macOS使用`/`
+- 路径表示方式不同：如Windows的盘符（C:\）与Linux的根目录（/）
+- 相同路径的不同表示形式：如`C:\Users\test`与`C:/Users/test`
+
+## 2. 优化目标
+
+- 确保路径配置在不同操作系统上都能正确工作
+- 统一路径在前端和后端之间的传输格式
+- 提高路径处理的健壮性和安全性
+- 保持与现有系统功能的兼容性
+
+## 3. 优化方案
+
+### 3.1 前端路径处理优化
+
+#### 3.1.1 路径拼接逻辑
+- **修改文件**：`frontend/src/components/SettingsTab.vue`
+- **优化内容**：
+  - 将所有路径转换为POSIX格式（使用`/`作为分隔符）
+  - 添加路径验证，检查是否包含非法字符
+  - 确保传递给后端的路径格式统一
+
+#### 3.1.2 核心代码变更
+```javascript
+// 确保路径使用平台无关的表示方式，统一使用 / 作为分隔符
+const normalizedRoot = root.replace(/\\/g, '/');
+
+// 路径验证：检查是否包含非法字符
+const invalidChars = /[<>:"|?*]/;
+if (invalidChars.test(basePath.value)) {
+  message.value = { text: '路径包含非法字符，请检查', type: 'error' };
+  return;
+}
+```
+
+### 3.2 后端路径处理优化
+
+#### 3.2.1 路径工具类
+- **创建文件**：`backend/src/main/java/com/music/common/PathUtils.java`
+- **核心功能**：
+  - 路径规范化：将不同表示形式的路径转换为统一格式
+  - 跨平台路径转换：支持POSIX格式与平台特定格式互转
+  - 路径验证：检查路径是否包含非法字符
+  - 路径拼接：使用平台无关的方式拼接路径
+
+#### 3.2.2 ConfigService优化
+- **修改文件**：`backend/src/main/java/com/music/service/ConfigService.java`
+- **优化内容**：
+  - 在保存配置时验证并规范化basePath
+  - 在加载配置时规范化basePath
+  - 确保配置文件中存储的路径格式正确
+
+#### 3.2.3 Config类优化
+- **修改文件**：`backend/src/main/java/com/music/dto/Config.java`
+- **优化内容**：
+  - 确保派生路径使用POSIX格式
+  - 统一路径分隔符为`/`
+
+## 4. 实现细节
+
+### 4.1 路径工具类核心方法
+
+| 方法名 | 功能描述 |
+| :--- | :--- |
+| `normalizePath(String path)` | 规范化路径，去除`..`等相对路径部分 |
+| `toPosixPath(String path)` | 将路径转换为POSIX格式（使用`/`） |
+| `toPlatformPath(String path)` | 将路径转换为平台特定格式 |
+| `isValidPath(String path)` | 验证路径是否合法 |
+| `joinPath(String parent, String child)` | 拼接路径，使用平台无关的方式 |
+
+### 4.2 路径验证规则
+
+- 禁止包含以下非法字符：`< > : " | ? *`
+- 路径必须是有效的文件系统路径
+- 路径长度不能超过系统限制
+
+## 5. 测试方案
+
+### 5.1 单元测试
+- **测试文件**：`backend/src/test/java/com/music/common/PathUtilsTest.java`
+- **测试场景**：
+  - Windows路径规范化
+  - Linux路径规范化
+  - 跨平台路径转换
+  - 路径验证
+  - 路径拼接
+
+### 5.2 集成测试
+- 在不同操作系统上部署服务
+- 测试路径配置功能
+- 验证配置文件跨平台迁移
+
+### 5.3 测试用例示例
+
+```java
+@Test
+void testToPosixPath() {
+    // 测试Windows路径转POSIX路径
+    String windowsPath = "C:\\Users\\test\\MusicWork";
+    String posixPath = PathUtils.toPosixPath(windowsPath);
+    assertEquals("C:/Users/test/MusicWork", posixPath);
+}
+
+@Test
+void testIsValidPath() {
+    // 测试合法路径
+    assertTrue(PathUtils.isValidPath("C:\\Users\\test\\MusicWork"));
+    // 测试非法路径
+    assertFalse(PathUtils.isValidPath("C:\\Users\\test\\Music<Work"));
+}
+```
+
+## 6. 部署与迁移
+
+### 6.1 部署注意事项
+- 无需额外配置，优化后的代码会自动处理跨平台路径
+- 确保配置文件中的路径格式正确
+
+### 6.2 配置文件迁移
+- 旧配置文件会在加载时自动规范化
+- 迁移到新平台时，无需手动修改配置文件
+
+## 7. 最佳实践
+
+### 7.1 前端开发
+- 始终使用`/`作为路径分隔符
+- 在发送路径给后端前，先进行规范化处理
+- 添加路径验证，确保路径格式正确
+
+### 7.2 后端开发
+- 使用`PathUtils`工具类处理所有路径操作
+- 接收前端路径时，先进行规范化处理
+- 保存路径时，使用平台无关的格式
+
+## 8. 效果评估
+
+- **兼容性**：支持Windows、Linux、macOS等主流操作系统
+- **健壮性**：能够处理各种格式的路径
+- **安全性**：防止非法路径字符导致的安全问题
+- **易用性**：开发人员无需关心平台差异
+
+## 9. 经验教训与优化案例
+
+### 9.1 案例：Windows路径非法字符检测问题
+
+#### 问题描述
+用户在输入Windows 11路径"Z:\音视频"时，系统提示"路径包含非法字符，请检查"，但该路径在Windows系统中是合法的。
+
+#### 根本原因
+前端正则表达式`/[<>:"|?*]/`将冒号`:`列为非法字符，但在Windows路径中，冒号是合法的，用于分隔盘符和路径（如`Z:\音视频`）。
+
+#### 解决方案
+1. **前端修复**：修改正则表达式，移除冒号，并在验证前提取路径中的盘符部分
+2. **后端同步**：确保后端PathUtils类的验证逻辑与前端保持一致
+3. **测试用例补充**：添加中文路径和Windows盘符路径的测试用例
+
+#### 修复代码示例
+```javascript
+// 前端修复后的验证逻辑
+let pathToValidate = basePath.value;
+// 移除盘符部分（如果有）
+if (pathToValidate.match(/^[A-Za-z]:/)) {
+  pathToValidate = pathToValidate.substring(2);
+}
+const invalidChars = /[<>"|?*]/;
+if (invalidChars.test(pathToValidate)) {
+  message.value = { text: '路径包含非法字符，请检查', type: 'error' };
+  return;
+}
+```
+
+### 9.2 经验教训
+
+1. **跨平台兼容性考虑**：在设计路径验证规则时，必须考虑不同操作系统的路径格式差异
+2. **正则表达式精确性**：避免将合法的路径分隔符（如Windows的盘符冒号）误判为非法字符
+3. **前后端逻辑一致性**：确保前端和后端使用相同的路径验证规则
+4. **充分测试**：添加覆盖不同平台、不同路径格式的测试用例
+5. **用户友好提示**：提供更具体的错误提示，帮助用户理解问题所在
+
+## 10. 后续优化方向
+
+- 优化路径错误提示，提供更具体的错误信息
+- 添加路径长度验证，防止超长路径
+- 支持长路径前缀（如Windows的`\\?\`）
+- 考虑添加路径自动修复功能
+
+## 11. 总结
+
+通过对前端和后端路径处理的优化，解决了跨平台部署时的路径兼容性问题。优化后的系统能够：
+- 自动处理不同平台的路径格式
+- 统一前端和后端之间的路径传输格式
+- 正确处理Windows路径中的盘符冒号
+- 支持中文路径
+- 提高路径处理的健壮性和安全性
+- 保持与现有系统功能的兼容性
+
+这将使后端服务能够在不同操作系统上无缝部署和运行，提高了系统的可移植性和可靠性。通过本次修复案例，我们也积累了宝贵的跨平台路径处理经验，为未来的系统优化奠定了基础。