From 981b4ecf42d5560ee18afb0f119b53080bb4af7c Mon Sep 17 00:00:00 2001 From: liu <362165265@qq.com> Date: Thu, 29 Jan 2026 10:29:58 +0800 Subject: [PATCH] Initial setup of project files and directory structure. --- 00-开发前后端格式.md | 142 ++++++++++++++++++++++++++ 01-音频文件汇聚.md | 99 ++++++++++++++++++ 02-音频格式智能处理.md | 103 +++++++++++++++++++ 03-音乐去重.md | 125 +++++++++++++++++++++++ 04-音乐元数据繁体转简体.md | 120 ++++++++++++++++++++++ 05-音乐整理.md | 151 +++++++++++++++++++++++++++ 06-整理入库.md | 120 ++++++++++++++++++++++ 07-全局配置_路径配置.md | 59 +++++++++++ 08-路径.md | 202 +++++++++++++++++++++++++++++++++++++ 9 files changed, 1121 insertions(+) create mode 100644 00-开发前后端格式.md create mode 100644 01-音频文件汇聚.md create mode 100644 02-音频格式智能处理.md create mode 100644 03-音乐去重.md create mode 100644 04-音乐元数据繁体转简体.md create mode 100644 05-音乐整理.md create mode 100644 06-整理入库.md create mode 100644 07-全局配置_路径配置.md create mode 100644 08-路径.md diff --git a/00-开发前后端格式.md b/00-开发前后端格式.md new file mode 100644 index 0000000..bd60eb8 --- /dev/null +++ b/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`，禁止直接返回实体类或 `ResponseEntity`。 + +```java +public class Result { + 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` 格式 +- 前端拦截器自动判断 `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` 的构建与序列化 +- 测试全局异常处理器对 `BusinessException` 的捕获与转换 +- 测试 WebSocket 消息推送的节流机制 +- 测试路径验证拦截器的安全规则 + +**集成测试**: +- 测试完整的 HTTP 请求响应流程(包含正常与异常情况) +- 测试 WebSocket 连接建立、消息推送、断开重连 +- 测试 CORS 配置是否正确允许前端跨域访问 + +#### 7.2 前端测试 + +**单元测试**: +- 测试 API 响应拦截器对不同 code 值的处理逻辑 +- 测试 `useWebSocket` 组合式函数的连接管理与消息接收 +- 测试各个组件的参数校验与错误提示 + +**集成测试**: +- 测试前后端联调:完整的任务提交、进度推送、结果展示流程 +- 测试异常场景:网络断开、后端服务异常、超时等情况的用户提示 + +**E2E 测试**: +- 模拟真实用户操作,验证完整的业务流程 +- 测试不同浏览器的兼容性 diff --git a/01-音频文件汇聚.md b/01-音频文件汇聚.md new file mode 100644 index 0000000..7c178a8 --- /dev/null +++ b/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+ 个文件,包含重复文件名 +- 边界场景:空目录、单个文件、超长文件名、特殊字符文件名 diff --git a/02-音频格式智能处理.md b/02-音频格式智能处理.md new file mode 100644 index 0000000..2179144 --- /dev/null +++ b/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 进度推送的频率与性能影响 diff --git a/03-音乐去重.md b/03-音乐去重.md new file mode 100644 index 0000000..bd9a439 --- /dev/null +++ b/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)的结果 +- 验证不同格式/码率的优先级规则 diff --git a/04-音乐元数据繁体转简体.md b/04-音乐元数据繁体转简体.md new file mode 100644 index 0000000..c050d33 --- /dev/null +++ b/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 前端测试 + +**单元测试**: +- 测试繁体占比阈值配置的校验 +- 测试处理模式选择的状态管理 +- 测试预览结果的展示格式 + +**集成测试**: +- 测试完整的预览流程 +- 测试完整的执行流程 +- 测试转换前后对比展示 + +**测试数据**: +- 标准繁体: + - 周杰倫 → 周杰伦 + - 我的歌聲裡 → 我的歌声里 + - 愛情轉移 → 爱情转移 +- 繁简混合: + - 周杰倫的愛情故事 → 周杰伦的爱情故事 +- 多音字与特殊字: + - 幹什麼 → 干什么 + - 後來 → 后来 +- 边界场景: + - 纯英文标签(不应改变) + - 日文汉字(部分繁体,需谨慎处理) + - 空标签或特殊字符 + +**质量验证**: +- 对比专业繁简转换工具的结果 +- 人工抽查转换结果,确保无误转 +- 验证不同繁体占比阈值的效果 diff --git a/05-音乐整理.md b/05-音乐整理.md new file mode 100644 index 0000000..99cad30 --- /dev/null +++ b/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 分组的准确性 +- 验证封面图片的完整性与格式 +- 验证歌词文件的格式与内容 +- 验证整理报告的统计准确性 diff --git a/06-整理入库.md b/06-整理入库.md new file mode 100644 index 0000000..c2ed23a --- /dev/null +++ b/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 中验证: + - 艺术家与专辑列表的完整性 + - 歌曲播放的正常性 + - 封面显示的正确性 + - 歌词显示的正确性 +- 验证升级决策的合理性 +- 抽查合并前后的文件完整性 + +**安全性测试**: +- 验证备份机制(如果启用) +- 测试合并失败后的回滚能力 +- 测试主库数据不会因合并失败而损坏 diff --git a/07-全局配置_路径配置.md b/07-全局配置_路径配置.md new file mode 100644 index 0000000..af72a48 --- /dev/null +++ b/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)` 确保跨平台路径兼容。 diff --git a/08-路径.md b/08-路径.md new file mode 100644 index 0000000..cce6c9f --- /dev/null +++ b/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:"|?*]/`将冒号`:`列为非法字符，但在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路径中的盘符冒号 +- 支持中文路径 +- 提高路径处理的健壮性和安全性 +- 保持与现有系统功能的兼容性 + +这将使后端服务能够在不同操作系统上无缝部署和运行，提高了系统的可移植性和可靠性。通过本次修复案例，我们也积累了宝贵的跨平台路径处理经验，为未来的系统优化奠定了基础。