142 lines
6.1 KiB
Markdown
142 lines
6.1 KiB
Markdown
# AGENTS.md
|
||
本文件面向在本仓库中工作的自动化编码代理（agent）。
|
||
目标：在不破坏现有行为的前提下，稳定、可回归地进行开发与维护。
|
||
|
||
## 0. 仓库概览
|
||
- 仓库名：`quick-share`（DataTool - 房间数据传输助手）。
|
||
- 架构：前后端分离。
|
||
- `backend/`：Spring Boot 3.2.5 + Java 17。
|
||
- `frontend/`：Vue 3 + TypeScript + Vite + Pinia + TailwindCSS。
|
||
- 通信约定：
|
||
- REST：`/api/room/**`。
|
||
- WebSocket(STOMP/SockJS)：`/ws`，应用前缀 `/app`，订阅前缀 `/topic`。
|
||
|
||
## 1. 环境与启动
|
||
### 1.1 版本要求
|
||
- Java：17+。
|
||
- Maven：3.8+。
|
||
- Node.js：18+。
|
||
- npm：9+。
|
||
|
||
### 1.2 本地启动（开发）
|
||
- 后端：`cd backend && mvn spring-boot:run`。
|
||
- 前端：`cd frontend && npm install && npm run dev`。
|
||
- 默认地址：
|
||
- 后端 `http://localhost:8080`
|
||
- 前端 `http://localhost:5173`
|
||
|
||
## 2. Build / Lint / Test 命令
|
||
说明：仓库未配置前端 lint/test 脚本；后端使用 Maven 标准测试流程。
|
||
|
||
### 2.1 后端（Maven）
|
||
- 全量编译+测试：`cd backend && mvn clean test`。
|
||
- 全量验证（CI 推荐）：`cd backend && mvn clean verify`。
|
||
- 打包（跳过测试）：`cd backend && mvn clean package -DskipTests`。
|
||
- 运行单个测试类：`cd backend && mvn -Dtest=RoomServiceTest test`。
|
||
- 运行单个测试方法：`cd backend && mvn -Dtest=RoomServiceTest#shouldCreateRoom test`。
|
||
- 故障排查：可追加 `-e`（详细异常）或 `-X`（debug 日志）。
|
||
|
||
### 2.2 前端（Vite + TypeScript）
|
||
- 安装依赖：`cd frontend && npm install`。
|
||
- 开发启动：`cd frontend && npm run dev`。
|
||
- 生产构建：`cd frontend && npm run build`。
|
||
- 预览构建：`cd frontend && npm run preview`。
|
||
- 类型检查：`cd frontend && npx tsc --noEmit`。
|
||
|
||
### 2.3 “单测”现状（重点）
|
||
- 后端：支持 `-Dtest=类名` / `-Dtest=类名#方法名` 精准执行。
|
||
- 前端：当前未安装 Vitest/Jest，且无 `npm test` 脚本。
|
||
- 若任务要求“跑前端单测”，先确认是否已新增测试框架再执行。
|
||
|
||
## 3. 通用开发原则
|
||
- 只做最小必要改动，避免无关重构。
|
||
- 不随意改对外协议字段名（REST/WS JSON）。
|
||
- 优先复用现有 store/service/utils，避免重复造轮子。
|
||
- 前后端联动改动时，保持契约同步（字段、枚举、路径）。
|
||
- 错误处理优先“可读、可定位”，不要静默吞关键异常。
|
||
|
||
## 4. 前端规范（Vue 3 + TypeScript）
|
||
### 4.1 类型与 TS
|
||
- `frontend/tsconfig.json` 已启用 `strict: true`，新增代码必须通过。
|
||
- 禁用 `any`；必要时使用 `unknown` 并做类型收窄。
|
||
- API 响应、消息模型、store 状态优先显式接口定义。
|
||
- 公共类型放在 `frontend/src/types/`（如 `room.ts`）。
|
||
- 类型导入优先 `import type`。
|
||
|
||
### 4.2 组件与状态管理
|
||
- 使用 `script setup lang="ts"`（与现有组件一致）。
|
||
- 组件文件名使用 `PascalCase.vue`。
|
||
- 组合式 API 优先：`ref` / `computed` / `watch`。
|
||
- 跨组件共享状态集中到 Pinia（当前核心在 `wsStore`）。
|
||
- WebSocket 逻辑优先复用 `RoomWsClient` + `wsStore`，避免旁路实现。
|
||
|
||
### 4.3 导入、路径与格式
|
||
- 导入顺序建议：
|
||
1) 第三方依赖。
|
||
2) `@/` 别名模块。
|
||
3) 相对路径模块。
|
||
- 优先使用 `@/` 别名，减少深层 `../../`。
|
||
- 现有 TS/Vue 代码风格：2 空格缩进、单引号、语句末尾分号。
|
||
|
||
### 4.4 命名约定
|
||
- 变量/函数：`camelCase`。
|
||
- 类型/接口：`PascalCase`。
|
||
- 常量：`UPPER_SNAKE_CASE`（阈值、key 前缀等）。
|
||
- 布尔语义命名：`is/has/can/should` 前缀。
|
||
|
||
### 4.5 样式与 UI
|
||
- 样式体系：Tailwind + 少量 CSS 变量（见 `frontend/src/assets/main.css`）。
|
||
- 复用语义色：`primary` / `success` / `danger` / `warning`。
|
||
- 不引入新 UI 框架（除非任务明确要求）。
|
||
- 响应式写法遵循已有断点习惯：`sm` / `md` / `lg`。
|
||
|
||
### 4.6 前端错误处理
|
||
- `fetch` 后必须检查 `res.ok`，失败时给出可理解错误。
|
||
- `catch` 中保留必要诊断信息，同时确保 UI 状态可恢复。
|
||
- 对上传/下载/队列等流程，错误后要维护一致状态（进度、loading、重试入口）。
|
||
|
||
## 5. 后端规范（Spring Boot + Java）
|
||
### 5.1 Java 风格
|
||
- 使用 Java 17 特性时保持克制，优先可读性。
|
||
- 缩进 4 空格；类名 `PascalCase`，成员 `camelCase`，常量 `UPPER_SNAKE_CASE`。
|
||
- DTO/不可变结构优先 `record`（项目已采用）。
|
||
|
||
### 5.2 分层职责
|
||
- `controller`：参数校验、协议转换、状态码。
|
||
- `service`：核心业务规则、状态流转。
|
||
- `config`：框架配置与属性绑定。
|
||
- 避免把复杂业务塞入 Controller。
|
||
|
||
### 5.3 异常与 I/O
|
||
- 参数/状态非法：优先 `IllegalArgumentException` 或明确状态码。
|
||
- I/O 失败：保留异常链，不吞异常。
|
||
- 对外返回结构保持稳定，避免随意改 key。
|
||
- 文件/流操作使用 `try-with-resources` 并处理清理逻辑。
|
||
|
||
### 5.4 并发与状态
|
||
- 房间会话是并发场景，遵循现有并发容器策略（如 `ConcurrentHashMap`）。
|
||
- 共享状态修改必须考虑线程安全与资源释放（离房、断连、文件清理）。
|
||
|
||
## 6. 协议与兼容性
|
||
- 消息结构以 `frontend/src/types/room.ts` 与后端 `MessagePayload` 对齐。
|
||
- 修改消息字段时必须同步更新：
|
||
- 前端类型定义。
|
||
- 前端消息处理分支。
|
||
- 后端发送/接收逻辑。
|
||
- 现有架构约束：文件内容走 HTTP，消息元数据走 WebSocket，不要随意改。
|
||
|
||
## 7. 变更后自检
|
||
- 后端改动：至少执行 `cd backend && mvn test`（或受影响单测）。
|
||
- 前端改动：至少执行 `cd frontend && npm run build` 与 `cd frontend && npx tsc --noEmit`。
|
||
- 文档改动：核对命令、端口、路径、环境变量名是否与仓库一致。
|
||
- 最终确认：未误改协议字段、路由路径、事件类型、配置 key。
|
||
|
||
## 8. Cursor / Copilot 规则同步
|
||
已检查以下位置：
|
||
- `.cursorrules`
|
||
- `.cursor/rules/`
|
||
- `.github/copilot-instructions.md`
|
||
|
||
当前仓库未发现上述文件，因此本 `AGENTS.md` 为主要代理执行规范。
|
||
若后续新增 Cursor/Copilot 规则，请将关键约束并入本文件并保持一致。
|