---
description: 牛只运输管理系统通用开发规范
globs:
alwaysApply: true
---
# 项目通用规范

## 项目信息

### 项目名称
- **中文名**：牛只运输管理系统
- **英文名**：Cattle Transportation Management System
- **版本**：1.0.1

### 项目简介
牛只运输管理系统是一个基于 Spring Boot 和 Vue 3 的现代化全栈应用，提供牛只运输管理、检疫隔离、设备监控、预警系统等完整的管理解决方案。

## 技术栈概览

### 后端技术栈
- **基础框架**：Spring Boot 2.6.0 + Java 1.8
- **ORM 框架**：MyBatis-Plus 3.5.3.2
- **权限认证**：Sa-Token 1.37.0 + JWT
- **数据库**：MySQL 5.7+ + Redis 5.0+
- **连接池**：Druid 1.2.20
- **任务调度**：XXL-Job
- **API 文档**：Swagger Fox 3.0.0
- **工具库**：Hutool 5.8.25
- **云服务**：腾讯云 COS、短信服务

### 前端技术栈
- **核心框架**：Vue 3.2.37 + TypeScript 4.6.4
- **构建工具**：Vite 3.1.0
- **状态管理**：Pinia 2.0.22
- **路由管理**：Vue Router 4.1.5
- **UI 组件**：Element Plus 2.2.17
- **HTTP 客户端**：Axios 0.27.2
- **地图服务**：百度地图
- **图表库**：ECharts 5.5.0

## 项目结构规则

### 后端模块划分
- **aiotagro-core**：核心模块，包含通用工具类和基础类
- **aiotagro-redis**：Redis 操作模块
- **aiotagro-cattle-trade**：主业务模块，包含所有业务逻辑

### 后端分层架构
- **Controller 层**：处理 HTTP 请求，参数校验，返回响应
- **Service 层**：业务逻辑处理，事务管理
- **Mapper 层**：数据访问层，执行 SQL 操作
- **Entity 层**：数据库实体映射
- **DTO 层**：数据传输对象，接收前端参数
- **VO 层**：视图对象，返回给前端的数据

