---
description: 牛只运输管理系统技术栈规范
globs:
alwaysApply: true
---
# 技术栈规范

## 项目技术栈总览

本项目采用前后端分离架构，使用现代化技术栈构建企业级应用。

## 后端技术栈 (tradeCattle/)

### 核心框架
- **Spring Boot** 2.6.0 - 应用基础框架
- **Java** 1.8 - 编程语言
- **Maven** - 项目构建和依赖管理

### 数据持久层
- **MyBatis-Plus** 3.5.3.2 - ORM 框架，基于 MyBatis 增强
- **Druid** 1.2.20 - 阿里巴巴数据库连接池
- **MySQL** 5.7+ - 关系型数据库
- **Redis** 5.0+ - 缓存和会话存储

### 权限认证
- **Sa-Token** 1.37.0 - 轻量级权限认证框架
  - 支持多种登录方式
  - 整合 Redis 会话存储
  - 整合 JWT 令牌
- **JWT (jjwt)** 0.9.1 - JSON Web Token 实现

### 任务调度
- **XXL-Job** - 分布式任务调度平台
- **Spring @Scheduled** - Spring 内置定时任务

### API 文档
- **Swagger Fox** 3.0.0 - 在线 API 文档和调试工具
- **OpenAPI** - API 规范

### 工具库
- **Hutool** 5.8.25 - Java 工具类库
- **Commons IO** 2.13.0 - Apache IO 工具
- **Fastjson2** 2.0.43 - JSON 解析器
- **Apache POI** 4.1.2 - Excel 操作工具
- **Velocity** 2.3 - 模板引擎（代码生成）

### 云服务集成
- **腾讯云 COS** 5.6.89 - 对象存储服务
- **腾讯云 SDK** 3.1.423 - 腾讯云 Java SDK
- **腾讯云短信** - 短信通知服务

### 其他依赖
- **Lombok** - 简化 Java Bean 代码
- **transmittable-thread-local** 2.14.4 - 线程间参数传递
- **bizlog-sdk** 3.0.6 - 业务日志记录
- **Retrofit** 2.2.18 - HTTP 客户端（远程调用）
- **oshi-core** 6.4.11 - 系统信息获取
- **UserAgentUtils** 1.21 - 浏览器和系统识别

### 开发工具
- **Spring Boot DevTools** - 热部署
- **MyBatis-Plus Generator** 3.5.1 - 代码生成器
- **FreeMarker** - 模板引擎（代码生成）

## 前端技术栈 (pc-cattle-transportation/)

### 核心框架
- **Vue** 3.2.37 - 渐进式 JavaScript 框架
- **TypeScript** 4.6.4 - JavaScript 超集，类型安全
- **Vite** 3.1.0 - 下一代前端构建工具

### 状态管理和路由
- **Pinia** 2.0.22 - Vue 3 官方状态管理库
- **pinia-plugin-persist** 1.0.0 - Pinia 持久化插件
- **Vue Router** 4.1.5 - Vue 官方路由管理器

### UI 组件库
- **Element Plus** 2.2.17 - Vue 3 企业级 UI 组件库
- **@element-plus/icons-vue** 2.3.1 - Element Plus 图标
- **WindiCSS** 3.5.6 - 按需原子化 CSS 框架

### HTTP 客户端
- **Axios** 0.27.2 - 基于 Promise 的 HTTP 客户端
- **nprogress** 0.2.0 - 顶部进度条

### 地图服务
- **vue-baidu-map-3x** 1.0.38 - 百度地图 Vue 3 组件
- **vue3-baidu-map** 1.0.0 - 百度地图集成

### 富文本和视频
- **@wangeditor/editor** 5.1.23 - 富文本编辑器
- **@wangeditor/editor-for-vue** 5.1.12 - WangEditor Vue 3 集成
- **@liveqing/liveplayer-v3** 3.7.30 - 视频播放器
- **longze-vue3-video-player** 1.1.7 - Vue 3 视频播放器

### 数据可视化
- **ECharts** 5.5.0 - 数据可视化图表库
- **vue-chartjs** 5.3.0 - Vue Chart.js 封装

