204 lines
8.1 KiB
Markdown
204 lines
8.1 KiB
Markdown
# Project Context
|
||
|
||
## Purpose
|
||
|
||
牛只运输管理系统（Cattle Transportation Management System）是一个基于 Spring Boot 和 Vue 3 的现代化全栈应用，旨在为牛只运输过程提供全方位的管理和监控解决方案。
|
||
|
||
系统主要目标：
|
||
- 提供完整的牛只运输管理功能，包括运单管理、运输计划、路线规划等
|
||
- 实现检疫隔离管理，支持检疫记录、隔离状态监控、检疫证书管理
|
||
- 提供硬件设备监控能力，包括设备状态监控、数据采集、告警管理
|
||
- 构建预警系统，实现实时监控预警、异常情况报警、预警规则配置
|
||
- 支持用户权限管理、系统配置、日志管理等系统管理功能
|
||
|
||
## Tech Stack
|
||
|
||
### Backend (tradeCattle/)
|
||
- **基础框架**：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、短信服务
|
||
|
||
### Frontend (pc-cattle-transportation/)
|
||
- **核心框架**：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
|
||
- **地图服务**：百度地图（vue-baidu-map-3x）
|
||
- **图表库**：ECharts 5.5.0
|
||
|
||
## Project Conventions
|
||
|
||
### Code Style
|
||
|
||
#### Backend (Java)
|
||
- **命名约定**：
|
||
- 类名：PascalCase（如 `DeliveryController`）
|
||
- 方法名：camelCase（如 `findUserById`）
|
||
- 常量：UPPER_CASE（如 `MAX_RETRY_ATTEMPTS`）
|
||
- 包名：小写，按功能模块划分
|
||
- **注释规范**：
|
||
- 类注释：说明类的用途、作者、创建日期
|
||
- 方法注释：JavaDoc 格式，说明参数、返回值、异常
|
||
- 复杂逻辑：添加行内注释解释
|
||
- **代码格式**：使用 4 个空格缩进，遵循 Java 官方代码风格
|
||
|
||
#### Frontend (TypeScript/Vue)
|
||
- **命名约定**：
|
||
- 组件文件：PascalCase 或 camelCase
|
||
- 变量和函数：camelCase
|
||
- 常量：UPPER_CASE
|
||
- 类型和接口：PascalCase
|
||
- **组件规范**：
|
||
- 使用 Vue 3 Composition API
|
||
- 组件保持单一职责
|
||
- Props 使用 TypeScript 类型定义
|
||
- **代码格式**：使用 4 个空格缩进，行宽 150 字符，语句末尾使用分号
|
||
|
||
### Architecture Patterns
|
||
|
||
#### Backend Architecture
|
||
- **分层架构**：严格遵守 Controller → Service → Mapper 分层
|
||
- Controller 层：处理 HTTP 请求，参数校验，返回响应
|
||
- Service 层：业务逻辑处理，事务管理
|
||
- Mapper 层：数据访问层，执行 SQL 操作
|
||
- **模块划分**：
|
||
- `aiotagro-core`：核心模块，包含通用工具类和基础类
|
||
- `aiotagro-redis`：Redis 操作模块
|
||
- `aiotagro-cattle-trade`：主业务模块，包含所有业务逻辑
|
||
- **数据传输对象**：
|
||
- Entity：数据库实体映射
|
||
- DTO：接收前端请求参数
|
||
- VO：返回给前端的数据视图
|
||
|
||
#### Frontend Architecture
|
||
- **组件化开发**：按功能模块组织组件
|
||
- `api/`：API 接口定义，按业务模块划分
|
||
- `components/`：公共组件
|
||
- `views/`：页面组件
|
||
- `store/`：Pinia 状态管理
|
||
- **路由管理**：使用 Vue Router 进行路由配置和权限控制
|
||
- **状态管理**：使用 Pinia 进行全局状态管理
|
||
|
||
### Testing Strategy
|
||
|
||
#### Backend Testing
|
||
- **单元测试**：Service 层编写单元测试，使用 JUnit 5 + Mockito
|
||
- **集成测试**：Controller 层编写集成测试，测试完整业务流程
|
||
- **测试覆盖率目标**：60% 以上
|
||
- **关键业务逻辑**：必须有单元测试
|
||
|
||
#### Frontend Testing
|
||
- **工具函数**：编写单元测试
|
||
- **关键组件**：编写测试
|
||
- **测试工具**：Jest + Vue Test Utils
|
||
|
||
### Git Workflow
|
||
|
||
- **分支策略**：使用 Git Flow 工作流
|
||
- `main/master`：主分支，生产环境代码
|
||
- `develop`：开发分支，集成最新功能
|
||
- `feature/*`：功能分支，开发新功能
|
||
- `hotfix/*`：热修复分支，紧急修复生产问题
|
||
- **提交规范**：
|
||
- 编写有意义的提交信息
|
||
- 保持逻辑相关的更改在同一提交中
|
||
- 遵循约定式提交格式（Conventional Commits）
|
||
- **代码审查**：提交前进行代码自查，重要变更需要 Code Review
|
||
|
||
## Domain Context
|
||
|
||
### 核心业务领域
|
||
|
||
#### 1. 运输管理（Delivery/Shipping）
|
||
- **运单管理**：运单创建、编辑、查询、状态跟踪
|
||
- **运输计划**：运输计划制定、路线规划
|
||
- **车辆管理**：车辆信息管理、车辆备案码管理
|
||
- **司机管理**：司机信息管理、司机资质管理
|
||
- **装车管理**：装车记录、装车状态跟踪
|
||
|
||
#### 2. 检疫隔离管理（Quarantine）
|
||
- **检疫记录**：检疫记录创建、查询、管理
|
||
- **隔离状态监控**：隔离状态跟踪、隔离期限管理
|
||
- **检疫证书**：检疫证书生成、管理、验证
|
||
- **入境检疫**：入境检疫流程管理
|
||
- **出境管理**：出境检疫流程管理
|
||
|
||
#### 3. 硬件设备管理（Hardware/Device）
|
||
- **设备监控**：设备状态监控、设备数据采集
|
||
- **设备类型**：
|
||
- 项圈设备（Collar Device）
|
||
- 耳标设备（Ear Tag Device）
|
||
- 主机设备（Host Device）
|
||
- **设备日志**：设备日志记录、设备告警管理
|
||
- **设备维护**：设备维护记录、设备故障处理
|
||
|
||
#### 4. 预警系统（Early Warning）
|
||
- **实时监控**：实时监控预警、异常情况报警
|
||
- **预警规则**：预警规则配置、预警阈值设置
|
||
- **预警处理**：预警处理跟踪、预警处理记录
|
||
|
||
#### 5. 系统管理（System）
|
||
- **用户管理**：系统用户管理、用户权限管理
|
||
- **角色管理**：角色定义、角色权限配置
|
||
- **菜单权限**：菜单权限管理、权限控制
|
||
- **日志管理**：系统操作日志、业务日志记录
|
||
- **数据录入**：数据录入、数据审核
|
||
|
||
### 核心实体
|
||
|
||
- **Delivery（运单）**：运单号、车牌号、司机、出发地、目的地、状态等
|
||
- **Vehicle（车辆）**：车牌号、备案码、车辆类型、车辆状态等
|
||
- **Driver（司机）**：司机姓名、手机号、驾驶证号、司机状态等
|
||
- **Order（订单）**：买方、卖方、结算方式、约定价格等
|
||
- **Quarantine（检疫）**：检疫记录、检疫证书、检疫状态等
|
||
- **Device（设备）**：设备ID、设备类型、设备状态、设备位置等
|
||
- **User（用户）**：用户账号、密码、角色、权限等
|
||
|
||
## Important Constraints
|
||
|
||
### 技术约束
|
||
- **Java 版本**：必须使用 Java 1.8，不支持更高版本（除非明确升级）
|
||
- **数据库版本**：MySQL 5.7+，不支持 MySQL 8.0 的某些特性
|
||
- **浏览器兼容性**：前端需要支持现代浏览器（Chrome、Firefox、Edge 最新版本）
|
||
- **性能要求**：接口响应时间 < 2 秒，大数据量查询需要分页
|
||
|
||
### 业务约束
|
||
- **数据安全**：敏感数据（密码、身份证等）必须加密存储
|
||
- **权限控制**：所有业务操作需要权限验证，使用 Sa-Token 进行权限控制
|
||
- **数据完整性**：关键业务数据需要事务保证，避免数据不一致
|
||
- **审计要求**：关键操作需要记录操作日志，包括操作人、操作时间、操作内容
|
||
|
||
### 合规约束
|
||
- **数据隐私**：遵守数据隐私保护相关法规
|
||
- **日志保留**：操作日志需要保留一定期限（建议 6 个月以上）
|
||
- **数据备份**：重要数据需要定期备份
|
||
|
||
## External Dependencies
|
||
|
||
### 云服务
|
||
- **腾讯云 COS（对象存储）**：用于文件存储，包括图片、文档等
|
||
- **腾讯云短信服务**：用于发送验证码、通知短信等
|
||
|
||
### 第三方服务
|
||
- **百度地图 API**：用于地图展示、位置定位、路线规划等
|
||
- **XXL-Job**：分布式任务调度平台，用于定时任务管理
|
||
|
||
### 数据库
|
||
- **MySQL**：主数据库，存储业务数据
|
||
- **Redis**：缓存数据库，用于会话存储、缓存数据
|
||
|
||
### API 文档
|
||
- **Swagger Fox**：API 文档生成和调试工具，访问路径：`/swagger-ui.html`
|
||
|
||
### 开发工具
|
||
- **MyBatis-Plus Generator**：代码生成器，用于生成 Entity、Mapper、Service 等
|
||
- **Lombok**：简化 Java Bean 代码，减少样板代码
|