mangmang
81977a157e
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.
167 lines
5.6 KiB
Markdown
167 lines
5.6 KiB
Markdown
# 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 规则文件，请将关键约束合并到本文件，避免规范冲突。
|