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

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

**集成测试**:
- 测试完整的预览流程
- 测试完整的执行流程
- 测试转换前后对比展示

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

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