MyTool/开发文档/04-音乐元数据繁体转简体.md

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 前端测试

单元测试:

• 测试繁体占比阈值配置的校验
• 测试处理模式选择的状态管理
• 测试预览结果的展示格式

集成测试:

• 测试完整的预览流程
• 测试完整的执行流程
• 测试转换前后对比展示

测试数据:

• 标准繁体:
  • 周杰倫 → 周杰伦
  • 我的歌聲裡 → 我的歌声里
  • 愛情轉移 → 爱情转移
• 繁简混合:
  • 周杰倫的愛情故事 → 周杰伦的爱情故事
• 多音字与特殊字:
  • 幹什麼 → 干什么
  • 後來 → 后来
• 边界场景:
  • 纯英文标签(不应改变)
  • 日文汉字(部分繁体,需谨慎处理)
  • 空标签或特殊字符

质量验证:

• 对比专业繁简转换工具的结果
• 人工抽查转换结果,确保无误转
• 验证不同繁体占比阈值的效果