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