diff --git a/.cursor/rules/api-conventions.mdc b/.cursor/rules/api-conventions.mdc new file mode 100644 index 0000000..f8946ac --- /dev/null +++ b/.cursor/rules/api-conventions.mdc @@ -0,0 +1,31 @@ +--- +description: REST API 路由与统一 JSON 返回格式 +globs: backend/routes/**/*.php,backend/app/Http/**/*.php +alwaysApply: false +--- +# API 规范 + +详见 `docs/07-api.md`。 + +## 路由 +- 统一前缀 `/api/v1/`,资源名复数,路由参数优先业务编码。 +- 状态动作:`POST /api/v1/{resource}/{code}/{action}` + +``` +POST /api/v1/inbounds/{inbound_no}/receive +POST /api/v1/outbounds/{outbound_no}/allocate +``` + +- 认证 Sanctum;每个接口都要经过 Policy / Gate 授权,权限码形如 `outbound:allocate`。 +- 列表接口必须分页并使用统一分页格式。 + +## 统一返回 +所有接口通过统一响应工具(如 `App\Support\ApiResponse`)返回,禁止 Controller 自定义结构。 + +```json +{ "success": true, "message": "OK", "data": {} } +{ "success": false, "message": "操作失败", "errors": {} } +``` + +- 输出数据统一经 API Resource 转换,不直接返回 Model。 +- 验证错误、业务异常、授权失败在异常处理器中统一转换为失败格式。 diff --git a/.cursor/rules/database.mdc b/.cursor/rules/database.mdc new file mode 100644 index 0000000..62e4651 --- /dev/null +++ b/.cursor/rules/database.mdc @@ -0,0 +1,26 @@ +--- +description: MySQL 表设计、迁移与索引规范 +globs: backend/database/**/*.php,backend/app/Models/**/*.php,docs/database/** +alwaysApply: false +--- +# 数据库规范 + +详见 `docs/09-database.md`。表结构设计存放在 `docs/database/`(索引 `docs/database/README.md`)。 + +- **设计先行**:先在 `docs/database/` 中设计并确认表结构,再写迁移;迁移与设计文档必须保持一致,改表时同步更新文档。 + +- InnoDB + utf8mb4;所有表有 `created_at`、`updated_at`。 +- 核心业务表必须有 `tenant_code`;业务编码唯一约束包含租户:`UNIQUE (tenant_code, sku_code)`。 +- 重要业务表按需加 `status`、`version`(乐观锁)、`deleted_at`;**不要无脑给所有表加软删除**,流水类事实表禁止软删除与更新。 +- 数量字段使用整数或 `DECIMAL`,禁止 `FLOAT/DOUBLE`;金额使用 `DECIMAL`。 +- 索引围绕实际查询设计,复合索引通常以 `tenant_code` 为最左列;关注 `warehouse_code`、`customer_code`、`sku_code`、`order_no`、`inbound_no`、`outbound_no`、`location_code`、`status`、`created_at`。 +- 迁移必须可回滚(实现 `down()`),已上线的迁移不修改,新增迁移变更。 +- 表名是单数加 `wms_` 前缀(如 `wms_sku`、`wms_stock_log`)。每张表一个 SQL 文件,放在 `docs/database/` 对应领域目录,约定见 `docs/database/00-conventions.md`。 + +```php +// ✅ +$table->string('tenant_code', 32); +$table->string('sku_code', 64); +$table->unique(['tenant_code', 'sku_code']); +$table->index(['tenant_code', 'status', 'created_at']); +``` diff --git a/.cursor/rules/development-workflow.mdc b/.cursor/rules/development-workflow.mdc new file mode 100644 index 0000000..ecfb22a --- /dev/null +++ b/.cursor/rules/development-workflow.mdc @@ -0,0 +1,26 @@ +--- +description: 分阶段开发流程、修改前后检查清单与禁止事项 +alwaysApply: true +--- +# 开发工作方式 + +像资深项目开发人员一样工作,而不是代码生成器。详见 `docs/15-development-workflow.md`、`docs/16-roadmap.md`。 + +## 分阶段 +- 严格按 Phase 1~17 顺序推进(`docs/16-roadmap.md`),不要一次生成整个项目或几百个文件。 +- 每个 Phase 开始前先说明:目标、涉及模块、数据库变化、API 变化、前端变化、测试方案、风险;确认后再实施。 +- 阶段完成后:检查代码 → 数据库 → 运行测试 → API → 前端 → 修复问题,再进入下一阶段。 + +## 修改前 +理解目录 → 搜索已有实现(不重复造)→ 检查数据库结构、相关 API、前端调用 → 再修改。 + +## 修改后 +检查类型、语法、引用、迁移、API、权限、**租户隔离**,并运行相关测试。 + +## 禁止 +- 跳过架构设计;Controller 堆业务;一个 Model 承担所有业务 +- 忽略 `tenant_code`;直接改库存不留流水;不考虑并发库存 +- Python 直接修改核心 WMS 数据;平台逻辑写死进核心订单模型 +- 过早微服务化;没有测试就继续堆功能;随意增加第三方依赖 +- 重复实现 Element Plus / Admin 框架已提供的能力 +- 魔法字符串、硬编码、重复 SQL、跨模块强耦合 diff --git a/.cursor/rules/docker.mdc b/.cursor/rules/docker.mdc new file mode 100644 index 0000000..e938bdb --- /dev/null +++ b/.cursor/rules/docker.mdc @@ -0,0 +1,15 @@ +--- +description: Docker 开发环境规范 +globs: docker-compose*.yml,docker/**,**/Dockerfile +alwaysApply: false +--- +# Docker 开发环境 + +详见 `docs/13-docker.md`。 + +- 根目录**一个** `docker-compose.yml`,不为小模块建立独立 Compose。 +- 服务:php-fpm(PHP 8.4)、nginx、mysql(8)、redis(7)、node(前端开发)、py-service(FastAPI,构建上下文 `py-service/`)。 +- Queue Worker、Scheduler 为独立服务,复用 PHP 镜像。 +- 镜像定义放 `docker/{service}/`;敏感配置经 `.env` 注入,不写入镜像与 Git。 +- 数据卷持久化 MySQL / Redis;端口、密码可通过 `.env` 配置。 +- 第一阶段不引入 Kubernetes,生产方案在 Phase 17 设计。 diff --git a/.cursor/rules/frontend-vue.mdc b/.cursor/rules/frontend-vue.mdc new file mode 100644 index 0000000..bb5f2b9 --- /dev/null +++ b/.cursor/rules/frontend-vue.mdc @@ -0,0 +1,27 @@ +--- +description: Vue 3 + TypeScript + Element Plus 前端规范(pure-admin-thin) +globs: frontend/**/*.vue,frontend/**/*.ts,frontend/**/*.tsx +alwaysApply: false +--- +# 前端规范 + +详见 `docs/10-frontend.md`。 + +## 框架 +- Admin 基于 pure-admin-thin(i18n 分支),复用其 Layout / Router / 权限 / 标签页 / i18n,不重复实现。 +- UI 只用 Element Plus,不引入 Naive UI 等第二套组件库;不重复实现 Element Plus 已有组件。 +- 新增依赖前先确认框架与现有依赖无法满足。 + +## 结构 +- 页面按业务领域放 `src/views/{domain}/`(warehouse、inventory、inbound、outbound 等)。 +- 接口调用统一放 `src/api/{domain}.ts`,通过框架封装的 HTTP 实例,页面内不直接写 axios。 +- 类型放 `src/types/`,状态 / 枚举常量放 `src/constants/`,禁止魔法字符串。 + +## 编码 +- `