698 lines
17 KiB
Markdown
698 lines
17 KiB
Markdown
# 路径导航、手动充电、小车暂停/恢复运行接口文档
|
||
|
||
## 接口概述
|
||
|
||
**接口名称：** AMR小车控制接口
|
||
**接口描述：** 提供AMR小车的暂停/恢复运行控制、手动发布充电任务和手动下发移动任务（路径导航）功能。在某个场景中选择一个小车，如果该小车正在运行中，可以下发暂停运行指令，将小车置为暂停状态；如果小车是暂停状态，可以下发恢复运行指令，使小车恢复到之前的运行状态；也可以手动为小车发布充电任务（需要小车处于空载状态）；还可以手动为小车下发移动任务，指定小车移动到目标站点
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [1. 暂停小车运行](#1-暂停小车运行)
|
||
- [2. 恢复小车运行](#2-恢复小车运行)
|
||
- [3. 手动发布充电任务](#3-手动发布充电任务)
|
||
- [4. 手动下发小车移动任务](#4-手动下发小车移动任务)
|
||
- [通用规范](#通用规范)
|
||
- [错误处理](#错误处理)
|
||
- [调用示例](#调用示例)
|
||
- [注意事项](#注意事项)
|
||
|
||
---
|
||
|
||
## 1. 暂停小车运行
|
||
|
||
### 接口信息
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| **请求方法** | PUT |
|
||
| **请求路径** | `/amr/{id}/pause` |
|
||
| **接口标识** | pauseAmr |
|
||
| **权限要求** | `amr:vwed_amr:edit` |
|
||
|
||
### 接口描述
|
||
|
||
如果小车正在运行中（`navigationalState` 为 `"driving"`），可以下发暂停运行指令，将小车置为暂停状态。
|
||
|
||
### 请求参数
|
||
|
||
#### 路径参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| id | String | 是 | AMR的ID | `"amr_001"` |
|
||
|
||
#### 请求体参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| sceneId | String | 是 | 场景ID | `"scene_001"` |
|
||
|
||
### 请求示例
|
||
|
||
```json
|
||
PUT /amr/amr_001/pause
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"sceneId": "scene_001"
|
||
}
|
||
```
|
||
|
||
### 响应数据
|
||
|
||
#### 成功响应
|
||
|
||
**HTTP状态码：** 200
|
||
**业务状态码：** 200
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "暂停小车运行成功！",
|
||
"code": 200,
|
||
"result": "暂停小车运行成功！",
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
**参数错误（AMR ID为空）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "AMR ID为空！",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**参数错误（场景ID为空）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "场景ID为空！",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**业务错误（小车不存在、不在线、不是运行状态或指令发送失败）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "暂停小车运行失败！可能是小车不存在、不在线、不是运行状态或指令发送失败，请查看日志获取详细信息。",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
|
||
|
||
---
|
||
|
||
## 2. 恢复小车运行
|
||
|
||
### 接口信息
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| **请求方法** | PUT |
|
||
| **请求路径** | `/amr/{id}/resume` |
|
||
| **接口标识** | resumeAmr |
|
||
| **权限要求** | `amr:vwed_amr:edit` |
|
||
|
||
### 接口描述
|
||
|
||
如果小车是暂停状态（`navigationalState` 为 `"paused"`），可以下发恢复运行指令，使小车恢复到之前的运行状态。
|
||
|
||
### 请求参数
|
||
|
||
#### 路径参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| id | String | 是 | AMR的ID | `"amr_001"` |
|
||
|
||
#### 请求体参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| sceneId | String | 是 | 场景ID | `"scene_001"` |
|
||
|
||
### 请求示例
|
||
|
||
```json
|
||
PUT /amr/amr_001/resume
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"sceneId": "scene_001"
|
||
}
|
||
```
|
||
|
||
### 响应数据
|
||
|
||
#### 成功响应
|
||
|
||
**HTTP状态码：** 200
|
||
**业务状态码：** 200
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "恢复小车运行成功！",
|
||
"code": 200,
|
||
"result": "恢复小车运行成功！",
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
**参数错误（AMR ID为空）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "AMR ID为空！",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**参数错误（场景ID为空）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "场景ID为空！",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**业务错误（小车不存在、不在线、不是暂停状态或指令发送失败）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "恢复小车运行失败！可能是小车不存在、不在线、不是暂停状态或指令发送失败，请查看日志获取详细信息。",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
|
||
|
||
---
|
||
|
||
## 3. 手动发布充电任务
|
||
|
||
### 接口信息
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| **请求方法** | GET |
|
||
| **请求路径** | `/amr/manuallSetCharging/{sceneId}/{amrId}` |
|
||
| **接口标识** | manuallSetCharging |
|
||
| **权限要求** | 无特殊权限要求（或使用默认权限） |
|
||
|
||
### 接口描述
|
||
|
||
手动为指定场景中的小车发布充电任务。**注意：需要进行充电的小车必须是空载状态（`isLoading = false`）**。
|
||
|
||
接口会设置小车的充电标志（`is_need_charge = true`），由调度器算法生成充电任务。
|
||
|
||
### 请求参数
|
||
|
||
#### 路径参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| sceneId | String | 是 | 场景ID | `"scene_001"` |
|
||
| amrId | String | 是 | AMR的ID | `"amr_001"` |
|
||
|
||
### 请求示例
|
||
|
||
```
|
||
GET /amr/manuallSetCharging/scene_001/amr_001
|
||
```
|
||
|
||
### 响应数据
|
||
|
||
#### 成功响应
|
||
|
||
**HTTP状态码：** 200
|
||
**业务状态码：** 200
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "手动发布充电任务成功！",
|
||
"code": 200,
|
||
"result": "手动发布充电任务成功！",
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
**参数错误（场景ID或AMR ID为空）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "场景ID或AMR id为空！",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**业务错误（小车不存在）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "小车不存在！",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**业务错误（小车不是空载状态）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "小车当前不是空载状态，无法发送充电指令！",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**业务错误（场景实例不存在或小车不在场景中）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "手动发布充电任务失败！可能是场景实例不存在或小车不在场景中，请查看日志获取详细信息。",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
|
||
|
||
---
|
||
|
||
## 4. 手动下发小车移动任务
|
||
|
||
### 接口信息
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| **请求方法** | POST |
|
||
| **请求路径** | `/task/manual/move` |
|
||
| **接口标识** | manualMoveTask |
|
||
| **权限要求** | `task:vwed_task:add` |
|
||
|
||
### 接口描述
|
||
|
||
手动为指定场景中的小车下发移动任务，使小车移动到目标站点。接口会自动创建任务、任务块和移动动作，并将任务推送到调度器队列中执行。
|
||
|
||
**注意：** 小车必须满足以下条件才能下发移动任务：
|
||
- 小车必须存在
|
||
- 小车必须在线（`isOnline = 1`）
|
||
- 小车必须开启接单（`isAcceptTask = 1`）
|
||
- 小车当前没有正在执行的任务（`currentTaskName` 和 `curTaskId` 为空）
|
||
- 小车状态必须为空闲（`amrStatus = 0`）
|
||
- 小车必须关联到目标场景
|
||
|
||
### 请求参数
|
||
|
||
#### 请求体参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| sceneId | String | 是 | 场景ID | `"scene_001"` |
|
||
| amrId | String | 是 | AMR的ID | `"amr_001"` |
|
||
| taskName | String | 是 | 任务名称 | `"手动移动任务"` |
|
||
| targetStationName | String | 是 | 目标站点名称 | `"station_001"` |
|
||
| description | String | 否 | 任务描述 | `"手动下发的小车移动任务"` |
|
||
| operator | String | 否 | 操作人，默认为"system" | `"admin"` |
|
||
| priority | Integer | 是 | 任务优先级，范围1-1000，默认500 | `500` |
|
||
|
||
### 请求示例
|
||
|
||
```json
|
||
POST /task/manual/move
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"sceneId": "scene_001",
|
||
"amrId": "amr_001",
|
||
"taskName": "手动移动任务",
|
||
"targetStationName": "station_001",
|
||
"description": "手动下发的小车移动任务",
|
||
"operator": "admin",
|
||
"priority": 500
|
||
}
|
||
```
|
||
|
||
### 响应数据
|
||
|
||
#### 成功响应
|
||
|
||
**HTTP状态码：** 200
|
||
**业务状态码：** 200
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "操作成功",
|
||
"code": 200,
|
||
"result": {
|
||
"taskId": "task_123456",
|
||
"taskBlockId": "block_123456",
|
||
"vwedTaskId": "vwed_task_123456",
|
||
"amrId": "amr_001",
|
||
"amrName": "AMR-001",
|
||
"currentStationName": "station_002",
|
||
"targetStationName": "station_001"
|
||
},
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**响应字段说明：**
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| taskId | String | 创建的任务ID |
|
||
| taskBlockId | String | 创建的任务块ID |
|
||
| vwedTaskId | String | VWED任务ID |
|
||
| amrId | String | 小车ID |
|
||
| amrName | String | 小车名称 |
|
||
| currentStationName | String | 小车当前站点名称 |
|
||
| targetStationName | String | 目标站点名称 |
|
||
|
||
#### 错误响应
|
||
|
||
**参数错误（场景ID为空）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "场景ID不能为空",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**参数错误（AMR ID为空）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "AMR id不能为空",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**参数错误（任务名称为空）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "任务名称不能为空",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**参数错误（目标站点为空）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "目标站点不能为空",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**参数错误（优先级范围错误）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "优先级范围为1-1000",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**业务错误（场景ID不存在）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "场景ID不存在",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**业务错误（小车不存在）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "指定的小车不存在",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**业务错误（小车未上线）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "小车未上线，无法下发任务",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**业务错误（小车未开启接单）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "小车未开启接单，无法下发任务",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**业务错误（小车正在执行任务）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "小车正在执行任务，无法重复下发",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**业务错误（小车状态非空闲）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "小车状态非空闲，暂不能执行新任务",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
**业务错误（小车未关联到目标场景）**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "小车未关联到目标场景，无法调度",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1728547200000
|
||
}
|
||
```
|
||
|
||
|
||
|
||
---
|
||
|
||
## 通用规范
|
||
|
||
### 统一返回结构
|
||
|
||
所有接口均采用统一的返回结构：
|
||
|
||
```json
|
||
{
|
||
"success": boolean, // 操作是否成功
|
||
"message": string, // 提示信息
|
||
"code": number, // 状态码（200表示成功，其他表示失败）
|
||
"result": any, // 业务数据（成功时返回具体数据，失败时为null）
|
||
"timestamp": number // 时间戳
|
||
}
|
||
```
|
||
|
||
### 小车状态说明
|
||
|
||
小车的导航状态（`navigationalState`）可能的值：
|
||
|
||
- `"driving"`：正在运行中
|
||
- `"paused"`：已暂停
|
||
- `"finish"`：已完成/空闲
|
||
|
||
### 操作前提条件
|
||
|
||
**暂停操作前提：**
|
||
- 小车必须存在
|
||
- 小车必须在线（`isOnline = 1`）
|
||
- 小车必须处于运行状态（`navigationalState = "driving"`）
|
||
|
||
**恢复操作前提：**
|
||
- 小车必须存在
|
||
- 小车必须在线（`isOnline = 1`）
|
||
- 小车必须处于暂停状态（`navigationalState = "paused"`）
|
||
|
||
**手动发布充电任务前提：**
|
||
- 小车必须存在
|
||
- 小车必须处于空载状态（`isLoading = false`）
|
||
- 场景实例必须存在
|
||
- 小车必须在场景中
|
||
|
||
**手动下发移动任务前提：**
|
||
- 小车必须存在
|
||
- 小车必须在线（`isOnline = 1`）
|
||
- 小车必须开启接单（`isAcceptTask = 1`）
|
||
- 小车当前没有正在执行的任务（`currentTaskName` 和 `curTaskId` 为空）
|
||
- 小车状态必须为空闲（`amrStatus = 0`）
|
||
- 小车必须关联到目标场景
|
||
|
||
---
|
||
|
||
## 错误处理
|
||
|
||
### 常见错误码
|
||
|
||
| 错误码 | 说明 | 处理建议 |
|
||
|--------|------|----------|
|
||
| 200 | 操作成功 | - |
|
||
| 500 | 操作失败 | 查看错误信息，检查小车状态和日志 |
|
||
|
||
### 错误信息说明
|
||
|
||
- **"AMR ID为空！"**：路径参数中的AMR ID未提供或为空
|
||
- **"场景ID为空！"**：请求体中的场景ID未提供或为空
|
||
- **"暂停小车运行失败！可能是小车不存在、不在线、不是运行状态或指令发送失败，请查看日志获取详细信息。"**：业务逻辑检查失败或指令发送失败
|
||
- **"恢复小车运行失败！可能是小车不存在、不在线、不是暂停状态或指令发送失败，请查看日志获取详细信息。"**：业务逻辑检查失败或指令发送失败
|
||
- **"场景ID或AMR id为空！"**：路径参数中的场景ID或AMR ID未提供或为空
|
||
- **"小车不存在！"**：指定的小车不存在
|
||
- **"小车当前不是空载状态，无法发送充电指令！"**：小车正在载货，无法发布充电任务
|
||
- **"手动发布充电任务失败！可能是场景实例不存在或小车不在场景中，请查看日志获取详细信息。"**：场景实例不存在或小车不在场景中
|
||
- **"场景ID不能为空"**：请求体中的场景ID未提供或为空
|
||
- **"AMR id不能为空"**：请求体中的AMR ID未提供或为空
|
||
- **"任务名称不能为空"**：请求体中的任务名称未提供或为空
|
||
- **"目标站点不能为空"**：请求体中的目标站点未提供或为空
|
||
- **"优先级范围为1-1000"**：请求体中的优先级不在有效范围内
|
||
- **"场景ID不存在"**：指定的场景ID不存在
|
||
- **"指定的小车不存在"**：指定的小车不存在
|
||
- **"小车未上线，无法下发任务"**：小车不在线
|
||
- **"小车未开启接单，无法下发任务"**：小车未开启接单功能
|
||
- **"小车正在执行任务，无法重复下发"**：小车当前有正在执行的任务
|
||
- **"小车状态非空闲，暂不能执行新任务"**：小车状态不是空闲状态
|
||
- **"小车未关联到目标场景，无法调度"**：小车未关联到指定的场景
|
||
|
||
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **权限验证**：
|
||
- 暂停/恢复接口需要 `amr:vwed_amr:edit` 权限
|
||
- 手动发布充电任务接口可能不需要特殊权限
|
||
- 手动下发移动任务接口需要 `task:vwed_task:add` 权限
|
||
|
||
2. **参数校验**：
|
||
- `sceneId` 为必填参数，前端需要进行相应的表单验证
|
||
- AMR ID通过路径参数传递，必须提供有效的AMR ID
|
||
|
||
3. **状态检查**：
|
||
- 暂停操作要求小车必须处于运行状态（`navigationalState = "driving"`）
|
||
- 恢复操作要求小车必须处于暂停状态（`navigationalState = "paused"`）
|
||
- 小车必须在线（`isOnline = 1`）才能执行暂停/恢复操作
|
||
- 手动发布充电任务要求小车必须处于空载状态（`isLoading = false`）
|
||
- 手动下发移动任务要求小车必须在线、开启接单、无在执行任务、状态为空闲，且必须关联到目标场景
|
||
|
||
4. **错误处理**：建议前端对各种错误情况进行友好的提示处理，特别是状态不匹配的情况
|
||
|
||
5. **日志记录**：接口调用会自动记录操作日志，便于问题追踪
|
||
|
||
6. **指令类型**：接口使用 VDA5050 标准的 `pause` 和 `resume` 即时动作类型，需要确保设备支持这些指令类型
|
||
|
||
7. **场景隔离**：接口支持场景ID参数，符合多场景架构设计
|
||
|
||
8. **异步操作**：指令发送是异步的，接口返回成功仅表示指令已发送，不代表小车状态已立即改变。建议前端在操作后适当延迟再查询小车状态
|
||
|
||
9. **手动发布充电任务特殊说明**：
|
||
- 该接口不会直接发送充电指令给小车，而是设置充电标志
|
||
- 调度器算法会检测到充电标志并自动生成充电任务
|
||
- 小车会按照调度器的任务安排前往充电站进行充电
|
||
- 充电任务的执行时间取决于调度器的任务调度策略
|
||
|
||
10. **手动下发移动任务特殊说明**：
|
||
- 该接口会自动创建任务、任务块和移动动作
|
||
- 任务块会自动推送到 Redis 队列中，由调度器调度执行
|
||
- 小车会按照调度器的任务安排移动到目标站点
|
||
- 任务的执行时间取决于调度器的任务调度策略和任务优先级
|
||
- 接口会返回创建的任务ID、任务块ID等信息，可用于后续查询任务状态
|
||
|
||
---
|
||
|
||
|
||
|