# 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 规则文件，请将关键约束合并到本文件，避免规范冲突。