211 lines
10 KiB
Plaintext
211 lines
10 KiB
Plaintext
---
|
||
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_<table_name>_<description>.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/`，业务组件就近放置
|