cattleTransportation/openspec/project.md

# 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 代码，减少样板代码