38 lines
3.6 KiB
Markdown
38 lines
3.6 KiB
Markdown
# Repository Guidelines
|
||
|
||
## 项目结构
|
||
仓库分为 `frontend/` 和 `backend/` 两部分。前端是 Vue 3 + Vite，主要代码在 `frontend/src/`：页面在 `src/views/`，通用组件在 `src/components/`，接口封装在 `src/api/`，状态管理在 `src/stores/`，路由在 `src/router/`。后端是 Express + TypeScript，代码在 `backend/src/`，按 `routes/`、`controllers/`、`middleware/`、`utils/` 分层。数据库模型统一在 `backend/prisma/schema.prisma`。部署相关文件在仓库根目录：`docker-compose.yml`、`Dockerfile`、`deploy.sh`。
|
||
|
||
## 构建、运行与开发命令
|
||
首次进入前后端目录分别执行 `npm install`。
|
||
|
||
- `cd frontend && npm run dev`：启动前端开发环境。
|
||
- `cd frontend && npm run build`：执行类型检查并打包前端。
|
||
- `cd backend && npm run dev`：用 `nodemon + ts-node` 启动后端。
|
||
- `cd backend && npm run build`：编译后端到 `dist/`。
|
||
- `cd backend && npm run prisma:generate`：Prisma 模型变更后重建客户端。
|
||
- `cd backend && npm run prisma:migrate`：生成并应用本地数据库迁移。
|
||
- `docker compose up --build`：同时启动 MySQL、后端、前端。
|
||
|
||
## 代码风格与命名
|
||
项目以 TypeScript 为主，现有代码统一使用 2 空格缩进。Vue 组件文件使用 PascalCase，如 `EquipmentForm.vue`；接口、store、工具模块使用语义化名称，如 `equipment.ts`、`storageLocation.ts`。新增功能时，尽量保持前端 API 名称、后端路由、控制器按同一业务域对应，方便排查问题。
|
||
|
||
## 测试与验证
|
||
当前仓库没有现成自动化测试脚本，因此每次改动后至少执行 `frontend` 和 `backend` 的 `npm run build`。涉及接口改动时，还应手动验证对应页面流程，并检查 `GET /api/health`。涉及 Prisma 或数据库结构调整时，额外执行 `npm run prisma:generate`，确认相关增删改查正常。若后续补测试，建议使用 `*.spec.ts` 命名。
|
||
|
||
## 提交与合并请求
|
||
当前 Git 历史很少，只有初始提交，没有强约束格式。建议提交信息使用简短中文，写清“改了什么”，例如：`后端：修复借用记录筛选条件`。Pull Request 需要说明变更范围、验证方式、是否影响数据库或部署；前端页面改动建议附截图，接口或表结构改动要明确标注兼容性影响。
|
||
|
||
## 配置与安全
|
||
不要提交真实密码、数据库连接串或生产环境地址。`DATABASE_URL`、会话密钥、认证模式等应通过环境变量管理。修改 `docker-compose.yml`、认证配置或对外端口时，先确认是否会影响本地联调和线上部署。
|
||
|
||
## Multi-Agent 团队分工
|
||
推荐使用 4 个角色，保持团队小而清晰。
|
||
|
||
- 主控 / 集成代理：负责拆任务、安排子代理、收敛方案、做最终验收；默认可读全仓库，但不要直接承担大批量业务改动。
|
||
- 前端业务代理：只负责 `frontend/src/views/`、`frontend/src/components/`、`frontend/src/api/`、`frontend/src/stores/`、`frontend/src/router/`，处理页面、交互、表单、状态和前端接口联调。
|
||
- 后端业务代理：只负责 `backend/src/routes/`、`backend/src/controllers/`，处理资产、借还、搜索、统计、人员等业务接口。
|
||
- 数据与系统代理：只负责 `backend/prisma/`、`backend/src/middleware/`、`backend/src/utils/`、认证配置、`docker-compose.yml`、`Dockerfile`、`deploy.sh`，处理数据库结构、权限、认证、部署和环境问题。
|
||
|
||
协作时尽量避免跨边界改动：前端代理不直接改 Prisma，后端业务代理不直接动 Docker，数据与系统代理不直接改页面。
|