6.1 KiB
6.1 KiB
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。
- REST：
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 导入、路径与格式
- 导入顺序建议：
- 第三方依赖。
@/别名模块。- 相对路径模块。
- 优先使用
@/别名，减少深层../../。 - 现有 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 规则，请将关键约束并入本文件并保持一致。