无人拖车对接文档
1. 概述
本文档描述无人拖车系统与威海港 YMS 系统的对接规范，包括消息队列配置、消息格式、状态流转等内容。
2. 技术架构
┌─────────────────┐ RabbitMQ ┌─────────────────┐
│ 无人拖车系统 │ ────────────────────────→ │ YMS 系统 │
│ (Producer) │ 队列: unmanned_DRIVER_ │ (Consumer) │
│ │ status_queue │ │
└─────────────────┘ └─────────────────┘
│
▼
┌───────────────┐
│ Redis │
│ (会话状态存储)│
└───────────────┘3. 队列配置
3.1 RabbitMQ 连接信息
| 配置项 | 值 |
|---|---|
| 主机地址 | 192.168.31.30 |
| 端口 | 5672 |
| 用户名 | admin |
| 密码 | admin |
| Virtual Host | / |
3.2 队列参数
| 配置项 | 值 | 说明 |
|---|---|---|
| Exchange | unmanned_DRIVER_exchange | 直连交换机 |
| Queue | unmanned_DRIVER_status_queue | 状态消息队列 |
| Routing Key | unmanned_DRIVER_status_key | 路由键 |
| Durable | true | 持久化 |
| Auto Delete | false | 不自动删除 |
4. 消息格式
4.1 基础消息结构
所有消息均为 JSON 格式，编码为 UTF-8。
json
{
"terminalName": "UT-001",
"username": "unmanned_system",
"workStatus": "WAITING_FOR_PALLET",
"timestamp": 1715115000000
}4.2 字段说明
| 字段 | 类型 | 必填 | 含义 |
|---|---|---|---|
| terminalName | String | 是 | 无人拖车唯一标识（车号） |
| username | String | 是 | 无人拖车系统用户名 |
| workStatus | String | 是 | 当前作业状态（见 4.3） |
| timestamp | Long | 否 | 消息时间戳（毫秒），不传则由 YMS 系统生成 |
4.3 状态值说明
| 状态值 | 含义 | 触发时机 |
|---|---|---|
WAITING_FOR_PALLET | 等待拉托盘 | 拖车空闲，等待分配托盘任务 |
WAITING_FOR_CONTAINER | 等待正面吊放箱 | 已绑定托盘，到达正面吊位置等待放箱 |
WAITING_FOR_SHIPMENT | 等待装船 | 已完成放箱，等待前往装船位置 |
PENDING | 作业中 | 正在执行运输任务 |
DONE | 已完成 | 完成当前作业，返回等待区 |
4.4 状态流转图
WAITING_FOR_PALLET
│
▼ (分配托盘)
WAITING_FOR_CONTAINER
│
▼ (正面吊放箱完成)
WAITING_FOR_SHIPMENT
│
▼ (装船完成)
DONE
│
▼ (返回等待区)
WAITING_FOR_PALLET5. 交互流程
5.1 拖车上线流程
无人拖车系统 YMS 系统
│ │
│ 发送状态消息 │
│ workStatus=WAITING_FOR_ │
│ PALLET │
│──────────────────────────→│
│ │
│ 注册会话到Redis │
│ │
│ │ 更新在线状态
│ │5.2 作业任务分配
无人拖车系统 YMS 系统 前端
│ │ │
│ │ 分配任务 (STOMP) │
│ │──────────────────────→ │
│ │ │
│ │ 发送任务消息 │
│ 接收任务消息 │ (STOMP /topic/terminal/ │
│←───────────────────────────│ name/{terminalName}) │
│ │ │5.3 状态同步
无人拖车系统 YMS 系统
│ │
│ 状态变更时发送消息 │
│ workStatus=xxx │
│──────────────────────────→│
│ │
│ │ 更新Redis会话状态
│ │
│ │ 推送状态变更到前端
│ │6. 消息示例
6.1 上线消息
json
{
"terminalName": "UT-001",
"username": "unmanned_system",
"workStatus": "WAITING_FOR_PALLET",
"timestamp": 1715115000000
}6.2 前往正面吊位置
json
{
"terminalName": "UT-001",
"username": "unmanned_system",
"workStatus": "WAITING_FOR_CONTAINER",
"timestamp": 1715115060000
}6.3 等待装船
json
{
"terminalName": "UT-001",
"username": "unmanned_system",
"workStatus": "WAITING_FOR_SHIPMENT",
"timestamp": 1715115120000
}6.4 作业完成
json
{
"terminalName": "UT-001",
"username": "unmanned_system",
"workStatus": "DONE",
"timestamp": 1715115180000
}7. YMS 系统反馈
YMS 系统通过 STOMP 协议向无人拖车发送任务指令，无人拖车系统需订阅以下地址：
| 订阅地址 | 说明 |
|---|---|
/topic/terminal/DRIVER | 所有拖车广播消息 |
/topic/terminal/name/{terminalName} | 指定拖车的消息 |
7.1 任务指令格式
json
{
"terminalType": "DRIVER",
"terminalName": "UT-001",
"action": "ASSIGN_CONTAINER",
"cLaneCntrIdList": ["f3e1b8f2-53b1-4b1f-a43f-72e2f7e7f6df"],
"description": "请前往指定位置执行放箱作业",
"timestamp": 1715115000000
}7.2 动作类型说明
| action | 含义 |
|---|---|
ASSIGN_CONTAINER | 分配放箱任务 |
MOVE_CONTAINER | 移箱任务 |
CANCEL_TASK | 取消任务 |
REQUIRE_DRIVER | 叫车指令 |
8. 错误处理
8.1 消息重试
- 消息消费失败时，RabbitMQ 会自动重试
- 超过重试次数后，消息会被移入死信队列
8.2 消息幂等性
YMS 系统保证消息处理的幂等性，同一消息重复处理不会产生副作用。
9. 安全注意事项
- 认证: 无人拖车系统连接 RabbitMQ 需使用专用账号密码
- 消息加密: 生产环境建议启用 TLS 加密
- 权限控制: 队列权限仅限无人拖车系统账号
10. 测试环境
| 配置项 | 值 |
|---|---|
| RabbitMQ 主机 | 192.168.31.30 |
| 端口 | 5672 |
| 测试拖车号 | UT-TEST01, UT-TEST02 |
11. 附录
11.1 无人拖车会话标识规则
- 会话 ID 格式：
unmanned:{terminalName} - 示例：
unmanned:UT-001
11.2 时间格式
所有时间戳均为 Unix 时间戳（毫秒），时区为 UTC+8。
文档版本: v1.0
创建日期: 2026-05-18
维护人: ZhangHL