347 lines
10 KiB
Plaintext
347 lines
10 KiB
Plaintext
---
|
||
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 提交规范
|