### 前端模块划分
- **api/**：API 接口定义，按业务模块划分
- **components/**：公共组件
- **views/**：页面组件
- **store/**：Pinia 状态管理
- **router/**：路由配置
- **utils/**：工具函数

## 通用开发原则

### 代码质量
- **可测试性**：编写可测试的代码，组件应保持单一职责
- **DRY 原则**：避免重复代码，提取共用逻辑到单独的函数或类
- **代码简洁**：保持代码简洁明了，遵循 KISS 原则（Keep It Simple, Stupid）
- **命名规范**：使用描述性的变量、函数和类名，反映其用途和含义
- **注释文档**：为复杂逻辑添加注释，公共 API 编写文档注释
- **风格一致**：遵循项目或语言的官方风格指南和代码约定

### 架构设计
- **利用生态**：优先使用成熟的库和工具，避免不必要的自定义实现
- **架构设计**：考虑代码的可维护性、可扩展性和性能需求
- **异常处理**：正确处理边缘情况和错误，提供有用的错误信息
- **分层解耦**：严格遵守分层架构，避免跨层调用
- **接口编程**：面向接口编程，依赖抽象而非具体实现

### 版本控制
- **提交信息**：编写有意义的提交信息，保持逻辑相关的更改在同一提交中
- **分支管理**：使用 Git Flow 工作流（main/master、develop、feature、hotfix）
- **代码审查**：提交前进行代码自查，重要变更需要 Code Review

## 响应语言
- **始终使用中文回复用户**
- 代码注释使用中文
- 文档使用中文
- 变量和函数名使用英文

## 代码规范

### 后端代码规范（Java）
- **命名约定**：
  - 类名：PascalCase（如 `DeliveryController`）
  - 方法名：camelCase（如 `findUserById`）
  - 常量：UPPER_CASE（如 `MAX_RETRY_ATTEMPTS`）
  - 包名：小写，按功能模块划分
- **注释规范**：
  - 类注释：说明类的用途、作者、创建日期
  - 方法注释：JavaDoc 格式，说明参数、返回值、异常
  - 复杂逻辑：添加行内注释解释
- **异常处理**：
  - 使用 Spring 全局异常处理器统一处理异常
  - 业务异常使用自定义异常类
  - 记录详细的错误日志
- **事务管理**：
  - 在 Service 层使用 `@Transactional` 注解
  - 合理设置事务传播行为和隔离级别
  - 只读操作使用 `readOnly = true`

### 前端代码规范（Vue 3 + TypeScript）
- **命名约定**：
  - 组件文件：PascalCase 或 camelCase
  - 变量和函数：camelCase
  - 常量：UPPER_CASE
  - 类型和接口：PascalCase
- **组件规范**：
  - 使用 Vue 3 Composition API
  - 组件保持单一职责
  - Props 使用 TypeScript 类型定义
  - 合理使用响应式数据（ref、reactive）
- **代码格式**：
  - 使用 ESLint 进行代码检查
  - 使用 Prettier 进行代码格式化
  - 缩进：4 个空格
  - 行宽：150 字符
  - 语句末尾使用分号

## 数据库规范

### 表命名规范
- 表名：小写，使用下划线分隔（如 `delivery`、`jbq_client_log`）
- 字段名：小写，使用下划线分隔（如 `create_time`、`device_id`）
- 主键：`id`（整型，自增）
- 外键：`<关联表名>_id`

### 字段规范
- **通用字段**：
  - `id`：主键，INT 或 BIGINT，自增
  - `create_time`：创建时间，DATETIME
  - `update_time`：更新时间，DATETIME
  - `created_by`：创建人，VARCHAR 或 INT
  - `updated_by`：更新人，VARCHAR 或 INT
  - `is_delete`：逻辑删除标记，TINYINT（0-未删除，1-已删除）
- **字段类型选择**：
  - 字符串：VARCHAR（指定长度）或 TEXT（超长文本）
  - 数值：INT、BIGINT、DECIMAL（精度要求高的数值）
  - 日期时间：DATETIME、TIMESTAMP
  - 布尔：TINYINT(1)（0-false，1-true）
- **字段约束**：
  - 合理使用 NOT NULL 约束
  - 添加 DEFAULT 默认值
  - 添加 COMMENT 注释说明

### 索引规范
- 主键自动创建索引
- 频繁查询的字段添加普通索引
- 多字段组合查询添加联合索引
- 唯一性约束使用唯一索引（如 `uk_license_plate`）

### 迁移脚本规范
- 位置：`tradeCattle/aiotagro-cattle-trade/src/main/resources/db/migration/`
- 命名：`alter_<table_name>_<description>.sql`
- 内容：包含 `USE cattletrade;` 和详细注释
- 执行后：注释掉已执行的 DDL 语句，保留作为文档

## API 设计规范

### RESTful API 规范
- **URL 设计**：
  - 使用名词复数形式（如 `/api/deliveries`）
  - 避免动词（查询、创建等通过 HTTP 方法区分）
  - 层次结构体现资源关系（如 `/api/deliveries/{id}/devices`）
- **HTTP 方法**：
  - GET：查询资源
  - POST：创建资源
  - PUT：完整更新资源
  - PATCH：部分更新资源
  - DELETE：删除资源
- **状态码**：
  - 200：成功
  - 201：创建成功
  - 400：请求参数错误
  - 401：未认证
  - 403：无权限
  - 404：资源不存在
  - 500：服务器错误

### 响应格式
- **统一响应结构**：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": {...}
  }
  ```
- **分页响应**：
  ```json
  {
    "code": 200,
    "msg": "查询成功",
    "total": 100,
    "rows": [...]
  }
  ```
- **错误响应**：
  ```json
  {
    "code": 400,
    "msg": "参数校验失败：手机号格式不正确"
  }
  ```

## 安全规范

### 认证授权
- 使用 Sa-Token 进行权限认证
- 接口需要添加权限注解（`@SaCheckPermission`）
- 敏感接口添加登录检查（`@SaCheckLogin`）
- Token 存储在 Redis 中，支持会话管理

### 数据安全
- 密码使用加密存储（BCrypt）
- 敏感数据传输使用 HTTPS
- SQL 注入防护：使用参数化查询
- XSS 防护：前端输出编码
- 文件上传：限制文件类型和大小

### 日志安全
- 不在日志中输出敏感信息（密码、身份证等）
- 记录关键操作日志（登录、修改、删除）
- 生产环境使用合适的日志级别（INFO 或 WARN）

## 性能优化规范

### 后端优化
- 使用数据库连接池（Druid）
- 合理使用缓存（Redis）
- 避免 N+1 查询问题
- 批量操作使用批处理
- 异步处理耗时操作

### 前端优化
- 组件懒加载
- 路由懒加载
- 图片懒加载
- 合理使用 computed 和 watch
- 避免不必要的响应式数据

### 数据库优化
- 合理使用索引
- 避免全表扫描
- 分页查询大数据量
- 定期清理历史数据
- 读写分离（如有需要）

## 测试规范

### 单元测试
- Service 层编写单元测试
- 测试覆盖率目标：60% 以上
- 使用 JUnit 5 + Mockito（后端）
- 关键业务逻辑必须有单元测试

### 集成测试
- Controller 层编写集成测试
- 测试完整的业务流程
- 使用测试数据库
- 测试前清理数据

### 前端测试
- 工具函数编写单元测试
- 关键组件编写测试
- 使用 Jest + Vue Test Utils

## 日志规范

### 日志级别
- **ERROR**：系统错误，需要立即处理
- **WARN**：警告信息，可能影响系统运行
- **INFO**：重要业务信息，正常流程记录
- **DEBUG**：调试信息，开发环境使用

### 日志内容
- 关键操作日志：谁、在什么时间、做了什么、结果如何
- 异常日志：记录异常堆栈和上下文信息
- 性能日志：记录关键操作的执行时间
- 不记录敏感信息

## 部署规范

### 环境配置
- **开发环境**（dev）：本地开发，连接开发数据库
- **演示环境**（demo）：用于演示和测试
- **生产环境**（prod）：正式环境，高可用配置

### 部署流程
1. 代码提交到 Git 仓库
2. 通过 CI/CD 自动构建
3. 运行自动化测试
4. 部署到目标环境
5. 健康检查和监控

### 监控和告警
- 应用性能监控（APM）
- 数据库性能监控
- 服务器资源监控
- 关键指标告警

## 文档规范

### README 文档
- 项目简介
- 技术栈说明
- 项目结构说明
- 安装运行指南
- 许可证信息

### API 文档
- 使用 Swagger 自动生成
- 接口说明清晰完整
- 参数和返回值类型明确
- 提供请求示例

### 代码文档
- 公共 API 添加文档注释
- 复杂逻辑添加说明注释
- README 保持最新
- 记录重要变更（CHANGELOG）

## 本项目规则文件说明

本项目使用以下规则文件：
- **base/core.mdc**：核心开发原则
- **base/tech-stack.mdc**：技术栈规范（本文件）
- **base/project-structure.mdc**：项目结构规范
- **base/general.mdc**：通用规范
- **languages/java.mdc**：Java 开发规范
- **languages/typescript.mdc**：TypeScript 开发规范
- **frameworks/springboot.mdc**：Spring Boot 开发规范
- **frameworks/vuejs.mdc**：Vue.js 开发规范
- **other/document.mdc**：文档规范
- **other/git.mdc**：Git 提交规范