MyTool/优化计划.md

音乐功能优化计划

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

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

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

---

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

0. 基线与安全准备

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

1. 去重流程重复处理问题（最高优先）

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

2. 文件移动跨盘容错统一

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

3. 繁简转换输出目录语义统一

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

4. 进度消息模型标准化

• 开发：扩展 ProgressMessage（增加业务字段如 duplicateGroups、albums、tracks 等），减少 success/failed 的语义复用。
• 测试：已补充 ProgressMessageMappingTest，验证 dedup/organize/zhconvert/merge 的结构化字段映射。
• 完成：前端无需“特殊猜字段”后打勾。

5. 任务进度存储清理机制

• 开发：为 ProgressStore 增加完成任务清理策略（TTL 或定时清理）。
• 测试：已补充 ProgressStoreTest，验证正常读取与过期清理行为。
• 完成：验证通过后打勾。

6. 前端 WebSocket/watch 释放治理

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

7. 转码稳定性增强（ffmpeg 预检 + 超时）

• 开发：在 ConvertService 增加 ffmpeg 可用性预检查、单文件超时与错误分类。
• 测试：已补充 ConvertServiceInternalTest 覆盖 ffmpeg 缺失、损坏输入、超时文案分类，并通过全量后端测试。
• 完成：异常处理链路已覆盖并通过测试后打勾。

8. 繁体转换质量提升

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

9. 回归与验收（全功能）

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

---

完成定义（DoD）

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

---

每日打勾模板（可复制）

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

---

当前测试记录（自动化）

• mvn -Dtest=FileTransferUtilsTest test
• mvn -Dtest=DedupServiceInternalTest test
• mvn -Dtest=ProgressStoreTest test
• mvn -Dtest=ZhConvertServiceInternalTest test
• mvn -Dtest=ProgressMessageMappingTest test
• mvn -Dtest=TraditionalFilterServiceTest test
• mvn -Dtest=ConvertServiceInternalTest test
• mvn -Dtest=ConvertServiceInternalTest,TraditionalFilterServiceTest test
• mvn -Dtest=FileTransferUtilsTest,ProgressStoreTest,ZhConvertServiceInternalTest,ProgressMessageMappingTest test
• mvn test
• mvn clean compile
• npm run build

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