### 工具库
- **@vueuse/core** 10.10.0 - Vue Composition API 工具集
- **moment** 2.30.1 - 日期时间处理
- **js-cookie** 3.0.5 - Cookie 操作
- **mitt** 3.0.1 - 事件总线
- **qrcode** 1.5.4 - 二维码生成
- **file-saver** 2.0.5 - 文件下载
- **vue3-json-viewer** 2.2.2 - JSON 可视化
- **vue3-print-nb** 0.1.4 - 打印功能
- **vue-draggable-plus** 0.5.2 - 拖拽功能
- **element-china-area-data** 6.1.0 - 中国省市区数据

### 开发工具
- **ESLint** 8.57.0 - 代码检查工具
- **Prettier** 2.7.1 - 代码格式化工具
- **TypeScript ESLint** 5.38.1 - TypeScript 代码检查
- **Vue TSC** 0.40.4 - Vue TypeScript 编译器

### 构建插件
- **unplugin-auto-import** 0.11.2 - 自动导入 API
- **unplugin-vue-components** 0.22.7 - 组件自动导入
- **vite-plugin-svg-icons** 2.0.1 - SVG 图标集成
- **vite-plugin-windicss** 1.9.3 - WindiCSS 插件

### Git 提交规范
- **commitizen** 4.2.5 - Git 提交规范化工具
- **cz-customizable** 7.0.0 - 自定义提交规范
- **@commitlint/cli** 17.1.2 - 提交信息检查
- **@commitlint/config-conventional** 17.1.0 - 常规提交规范

### 样式预处理
- **Sass** 1.55.0 - CSS 预处理器
- **Less** 4.1.3 - CSS 预处理器

## 开发环境要求

### 后端开发环境
- **JDK** 1.8 或更高版本
- **Maven** 3.6+ 
- **MySQL** 5.7+
- **Redis** 5.0+
- **IDE**：IntelliJ IDEA / Eclipse

### 前端开发环境
- **Node.js** 16.0.0 或更高版本
- **Yarn** 1.22.0+ 或 pnpm 7.0.0+
- **IDE**：VS Code / WebStorm

### 数据库工具
- **Navicat** / **DataGrip** / **MySQL Workbench**

## 部署环境

### 生产环境配置
- **服务器**：Linux (CentOS 7+ / Ubuntu 18.04+)
- **Web 服务器**：Nginx (反向代理和静态资源)
- **应用服务器**：Spring Boot 内置 Tomcat
- **数据库**：MySQL 5.7+ (主从配置)
- **缓存**：Redis 5.0+ (集群或哨兵模式)

### 部署端口
- **后端端口**：16200
- **前端端口**：8080 (开发) / 80/443 (生产)
- **上下文路径**：`/api` (后端)

## 技术选型原则

1. **稳定性优先**：选择成熟稳定的框架和库
2. **社区活跃**：优先选择社区活跃、文档完善的技术
3. **性能考虑**：选择高性能的组件（如 Druid、MyBatis-Plus）
4. **易维护性**：使用主流技术栈，便于团队协作
5. **安全性**：集成安全认证和授权框架（Sa-Token）
6. **可扩展性**：支持分布式部署和横向扩展

## 技术栈版本管理

- 后端依赖版本统一在父 `pom.xml` 的 `<properties>` 中管理
- 前端依赖版本统一在 `package.json` 中管理
- 定期检查依赖更新和安全漏洞
- 升级依赖前进行充分测试

## 官方文档链接

### 后端技术文档
- Spring Boot: https://spring.io/projects/spring-boot
- MyBatis-Plus: https://baomidou.com/
- Sa-Token: https://sa-token.cc/
- Druid: https://github.com/alibaba/druid
- Hutool: https://hutool.cn/

### 前端技术文档
- Vue 3: https://cn.vuejs.org/
- Vite: https://cn.vitejs.dev/
- Pinia: https://pinia.vuejs.org/zh/
- Element Plus: https://element-plus.org/zh-CN/
- TypeScript: https://www.typescriptlang.org/zh/