--- description: 牛只运输管理系统项目结构规范 globs: alwaysApply: true --- # 项目结构规范 ## 项目概述 牛只运输管理系统是一个前后端分离的全栈项目，包含后端 Spring Boot 服务和前端 Vue 3 应用，用于提供完整的牛只运输、检疫、设备监控等管理功能。 ## 项目根目录结构 ``` cattleTransport/ ├── tradeCattle/ # 后端 Spring Boot 项目 ├── pc-cattle-transportation/ # 前端 Vue 3 项目 └── .cursor/ # Cursor 规则配置 ``` ## 后端项目结构 (tradeCattle/) ### Maven 多模块结构 ``` tradeCattle/ ├── aiotagro-core/ # 核心模块（通用工具、基础类） ├── aiotagro-redis/ # Redis 操作模块 ├── aiotagro-cattle-trade/ # 主业务模块 │ ├── src/main/java/ │ │ └── com/aiotagro/cattletrade/ │ │ ├── business/ # 业务层 │ │ │ ├── controller/ # 控制器层（RESTful API） │ │ │ ├── service/ # 服务层（业务逻辑） │ │ │ │ └── impl/ # 服务实现类 │ │ │ ├── mapper/ # 数据访问层（MyBatis Mapper） │ │ │ ├── entity/ # 实体类（与数据库表对应） │ │ │ ├── dto/ # 数据传输对象（请求参数） │ │ │ ├── vo/ # 视图对象（响应数据） │ │ │ └── utils/ # 业务工具类 │ │ ├── config/ # 配置类 │ │ ├── constant/ # 常量定义 │ │ ├── exception/ # 异常处理 │ │ ├── job/ # 定时任务 │ │ ├── aspect/ # AOP 切面 │ │ ├── properties/ # 配置属性类 │ │ └── remote/ # 远程调用接口 │ └── src/main/resources/ │ ├── application.yml # 主配置文件 │ ├── application-dev.yml # 开发环境配置 │ ├── application-demo.yml # 演示环境配置 │ ├── application-prod.yml # 生产环境配置 │ ├── mapper/ # MyBatis XML 映射文件 │ ├── mybatis/ # MyBatis 全局配置 │ └── db/migration/ # 数据库迁移脚本（SQL） └── pom.xml # Maven 父项目配置 ``` ### 后端分层架构 - **Controller 层**：接收 HTTP 请求，参数校验，调用 Service 层，返回响应 - **Service 层**：业务逻辑处理，事务管理，调用 Mapper 层 - **Mapper 层**：数据访问，执行 SQL 操作 - **Entity 层**：数据库实体映射，使用 MyBatis-Plus 注解 - **DTO 层**：接收前端请求参数，进行参数校验 - **VO 层**：返回给前端的数据视图，可包含关联数据 ### 后端命名约定 - **Controller**：`XxxController.java`（如 `DeliveryController.java`） - **Service 接口**：`IXxxService.java`（如 `IDeliveryService.java`） - **Service 实现**：`XxxServiceImpl.java`（如 `DeliveryServiceImpl.java`） - **Mapper 接口**：`XxxMapper.java`（如 `DeliveryMapper.java`） - **Mapper XML**：`XxxMapper.xml`（与 Mapper 接口同名） - **Entity**：`Xxx.java`（如 `Delivery.java`，对应表名 `delivery`） - **DTO**：`XxxDto.java`、`XxxCreateDto.java`、`XxxEditDto.java` - **VO**：`XxxVo.java`（如 `DeliveryLogVo.java`） ## 前端项目结构 (pc-cattle-transportation/) ### Vue 3 + TypeScript 结构 ``` pc-cattle-transportation/ ├── src/ │ ├── api/ # API 接口定义 │ │ ├── common/ # 通用 API │ │ ├── abroad.js # 出境管理 │ │ ├── device.js # 设备管理 │ │ ├── shipping.js # 运输管理 │ │ ├── sys.js # 系统管理 │ │ └── userManage.js # 用户管理 │ ├── assets/ # 静态资源 │ │ ├── icons/svg/ # SVG 图标 │ │ └── images/ # 图片资源 │ ├── components/ # 公共组件 │ │ ├── common/ # 通用组件 │ │ │ ├── searchCustom/ # 自定义搜索组件 │ │ │ └── tableCustom/ # 自定义表格组件 │ │ ├── layout/ # 布局组件 │ │ ├── Editor/ # 富文本编辑器 │ │ ├── Pagination/ # 分页组件 │ │ └── SvgIcon/ # SVG 图标组件 │ ├── directive/ # 自定义指令 │ │ ├── permission/ # 权限指令 │ │ └── common/ # 通用指令 │ ├── plugins/ # 插件配置 │ │ ├── auth.js # 权限认证 │ │ └── cache.js # 缓存管理 │ ├── router/ # 路由配置 │ │ └── index.ts # 路由主文件 │ ├── store/ # Pinia 状态管理 │ │ ├── index.ts # Store 主文件 │ │ ├── user.ts # 用户状态 │ │ └── permission.js # 权限状态 │ ├── styles/ # 全局样式 │ │ └── index.scss # 样式主文件 │ ├── utils/ # 工具函数 │ │ ├── axios.ts # Axios 实例配置 │ │ ├── request.js # 请求封装 │ │ ├── auth.js # 认证工具 │ │ ├── permission.js # 权限工具 │ │ └── validate.js # 表单验证 │ ├── views/ # 页面组件 │ │ ├── shipping/ # 运输管理页面 │ │ │ ├── shippingList.vue # 运输列表 │ │ │ ├── createDeliveryDialog.vue # 创建运单对话框 │ │ │ ├── detailDialog.vue # 详情对话框 │ │ │ └── editDialog.vue # 编辑对话框 │ │ ├── userManage/ # 用户管理页面 │ │ │ ├── driver.vue # 司机管理 │ │ │ ├── vehicle.vue # 车辆管理 │ │ │ └── user.vue # 用户管理 │ │ ├── hardware/ # 硬件设备页面 │ │ ├── entry/ # 数据录入页面 │ │ ├── earlywarning/ # 预警系统页面 │ │ └── system/ # 系统管理页面 │ ├── App.vue # 根组件 │ ├── main.ts # 应用入口 │ └── permission.js # 路由权限控制 ├── public/ # 静态资源（不经过构建） ├── vite.config.ts # Vite 配置 ├── tsconfig.json # TypeScript 配置 ├── package.json # 依赖配置 └── .eslintrc.cjs # ESLint 配置 ``` ### 前端组织规则 - **API 按模块分离**：每个业务模块对应一个 API 文件 - **组件按功能分类**：通用组件放在 `components/common/`，业务组件放在对应的 `views/` 子目录 - **页面与对话框分离**：列表页面与弹窗对话框分开定义（如 `shippingList.vue` 与 `createDeliveryDialog.vue`） - **状态管理按模块**：每个业务模块有独立的 Store 文件 - **工具函数分类**：按功能分类（如 `auth.js`、`permission.js`、`validate.js`） ### 前端命名约定 - **组件文件**：使用 PascalCase 或 camelCase（如 `Pagination/index.vue`、`createDeliveryDialog.vue`） - **页面文件**：使用 camelCase（如 `shippingList.vue`、`driver.vue`） - **API 文件**：使用 camelCase（如 `shipping.js`、`userManage.js`） - **工具文件**：使用 camelCase（如 `axios.ts`、`auth.js`） ## 数据库迁移脚本规范 ### 位置 - 后端项目：`tradeCattle/aiotagro-cattle-trade/src/main/resources/db/migration/` ### 命名约定 - 格式：`alter__.sql` - 示例： - `alter_vehicle_record_code.sql` - 修改车辆表的备案码字段 - `alter_delivery_add_estimated_departure_time.sql` - 添加预计出发时间字段 - `alter_client_logs_latlng.sql` - 扩展经纬度字段长度 ### 脚本规范 - 每个脚本必须以 `USE cattletrade;` 开头 - 包含详细的注释说明变更目的 - 对于已执行的脚本，注释掉 `ALTER TABLE` 语句，保留作为文档 - 提供数据迁移语句（如有必要） ## 配置文件规范 ### 后端配置 - **主配置**：`application.yml` - 包含通用配置和环境切换 - **环境配置**： - `application-dev.yml` - 开发环境（本地数据库） - `application-demo.yml` - 演示环境 - `application-prod.yml` - 生产环境 - **敏感信息**：不要硬编码到配置文件，使用环境变量或配置中心 ### 前端配置 - **Vite 配置**：`vite.config.ts` - 包含代理、插件、别名等 - **环境变量**：`.env`、`.env.development`、`.env.production` - **代理配置**：开发环境代理 `/api` 到后端 `http://127.0.0.1:16200` ## 模块依赖关系 ### 后端模块依赖 ``` aiotagro-cattle-trade (主业务模块) ├── depends on: aiotagro-core (核心模块) └── depends on: aiotagro-redis (Redis 模块) ``` ### 前端模块依赖 - **核心依赖**：Vue 3、Vite、Pinia、Vue Router、Element Plus - **工具依赖**：Axios、Moment.js、ECharts - **地图依赖**：百度地图（vue-baidu-map-3x） - **视频依赖**：@liveqing/liveplayer-v3 ## 文件组织原则 1. **按功能模块组织**：相关的 Controller、Service、Mapper、Entity 放在同一业务包下 2. **保持层次清晰**：严格遵守分层架构，避免跨层调用 3. **避免循环依赖**：Service 之间可以相互调用，但需注意避免循环依赖 4. **分离通用逻辑**：通用工具类放在 `core` 模块，业务工具类放在 `utils` 包 5. **配置与代码分离**：配置文件放在 `resources` 目录，代码放在 `java` 目录 6. **前端组件复用**：通用组件放在 `components/common/`，业务组件就近放置