# agv-simulator

**Repository Path**: linbe8888/agv-simulator

## Basic Information

- **Project Name**: agv-simulator
- **Description**: 仓储 AGV 调度系统（WCS）—— 一套代码适配 6 种仓库形态的生产级调度平台，提供低代码策略编排、AI 智能运维、蓄单池批量调度与热力巷道优先级，驱动潜伏/搬运 AGV 车队全品类任务协同。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-02
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🏭 AGV 仓储 WCS 调度系统

> 面向智能仓储的 WCS（Warehouse Control System）调度平台

![Version](https://img.shields.io/badge/version-v3.4-blue)
![Java](https://img.shields.io/badge/Java-8+-orange)
![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.7-green)
![MySQL](https://img.shields.io/badge/MySQL-8.0-lightgrey)
![License](https://img.shields.io/badge/license-Apache%202.0-brightgreen)

![系统主界面](docs/images/main-ui.png)

---

## 📖 项目简介

**AGV 仓储 WCS 调度系统** —— 一套代码适配多种仓库形态的生产级 WCS 调度平台。

对接上游 WMS 和下游 RCS，实现潜伏/搬运 AGV 车队的任务编排、并发调度与全过程监控。已覆盖标准仓、直运仓、无空架仓等 6 种仓储场景，支持 AI 自然语言运维与低代码策略编排。

```
WMS（仓库管理）── REST ──▶  AGV WCS  ── HTTP ──▶  RCS（机器人控制）
       ◀── 回调通知 ──   编排·调度·监控   ◀── 状态回调 ──
```

### 为什么选择本项目？

| 特性 | 传统方案 | 本系统 |
|------|---------|--------|
| **场景适配** | 一仓一改，代码硬编码 | 6 种内置场景 + Web 切换，无需重启 |
| **策略变更** | 修改 Java 代码，重新部署 | 低代码编排，Step 原子拖拽组合 |
| **运维诊断** | 查日志、写 SQL | AI 自然语言问答，一键系统体检 |
| **车队扩展** | 多处代码修改 | yaml 加一行配置即可 |
| **订单调度** | 逐单即时下发，巷道混乱 | 蓄单池聚集 + 热力巷道优先级 |

---

## ✨ 核心亮点

### 🧠 AI 智能运维
内嵌基于 **LLM Function Calling** 的 AI 运维助手，涵盖 **4 大类 22 个工具**：
- 🔍 **状态查询** — 自然语言查询任务、AGV、库位、蓄单池状态
- 🩺 **诊断分析** — 一键系统体检、故障诊断、负载均衡分析
- 📊 **深入分析** — 吞吐量统计、场景 23 维度并排对比
- ⚙️ **配置管理** — 自然语言创建策略、切换场景

> 支持 OpenAI / Azure / 阿里云百炼 / Ollama 等兼容 API

![AI调度助手](docs/images/ai-assistant.png)

### 🔧 低代码策略编排
无需修改代码，通过 Web 页面可视化编排任务策略链：
- 内置 **10 种经典策略**（入库/出库/移库/直运/腾位/补空架...）
- 支持 **自定义策略**，Step 原子自由组合
- 策略与内置 Java 策略平级运行，100% 覆盖所有内置策略能力

![策略链配置](docs/images/strategy-chain.png)

> 可视化配置入库、出库、补空架、移库等策略链，支持开关控制与优先级排序。

![自定义策略列表](docs/images/custom-strategy-list.png)

> 8 个快速预设模板一键创建，也可从零自主编排。

![步骤编排](docs/images/step-editor.png)

> Step 原子自由拖拽组合，支持字段校验与步骤预览。

### 🎯 多场景一键切换
内置 **6 种预设仓库场景**，通过 Web 页面或 API 一键切换，覆盖仓储主流业务模式。

| # | 场景 | 代号 | 入库策略 | 出库策略 | AGV | 特点 |
|---|------|------|----------|----------|-----|------|
| 1 | **标准仓库** | `STANDARD` | 潜伏+搬运（2步） | 搬运+潜伏（2步） | 潜伏+搬运 | 经接驳位，支持腾位入库/补空架出库 |
| 2 | **纯潜伏** | `LATENT_ONLY` | 潜伏直达（1步） | 潜伏直达（1步） | 仅潜伏 | 无搬运AGV参与 |
| 3 | **纯入库** | `INBOUND_ONLY` | 潜伏+搬运（2步） | — | 潜伏+搬运 | 仅入库，自动补空架 |
| 4 | **纯出库** | `OUTBOUND_ONLY` | — | 搬运+潜伏（2步） | 潜伏+搬运 | 仅出库，自动补空架 |
| 5 | **全域直运** | `GLOBAL_DIRECT` | 搬运直达（1步） | 搬运直达（1步） | 仅搬运 | 跳过接驳位，留空架 |
| 6 | **无空架直运** | `DIRECT_CARRY_NO_RACK` | 搬运直达（1步） | 搬运直达（1步） | 仅搬运 | 跳过接驳位，源位不留空架 |

![场景配置](docs/images/scene-config.png)

### 🖥️ 双模操作
- **JavaFX 桌面客户端** — 11 个功能面板，深色主题，实时监控
- **Web 管理后台** — 场景配置、策略编排、场景对比

---

## 🏗️ 系统架构（7 层分层设计）

```
┌─────────────────────────────────────────────────────────────────┐
│                      🖥️ 表现层                                    │
│  JavaFX GUI (11 个面板)  │  Web 管理后台 (4 个页面)                │
├─────────────────────────────────────────────────────────────────┤
│                      🌐 Web 层 (Spring MVC)                      │
│  WmsController  │  RcsController  │  SceneConfigController      │
├─────────────────────────────────────────────────────────────────┤
│                      📋 AOP 切面层                               │
│  ApiLogAspect → 接口请求/响应日志自动记录到 DB（WMS + RCS）         │
├─────────────────────────────────────────────────────────────────┤
│                      ⚙️ 服务层                                   │
│  ┌──────────────┬───────────────────┬──────────────────────────┐│
│  │ WmsTaskService│ TaskPlanStore     │ PositionService          ││
│  │ 任务路由 & 校验│ 计划存储 & 持久化  │ 库位 CRUD & CAS 锁定      ││
│  ├──────────────┼───────────────────┼──────────────────────────┤│
│  │ StepExecutor  │ OrderPoolService  │ AccumulationTimer        ││
│  │ 五阶段执行器  │ 蓄单池管理         │ 蓄单倒计时                ││
│  ├──────────────┼───────────────────┼──────────────────────────┤│
│  │ ActiveChannelMgr│ AutoReplenishScheduler│ WmsCallbackService ││
│  │ 活跃通道选择    │ 自动补空架定时器      │ WMS 回调+重试        ││
│  ├──────────────┼───────────────────┼──────────────────────────┤│
│  │ SceneConfigService│ SceneRouter  │ TaskHistoryService       ││
│  │ 多场景管理       │ 场景路由判断   │ 历史查询                  ││
│  ├──────────────┼───────────────────┼──────────────────────────┤│
│  │ AiService     │ CustomStrategySvc│ ApiLogService            ││
│  │ AI 运维助手    │ 自定义策略管理    │ 接口日志查询              ││
│  └──────────────┴───────────────────┴──────────────────────────┘│
├─────────────────────────────────────────────────────────────────┤
│                   🧩 编排层（策略模式）                            │
│  TaskOrchestrator + StrategyChainFactory + 10种内置策略           │
│  + DynamicCustomStrategy（低代码自定义）                          │
│  SceneRouter → 场景感知路由  │  OrderPoolOrchestrator → 蓄单编排  │
├─────────────────────────────────────────────────────────────────┤
│                   📬 队列层                                      │
│  AgvTaskQueue → 潜伏AGV共享队列 + 搬运AGV共享队列 + 多AGV槽位管理  │
├─────────────────────────────────────────────────────────────────┤
│                   💾 数据层                                      │
│  MySQL 8.0 + MyBatis-Plus → 10 张业务表                          │
└─────────────────────────────────────────────────────────────────┘
```

---

## 🚀 快速开始

### 环境要求

| 依赖 | 版本 |
|------|------|
| JDK | 8+ |
| MySQL | 8.0+ |
| Maven | 3.6+ |

### 步骤

```bash
# 1. 克隆项目
git clone https://gitee.com/ithuameng/agv-simulator.git
cd agv-simulator

# 2. 导入数据库
mysql -u root -p < sql/agv-simulator.sql

# 3. 修改配置
# 编辑 src/main/resources/application.yml，配置数据库连接

# 4. 启动（GUI 模式，启动桌面监控面板）
mvn spring-boot:run

# 或纯后端模式（仅 REST API，适用于服务器部署）
java -jar target/agv-simulator.jar --nogui
```

### 启动后访问

| 地址 | 功能 |
|------|------|
| `http://localhost:12000/` | Web 首页入口 |
| `http://localhost:12000/scene-config.html` | 场景配置管理 |
| `http://localhost:12000/custom-strategy.html` | 自定义策略编排 |
| `http://localhost:12000/scene-compare.html` | 场景差异对比 |
| `http://localhost:12000/actuator/health` | 健康检查 |

---

## 📋 功能详情

### 🚗 多 AGV 车队并发调度

- **共享队列模型**：每种类型 AGV 共享一个 `ConcurrentLinkedDeque` 无锁队列
- **CAS 无锁抢占**：通过 `AtomicBoolean` 实现 AGV 忙闲标记
- **巷道优先调度**：空闲 AGV 优先选择同巷道任务，减少跨区移动
- **防饥饿机制**：保证长时间等待的任务不会被无限期推迟
- **Double-Check 防丢失**：AGV 完成回调时防止 Lost Wake-Up

**加车只需在 `application.yml` 中增加一行配置：**

```yaml
wcs.agv.fleet:
  latent:
    - id: "LATENT-01"
    - id: "LATENT-02"   # 新增一台潜伏AGV
  carry:
    - id: "CARRY-01"
```

### 📦 蓄单池 + 批量编排

系统不逐单即时编排，而是将订单汇入蓄单池，按巷道聚集后批量处理：

```
WMS 持续下发 ──▶ 蓄单池 ──⏱️ 倒计时 ──▶ 批量编排
                    ▲ 新单重置倒计时
                    │
                ┌──────────┐  ┌──────────┐
                │ 巷道A: 3单│  │ 巷道B: 5单│  ...
                └──────────┘  └──────────┘
                      │             │
                 max-active-channels 选最优巷道
                      │
                      ▼
                 逐单编排 → 提交 AGV 队列
```

**核心机制：**
- 倒计时重置避免过早编排
- 活跃通道按订单数降序选择
- try-confirm-rollback 两阶段编排，失败自动回滚
- 单条失败不影响同通道其他订单

![蓄单池调度](docs/images/order-pool.png)

### ⚡ 五阶段步骤执行器

每个任务步骤经过严格的 5 阶段执行，保障数据一致性：

```
Phase 1  前置强校验 → 位置存在性/状态期望/锁定竞争校验
Phase 2  CAS 原子锁定 → 源位/目标位锁定，失败自动回滚
Phase 3  下发 AGV 指令 → 构建 RCS JSON，注入指派 AGV 编号
Phase 4  等待 RCS 回调 → 中间状态更新 + 托盘码持久化
Phase 5  回调处理 → 更新库位状态，自动提交下一步或标记完成
```

**容错能力：**
- 崩溃恢复：启动时自动恢复 EXECUTING 状态的步骤
- 可重入：识别本任务预锁，允许 LOCKED 状态放行
- 部分失败回滚：目标位锁定失败自动释放已锁源位

### 🔁 自动补空架

定时检测入库缓存区空架数量，低于阈值自动生成补空架任务，无需人工干预。

### 📡 WMS/RCS 协议集成

- **WMS → WCS**：REST API 下发入库/出库/移库/取消任务
- **WCS → RCS**：HTTP 下发 AGV 移动指令并接收状态回调
- **WCS → WMS**：任务状态变更主动回调通知，失败自动重试（最多3次）
- **robotId 注入**：编排时不指定 AGV，执行时动态分配空闲 AGV

### 🖥️ JavaFX 桌面监控面板

**11 个功能面板**，深色主题，实时刷新：

| 面板 | 功能 |
|------|------|
| **AiChatPanel** 🆕 | AI 运维助手对话框，自然语言交互 |
| **ControlPanel** | RCS 连接控制、补空架开关、蓄单池开关、场景切换 |
| **TaskMonitorPanel** | 实时任务步骤状态、AGV 车队状态指示 |
| **OrderPoolPanel** | 蓄单池列表、手动编排、订单取消 |
| **PositionManagePanel** | 库位状态可视化（表格+网格双视图） |
| **TaskHistoryPanel** | 历史任务查询、步骤时间线详情 |
| **WmsTaskPanel** | WMS 任务模拟下发 |
| **ApiLogPanel** | 接口调用日志查询 |

![任务历史](docs/images/task-history.png)

### 🌐 Web 管理页面

| 页面 | 路径 | 功能 |
|------|------|------|
| 场景配置 | `/scene-config.html` | 6 种内置场景卡片式展示、CRUD、激活 |
| 自定义策略 | `/custom-strategy.html` | 低代码策略编排、8 个预设模板 |
| 场景对比 | `/scene-compare.html` | 任意两场景 23 维度并排对比，差异高亮 |

---

## 🗄️ 数据库设计

| 表名 | 用途 |
|------|------|
| `t_location` | 库位表（状态机：FREE→HAS_RACK→HAS_RACK_GOODS） |
| `t_task_plan` | 任务计划表 |
| `t_task_step` | 任务步骤表 |
| `t_pooled_order` | 蓄单池订单表 |
| `t_active_channel` | 活跃通道记录表 |
| `t_api_log` | 接口调用日志表（WMS+RCS） |
| `t_wms_callback_retry` | WMS 回调重试记录表 |
| `t_scene_config` | 场景配置表 |
| `t_custom_strategy` | 自定义策略表 |
| `t_task_trace` | 任务全链路追踪表 |
| `sequence` | 序列号生成表 |

---

## ⚙️ 核心配置

```yaml
# 服务端口
server.port: 12000

# 多 AGV 车队（核心）
wcs.agv.fleet:
  latent:
    - id: "LATENT-01"
    - id: "LATENT-02"
  carry:
    - id: "CARRY-01"

# 多场景模式
wcs.scene:
  enabled: true
  default-scene: STANDARD

# AI 助手（可选，不配置则 AI 面板不可用）
agv.ai:
  enabled: true
  base-url: https://api.openai.com/v1    # 支持 OpenAI / 阿里云百炼 / Ollama
  api-key: sk-xxxxxxxx
  model: gpt-3.5-turbo
  timeout: 30
  max-history-rounds: 10

# RCS 连接（开发调试时可关闭）
rcs:
  enabled: false
  ip: 192.168.1.112
  port: 18888

# WMS 回调
wms.callback:
  enabled: false
  retry-enabled: true
  max-retries: 3

# 数据库
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/agv-simulator?useUnicode=true&characterEncoding=utf8
    username: root
    password: your_password
```

---

## 📁 项目结构

```
agv-simulator/
├── sql/
│   └── agv-simulator.sql              # 数据库初始化脚本（DDL + 初始数据）
├── docs/
│   ├── WMS接口文档.html               # WMS 接口规范
│   └── RCS接口文档.html               # RCS 接口规范
├── src/main/java/com/warehouse/simulator/
│   ├── AgvSimulatorApplication.java   # Spring Boot 启动入口
│   ├── aspect/                        # AOP 切面
│   ├── config/                        # 配置类
│   ├── constant/                      # 常量定义
│   ├── controller/                    # REST 控制器
│   ├── dto/                           # 数据传输对象
│   ├── entity/                        # 数据库实体
│   ├── mapper/                        # MyBatis Mapper
│   ├── model/                         # 领域模型
│   ├── queue/                         # AGV 任务队列
│   ├── scheduler/                     # 定时任务
│   ├── service/                       # 业务服务
│   │   ├── intelligent/              # AI 智能助手（22个Function Calling工具）
│   │   ├── orchestration/            # 编排引擎（10种内置策略+自定义策略）
│   │   ├── pool/                     # 蓄单池管理
│   │   ├── position/                 # 库位管理
│   │   ├── task/                     # 任务执行引擎
│   │   └── wms/                      # WMS 对接服务
│   ├── ui/                           # JavaFX GUI（14个面板+CSS）
│   └── utils/                        # 工具类
└── src/main/resources/
    ├── application.yml                # 全量配置
    └── static/                        # Web 页面
        ├── index.html
        ├── scene-config.html
        ├── custom-strategy.html
        └── scene-compare.html
```

---

## 🛠️ 技术栈

| 层面 | 技术 | 说明 |
|------|------|------|
| 基础框架 | Spring Boot 2.7.18 | 长期支持版本，生态成熟 |
| Java 版本 | Java 8+ | 广泛兼容 |
| ORM | MyBatis-Plus 3.5 | Lambda 条件构造器，简化 CRUD |
| 数据库 | MySQL 8.0 | 关系型数据库 |
| 桌面 GUI | JavaFX 17 (OpenJFX) | 现代桌面 UI，CSS 样式支持 |
| AI/LLM | OpenAI 兼容 API | 支持 OpenAI / Azure / 阿里云百炼 / Ollama |
| HTTP 客户端 | Apache HttpClient 4.5 | RCS 指令下发 + LLM API 调用 |
| 工具库 | Lombok + Hutool 5.6 | 代码简化 + 实用工具 |
| 队列 | ConcurrentLinkedDeque | 无锁高并发队列 |
| 锁机制 | AtomicBoolean / AtomicReference | CAS 无锁抢占 + 场景热切换 |
| 构建工具 | Maven | 项目管理与构建 |

---

## 📐 设计模式与关键技术决策

| 决策 | 理由 |
|------|------|
| **策略模式** | 编排逻辑可扩展，新增场景只需加策略类 |
| **ConcurrentLinkedDeque** | 无锁队列，高并发入队/出队 |
| **AtomicBoolean CAS** | AGV 忙闲标记，无锁抢占 |
| **AtomicReference\<SceneConfig\>** | 场景热切换，线程安全 |
| **try-confirm-rollback** | 编排原子性保证 |
| **Function Calling** | LLM 自主选择+调用工具，实现"观测→诊断→分析→调整"闭环 |
| **双模架构** | Spring Boot 管理 Bean + JavaFX 桌面 GUI，共享同一容器 |

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交修改 (`git commit -m 'feat: add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

---

## 📄 开源协议

本项目采用 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) 协议开源。

---

## 📧 联系方式

如有问题或建议，欢迎通过 Gitee Issues 交流。

---

> **如果这个项目对你有帮助，欢迎点个 Star ⭐**