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.

AGENTS.md

@@ -0,0 +1,166 @@
+# AGENTS 指南（MyTool）
+
+本文件面向在本仓库内工作的自动化 coding agents，目标是快速、安全地完成任务并保持项目一致性。
+
+## 1. 仓库概览
+- `backend/`：Spring Boot 2.7 + Java 8。
+- `frontend/`：Vue 3 + Vite + TypeScript + Element Plus。
+- `docker/`：单容器部署脚本与镜像构建。
+- 生产环境为同源部署：后端托管前端构建产物。
+
+## 2. Cursor / Copilot 规则检查
+- 已检查 `.cursor/rules/`、`.cursorrules`、`.github/copilot-instructions.md`。
+- 当前仓库未发现上述规则文件。
+- 结论：请以本 `AGENTS.md` 作为主要执行规范。
+
+## 3. 构建 / 运行 / Lint / 测试命令
+
+### 3.1 前端（在 `frontend/` 目录执行）
+安装依赖：
+```bash
+npm ci
+```
+本地开发：
+```bash
+npm run dev
+```
+生产构建：
+```bash
+npm run build
+```
+预览构建：
+```bash
+npm run preview
+```
+Lint（当前为占位脚本）：
+```bash
+npm run lint
+```
+说明：当前 `lint` 实际输出 `no linter configured yet`，不是强校验。
+
+### 3.2 后端（在 `backend/` 目录执行）
+编译：
+```bash
+mvn clean compile
+```
+打包：
+```bash
+mvn clean package
+```
+运行服务：
+```bash
+mvn spring-boot:run
+```
+运行全部测试：
+```bash
+mvn test
+```
+运行单个测试类（重点）：
+```bash
+mvn -Dtest=SomeServiceTest test
+```
+运行单个测试方法（重点）：
+```bash
+mvn -Dtest=SomeServiceTest#shouldHandleEdgeCase test
+```
+跳过测试打包（Docker 构建同策略）：
+```bash
+mvn clean package -DskipTests
+```
+
+### 3.3 Docker（在仓库根目录或 `docker/`）
+启动：
+```bash
+cd docker && docker compose up -d --build
+```
+日志：
+```bash
+cd docker && docker compose logs -f
+```
+停止：
+```bash
+cd docker && docker compose down
+```
+
+## 4. 测试现状
+- `backend/src/test` 已有基础测试（如 `FileTransferUtilsTest`、`DedupServiceInternalTest`、`ConvertServiceInternalTest`、`TraditionalFilterServiceTest`、`ProgressStoreTest`）。
+- 前端未配置 Vitest/Jest，暂无 `*.spec.ts` / `*.test.ts`。
+- 新增功能时，优先补后端单测，至少覆盖核心服务分支。
+- 若引入前端测试框架，需同步更新 `package.json` 与本文件命令。
+
+## 5. 后端代码规范（Java / Spring）
+
+### 5.1 分层与职责
+- 根包固定为 `com.music`。
+- 目录分层遵循 `controller` / `service` / `dto` / `config` / `common` / `exception`。
+- Controller 负责参数校验与编排，不写重业务逻辑。
+- Service 负责核心业务流程，异常要转为可读的业务失败信息。
+
+### 5.2 命名规范
+- 类名：`PascalCase`（如 `ConvertService`、`GlobalExceptionHandler`）。
+- 方法/字段：`camelCase`。
+- 常量：`UPPER_SNAKE_CASE`（如 `LOSSLESS_EXTENSIONS`）。
+- DTO 命名：`XxxRequest` / `XxxResponse`。
+
+### 5.3 导入、格式、语言特性
+- 使用显式 import，避免 `*` 通配符导入。
+- 4 空格缩进，K&R 花括号风格，保持与现有代码一致。
+- 保持 Java 8 兼容，不引入高版本语法。
+- 文件编码 UTF-8。
+
+### 5.4 参数校验与类型
+- 接口入参使用 DTO，并配合 `@Valid`、`@NotBlank` 等注解。
+- 业务模式值（如 `copy`/`move`）做显式校验，错误走业务异常。
+- 路径、文件系统相关逻辑先校验再执行，避免抛裸异常到接口层。
+
+### 5.5 错误处理与返回结构
+- 统一返回 `Result<T>`：成功 `Result.success(...)`，失败 `Result.failure(...)`。
+- 业务异常使用 `BusinessException(code, message)`。
+- 全局异常由 `GlobalExceptionHandler` 兜底处理。
+- 不向前端暴露堆栈或底层实现细节，错误信息保持可读。
+- 异步任务失败需通过进度消息体现失败状态与原因。
+
+## 6. 前端代码规范（Vue 3 + TypeScript）
+
+### 6.1 组织与分层
+- 页面主逻辑放在 `src/components/*Tab.vue`。
+- 请求封装放在 `src/api/*.ts`，组件内不要直接拼 axios 细节。
+- WebSocket 逻辑集中在 `src/composables/useWebSocket.ts`。
+- 全局入口保持在 `src/main.ts`，避免散落初始化逻辑。
+
+### 6.2 命名与类型
+- 组件文件使用 `PascalCase.vue`。
+- 组合式函数使用 `useXxx`。
+- TS 接口和类型用 `PascalCase`。
+- 变量和函数用 `camelCase`。
+- 避免 `any`；优先显式接口、联合类型或 `unknown` + 类型收窄。
+
+### 6.3 编码风格
+- 使用 ESM 导入，默认相对路径。
+- 保持单引号、分号、2 空格缩进。
+- 默认使用 `<script setup lang="ts">`。
+- 组件样式默认 `scoped`，仅在必要场景使用 `:deep(...)`。
+
+### 6.4 状态与异常处理
+- 表单对象优先 `reactive`，标量状态优先 `ref`。
+- 接口返回默认遵循后端 `Result<T>`，通过 `src/api/request.ts` 统一解包。
+- 用户可恢复错误通过 `ElMessage.warning/error` 提示。
+- 长任务遵循“WebSocket 实时 + 轮询兜底”模式，注意组件卸载时清理连接与定时器。
+
+## 7. 代理工作约束
+- 变更前先确认影响层次：后端 DTO/Controller/Service 与前端 api/组件是否要同步。
+- 新增后端接口优先沿用 `/api/...` 风格与现有响应结构。
+- 不随意引入新框架或重型依赖（状态管理、UI 库、构建链）。
+- 新增命令、脚本、测试框架时，务必更新本文件。
+- 提交前至少执行受影响模块的构建或测试命令。
+
+## 8. 提交前快速检查
+- 是否保持 `Result<T>` + 统一异常处理链路？
+- 是否保持前后端字段命名和类型一致（尤其进度消息）？
+- 是否避免在组件中堆叠网络协议细节？
+- 是否给出最小可执行验证命令（build/test）？
+- 是否同步更新文档与脚本说明？
+
+---
+
+若后续新增 Cursor/Copilot 规则文件，请将关键约束合并到本文件，避免规范冲突。