# 音乐功能优化发布说明（草案）

## 1. 本次优化范围

- 去重：修复 MD5 + 元数据双策略下重复处理同一文件问题。
- 文件移动：统一跨盘容错（`move` 失败自动回退 `copy + delete`）。
- 繁简转换：统一“输出目录不为空”行为说明为“移动到输出目录后再修改”。
- 进度模型：新增结构化进度字段，减少 `success/failed` 语义复用。
- 进度缓存：增加 TTL 过期清理，避免长期堆积。
- 前端任务页：修复 WebSocket 连接切换时 watch 释放不完整问题。
- 转码稳定性：增加 ffmpeg 预检查、单文件超时与错误分类。
- 繁简质量：扩充常见繁简映射字典。

## 2. 兼容性说明

- `ProgressMessage` 保留 `success/failed` 老字段，前端优先读取新字段，兼容历史逻辑。
- API 路径与任务启动入参结构未变（`/api/*/start` 仍保持一致）。

## 3. 可能感知到的行为变化

- 去重任务在双策略场景下，重复文件不再被重复搬运，失败噪声明显降低。
- 跨盘移动相关任务（汇聚/整理/入库/去重/繁简输出）在跨分区下成功率更高。
- 繁简执行模式且指定输出目录时，文件会移动到输出目录，不再描述为“复制副本”。
- 合并任务前端不再从文案解析升级数量，而是读取结构化字段。

## 4. 风险与回滚点

- 进度字段新增后，若第三方客户端仅依赖旧字段，应确认兼容映射。
- 文件移动回退为 `copy + delete` 时，极端情况下可能受磁盘空间影响。
- 繁简映射字典扩展后，个别专有名词可能需要人工复核。

## 5. 验证建议（发布前）

- 后端：`mvn test`、`mvn clean compile`
- 前端：`npm run build`
- 手工回归：
  - 双策略去重（MD5+元数据）
  - 跨盘移动（源/目标分区不同）
  - 繁简预览/执行（输出目录空/非空）
  - 四个任务页反复切换与重置，确认无重复消息