---
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/`，业务组件就近放置
