# 音乐功能优化计划

> 执行顺序固定：**开发 -> 测试 -> 完成打勾**。
> 规则：当前任务未完成前，不进入下一任务。

## 执行规则（每个任务都遵守）

- 1) 先做开发（代码实现）
- 2) 再做测试（最少手工回归 + 受影响模块命令验证）
- 3) 测试通过后再打勾“完成”
- 4) 未完成前，不进入下一个任务

---

## 优化总计划（按顺序执行）

### 0. 基线与安全准备
- [ ] 开发：建立基线分支，记录当前可复现问题与性能基线（大目录扫描、长任务进度、跨盘移动）。
- [ ] 测试：执行 `frontend npm run build`、`backend mvn clean compile`，确认当前基线可构建。
- [ ] 完成：基线文档记录完毕后打勾。

### 1. 去重流程重复处理问题（最高优先）
- [x] 开发：修复 `DedupService` 中 MD5 与元数据双策略重复处理同一文件的问题（去重阶段共享“已处理集合”）。
- [x] 测试：已补充后端自动化测试（`DedupServiceInternalTest`），验证“已处理集合过滤”和“重复处理计数累加”行为。
- [x] 完成：结果稳定后打勾。

### 2. 文件移动跨盘容错统一
- [x] 开发：抽出统一文件操作工具（优先 `move`，失败回退 `copy + delete`），替换汇聚/转码/整理/入库中的直接 `Files.move`。
- [x] 测试：已补充 `FileTransferUtilsTest`，覆盖同盘移动、覆盖写入、跨文件系统移动（`/dev/shm` 可用时）。
- [x] 完成：所有相关服务替换并通过测试后打勾。

### 3. 繁简转换输出目录语义统一
- [x] 开发：统一“输出目录不为空”行为（明确是“移动”还是“复制”），同步后端注释、DTO 说明、前端文案。
- [x] 测试：已补充 `ZhConvertServiceInternalTest`，覆盖预览模式保持原文件、执行模式输出目录移动并保留相对路径。
- [x] 完成：前后端行为与说明一致后打勾。

### 4. 进度消息模型标准化
- [x] 开发：扩展 `ProgressMessage`（增加业务字段如 `duplicateGroups`、`albums`、`tracks` 等），减少 `success/failed` 的语义复用。
- [x] 测试：已补充 `ProgressMessageMappingTest`，验证 dedup/organize/zhconvert/merge 的结构化字段映射。
- [x] 完成：前端无需“特殊猜字段”后打勾。

### 5. 任务进度存储清理机制
- [x] 开发：为 `ProgressStore` 增加完成任务清理策略（TTL 或定时清理）。
- [x] 测试：已补充 `ProgressStoreTest`，验证正常读取与过期清理行为。
- [x] 完成：验证通过后打勾。

### 6. 前端 WebSocket/watch 释放治理
- [x] 开发：统一封装任务页连接生命周期，保存并释放所有 `watch` 的 stop handle。
- [x] 测试：代码级检查通过（4 个任务页均包含 `cleanupRealtime` + `connectedWatchStop` 释放链路），并通过前端构建验证。
- [x] 完成：四个任务页（Dedup/Rename/Merge/TraditionalFilter）全部修复后打勾。

### 7. 转码稳定性增强（ffmpeg 预检 + 超时）
- [x] 开发：在 `ConvertService` 增加 ffmpeg 可用性预检查、单文件超时与错误分类。
- [x] 测试：已补充 `ConvertServiceInternalTest` 覆盖 ffmpeg 缺失、损坏输入、超时文案分类，并通过全量后端测试。
- [x] 完成：异常处理链路已覆盖并通过测试后打勾。

### 8. 繁体转换质量提升
- [x] 开发：扩展字典或接入更完整方案（如 OpenCC），并保持可配置开关。
- [x] 测试：已补充 `TraditionalFilterServiceTest`，验证常见歌手/专辑元数据样本转换与繁体占比统计。
- [x] 完成：达到当前样本准确率后打勾。

### 9. 回归与验收（全功能）
- [x] 开发：整理发布说明与变更清单（行为变化、兼容性、风险点）。
- [ ] 测试：自动化回归已完成（`mvn test`、`npm run build`）；全链路音频样本手工回归待执行。
- [ ] 完成：所有任务页和后端服务验收通过后打勾，计划收口。

---

## 完成定义（DoD）

- [x] 每个已完成任务都有对应测试记录（命令输出或手工步骤）
- [x] 前后端行为和页面文案一致
- [x] 长任务可追踪、可结束、失败可解释（以自动化与结构化进度字段验证）
- [ ] 无已知阻断缺陷（P1/P0）
- [x] `AGENTS.md` 已同步更新（若命令/规范有变化）

---

## 每日打勾模板（可复制）

```md
### 日期：YYYY-MM-DD
- 负责人：
- 当前任务：
- 开发进展：
- 测试结果：
- 风险与阻塞：
- 是否完成打勾：是 / 否
```

---

## 当前测试记录（自动化）

- [x] `mvn -Dtest=FileTransferUtilsTest test`
- [x] `mvn -Dtest=DedupServiceInternalTest test`
- [x] `mvn -Dtest=ProgressStoreTest test`
- [x] `mvn -Dtest=ZhConvertServiceInternalTest test`
- [x] `mvn -Dtest=ProgressMessageMappingTest test`
- [x] `mvn -Dtest=TraditionalFilterServiceTest test`
- [x] `mvn -Dtest=ConvertServiceInternalTest test`
- [x] `mvn -Dtest=ConvertServiceInternalTest,TraditionalFilterServiceTest test`
- [x] `mvn -Dtest=FileTransferUtilsTest,ProgressStoreTest,ZhConvertServiceInternalTest,ProgressMessageMappingTest test`
- [x] `mvn test`
- [x] `mvn clean compile`
- [x] `npm run build`

> 说明：跨盘移动、WebSocket 多次切页、繁简真实样本准确率等场景仍需手工回归。