# my-agv

**Repository Path**: gotfocus/my-agv

## Basic Information

- **Project Name**: my-agv
- **Description**: 实现一个支撑多AGV并发运行的物联网与实时通信平台的后端核心系统。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-05-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AGV物联网实时通信平台后端系统

## 项目简介

AGV物联网实时通信平台后端系统是一个基于Spring Cloud的微服务架构，用于支撑多AGV并发运行的物联网与实时通信平台。该系统提供了设备接入、实时通信、指令下发、状态管理等核心功能。

## 技术栈

- **语言与版本**：Java 8
- **微服务框架**：Spring Cloud Greenwich.SR2（与Spring Boot 2.1.13.RELEASE兼容）
- **服务注册与发现**：Spring Cloud Netflix Eureka
- **配置中心**：Spring Cloud Config
- **API网关**：Spring Cloud Gateway
- **通信协议**：MQTT 3.1.1
- **消息队列**：Apache Kafka
- **数据存储**：MySQL + Redis
- **构建工具**：Maven

## 系统架构

系统采用基于Spring Cloud的微服务架构，包含以下核心服务：

1. **agv-gateway-service**：API网关，负责路由、鉴权、限流
2. **agv-connect-service**：核心连接服务，负责AGV设备的接入、长连接管理、心跳维持、在线状态管理
3. **agv-command-service**：指令下发服务，负责向指定AGV发送控制指令
4. **agv-status-service**：状态处理服务，负责接收、解析、存储AGV上报的状态信息
5. **agv-event-processor-service**：事件处理服务，消费消息队列中的AGV事件，实现业务逻辑的异步解耦

详细架构图请参考 `architecture.md` 文件。

## 核心功能

### 1. AGV设备接入与通信
- 使用Spring Integration集成MQTT Broker（如EMQX、HiveMQ）
- 基于设备唯一标识符的Topic结构：
  - 上行（状态上报）：`/agv/{agvId}/status`
  - 下行（指令下发）：`/agv/{agvId}/command`
  - 心跳：`/agv/{agvId}/heartbeat`
- 实现连接会话管理，在Redis中维护AGV设备的在线状态
- 可靠的心跳机制，AGV定期上报心跳，服务端检测超时并更新在线状态

### 2. 高性能与高并发处理
- 优化JVM参数，合理设置MQTT客户端的连接池
- 对MQTT消息的发布/订阅采用异步非阻塞方式
- 使用CompletableFuture处理多线程场景，避免阻塞主线程
- 对状态上报等高频写操作，采用批量插入优化

### 3. 事件驱动与异步解耦架构
- 当AGV状态更新、指令执行完毕等关键事件发生时，向Kafka发送标准化事件消息
- 事件主题如：`agv-status-changed`, `agv-command-executed`
- agv-event-processor-service订阅这些主题，执行后续业务逻辑，实现系统解耦

### 4. 指令下发与状态上报的可靠性与时序
- 指令下发使用MQTT QoS 1等级，确保至少送达一次
- 为每条指令生成唯一ID，AGV应答时携带此ID，实现指令到达确认
- 在状态上报中，每条消息包含消息序列号或时间戳，由agv-event-processor-service处理时进行顺序校验或幂等处理

## 数据库设计

系统使用MySQL存储持久化数据，Redis存储缓存数据。核心表结构包括：

1. **agv_device**：AGV设备信息
2. **agv_command_log**：AGV指令日志
3. **agv_status_history**：AGV状态历史
4. **connection_session**：连接会话信息

详细表结构请参考 `database-schema.sql` 文件。

## 快速开始

### 1. 环境准备

- JDK 1.8+
- Maven 3.6+
- MySQL 5.7+
- Redis 5.0+
- Kafka 2.2+
- MQTT Broker（如EMQX、HiveMQ）
- Eureka Server

### 2. 数据库初始化

执行 `database-schema.sql` 文件创建数据库和表结构：

```bash
mysql -u root -p < database-schema.sql
```

### 3. 服务启动顺序

1. 启动Eureka Server
2. 启动Kafka
3. 启动MQTT Broker
4. 启动agv-connect-service
5. 启动agv-status-service
6. 启动agv-command-service
7. 启动agv-event-processor-service
8. 启动agv-gateway-service

### 4. 服务配置

各服务的配置文件位于 `src/main/resources/application.yml`，可根据实际环境进行修改。

## 代码结构

系统遵循DDD（领域驱动设计）思想进行模块划分，每个服务内部分为以下层次：

- **api**：对外接口层
- **domain**：领域模型层
- **application**：应用服务层
- **infrastructure**：基础设施层

## 监控与维护

- 使用Spring Boot Actuator暴露健康检查、metrics等端点
- 关键业务逻辑编写单元测试（JUnit 5, Mockito）
- 集成测试使用@SpringBootTest

## 注意事项

1. 确保MQTT Broker、Kafka、Redis、MySQL等服务正常运行
2. 确保Eureka Server正常启动，服务能够正确注册
3. 调整JVM参数以适应高并发场景
4. 根据实际设备数量和消息量调整MQTT连接池和Kafka配置

## 联系方式

如有问题或建议，请联系项目维护人员。