Improve music processing robustness and workflow UX
Unify safe file-move behavior and richer progress semantics across backend tasks, while upgrading traditional-to-simplified conversion and refining the frontend multi-step panels for clearer execution feedback.
This commit is contained in:
108
优化计划.md
Normal file
108
优化计划.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# 音乐功能优化计划
|
||||
|
||||
> 执行顺序固定：**开发 -> 测试 -> 完成打勾**。
|
||||
> 规则：当前任务未完成前，不进入下一任务。
|
||||
|
||||
## 执行规则（每个任务都遵守）
|
||||
|
||||
- 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 多次切页、繁简真实样本准确率等场景仍需手工回归。
|
||||
Reference in New Issue
Block a user