Initial setup of project files and directory structure.

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 前端测试
+
+**单元测试**:
+- 测试繁体占比阈值配置的校验
+- 测试处理模式选择的状态管理
+- 测试预览结果的展示格式
+
+**集成测试**:
+- 测试完整的预览流程
+- 测试完整的执行流程
+- 测试转换前后对比展示
+
+**测试数据**:
+- 标准繁体:
+  - 周杰倫 → 周杰伦
+  - 我的歌聲裡 → 我的歌声里
+  - 愛情轉移 → 爱情转移
+- 繁简混合:
+  - 周杰倫的愛情故事 → 周杰伦的爱情故事
+- 多音字与特殊字:
+  - 幹什麼 → 干什么
+  - 後來 → 后来
+- 边界场景:
+  - 纯英文标签(不应改变)
+  - 日文汉字(部分繁体,需谨慎处理)
+  - 空标签或特殊字符
+
+**质量验证**:
+- 对比专业繁简转换工具的结果
+- 人工抽查转换结果,确保无误转
+- 验证不同繁体占比阈值的效果