VWED_server/VWED任务模块接口文档/机器人调度接口文档.md

# 机器人调度接口文档

## 机器人通用动作 (CAgvOperationBp)

本接口用于执行机器人的通用动作操作，包括移动、取放货等。

### 描述

本块用于执行机器人的通用动作，提供了丰富的参数来满足各种场景下的动作需求，如移动到特定位置、携带货物等。

### 输入参数

| 参数名           | 中文名称     | 是否必填 | 类型         | 描述                     |
| --------------- | ------------ | -------- | ------------ | ------------------------ |
| targetSiteLabel | 目标站点名    | 必填     | String       | 目标站点的名称或标识       |
| spin            | 允许随动      | 非必填   | Boolean      | 是否允许机器人在移动中同时进行旋转 |
| adjustInfo      | 调整          | 非必填   | JSONArray    | 机器人精细调整的参数信息 |
|task              |指令          |非必填    | JSONArray    | 机器人执行的动作         |

### 输出参数

| 参数名    | 中文名称 | 类型    | 描述                |
| --------- | -------- | ------- | ------------------- |
| success   | 成功标志 | Boolean | 操作是否成功        |
| message   | 消息     | String  | 操作结果消息        |
| code      | 返回代码 | Number  | 操作结果代码        |
| data      | 数据     | Object  | 返回数据对象        |
| data.taskId | 任务ID  | String  | 生成的任务ID        |

### 调用示例

```json
// 输入参数示例
{
  "targetSiteLabel": "storage_B",
  "postAction": "load",
  "goodsId": "box456",
  "isEndAction": false,
  "max_speed": 1.2,
  "max_wspeed": 0.5,
  "spin": true,
  "adjustInfo": [
    {"type": "position", "x": 0.05, "y": 0.02, "theta": 0.1}
  ]
}

// 成功响应示例
{
  "success": true,
  "message": "机器人移动成功，目标站点: storage_B, 货物ID: box456, 任务ID: TASK20230501002",
  "code": 200,
  "data": {
    "taskId": "TASK20230501002"
  }
}

// 失败响应示例
{
  "success": false,
  "message": "机器人通用动作失败: 机器人当前不可用",
  "code": 503
}
```

## 选择执行机器人 (CSelectAgvBp)

本接口用于从可用机器人中选择一个适合执行任务的机器人。

### 描述

本块用于根据指定条件（优先级、标签、机器人组等）从可用机器人中选择一个最合适的执行任务。

### 输入参数

| 参数名        | 中文名称     | 是否必填 | 类型         | 描述                      |
| ------------- | ------------ | -------- | ------------ | ------------------------- |
| priority      | 优先级       | 非必填   | Long         | 任务优先级，数值越大优先级越高 |
| vehicle       | 指定机器人   | 非必填   | String       | 指定使用的机器人ID        |
| group         | 指定机器人组 | 非必填   | String       | 指定从哪个机器人组中选择  |
| keyRoute      | 关键路径     | 必填     | String       | 机器人需要执行的关键路径  |

### 输出参数

| 参数名         | 中文名称     | 类型     | 描述                |
| -------------- | ------------ | -------- | ------------------- |
| success        | 成功标志     | Boolean  | 操作是否成功        |
| message        | 消息         | String   | 操作结果消息        |
| code           | 返回代码     | Number   | 操作结果代码        |
| data           | 数据         | Object   | 返回数据对象        |
| data.agvId     | 选出的机器人 | String   | 选择的机器人ID      |

### 调用示例

```json
// 输入参数示例
{
  "priority": 10,
  "tag": "heavy_load",
  "group": "warehouse_robots",
  "keyRoute": "warehouse_to_shipping",
  "keyGoodsId": "pallet123",
  "mapfPriority": 2
}

// 成功响应示例
{
  "success": true,
  "message": "从机器人组 warehouse_robots 选择机器人成功: AGV001",
  "code": 200,
  "data": {
    "agvId": "AGV001"
  }
}

// 失败响应示例
{
  "success": false,
  "message": "选择执行机器人失败: 没有符合条件的可用机器人",
  "code": 404
}
```

## 获取机器人位置 (VehicleStationBp)

本接口用于获取指定机器人的当前位置和上一个位置信息。

### 描述

本块用于查询指定机器人ID的当前位置和上一个位置，可用于监控机器人状态或位置变化。

### 输入参数

| 参数名   | 中文名称   | 是否必填 | 类型         | 描述             |
| -------- | ---------- | -------- | ------------ | ---------------- |
| vehicle  | 指定机器人 | 必填     | String       | 要查询的机器人ID |

### 输出参数

| 参数名         | 中文名称 | 类型    | 描述                |
| -------------- | -------- | ------- | ------------------- |
| success        | 成功标志 | Boolean | 操作是否成功        |
| message        | 消息     | String  | 操作结果消息        |
| code           | 返回代码 | Number  | 操作结果代码        |
| data           | 数据     | Object  | 返回数据对象        |
| data.station   | 当前位置 | String  | 机器人当前所在位置  |
| data.lastStation | 上次位置 | String  | 机器人上一个所在位置 |

### 调用示例

```json
// 输入参数示例
{
  "vehicle": "AGV001"
}

// 成功响应示例
{
  "success": true,
  "message": "获取机器人 AGV001 位置成功，当前位置: station_C, 上次位置: station_A",
  "code": 200,
  "data": {
    "station": "station_C",
    "lastStation": "station_A"
  }
}

// 失败响应示例
{
  "success": false,
  "message": "获取机器人位置失败: 机器人ID不存在",
  "code": 404
}
```

## 获取机器人电量 (GetBatteryLevelBp)

本接口用于获取指定机器人的当前电量水平。

### 描述

本块用于查询指定机器人ID的当前电量水平，可用于监控机器人的电量状态，以便及时充电或调度管理。

### 输入参数

| 参数名   | 中文名称   | 是否必填 | 类型         | 描述             |
| -------- | ---------- | -------- | ------------ | ---------------- |
| vehicle  | 机器人ID   | 必填     | String       | 要查询的机器人ID |

### 输出参数

| 参数名             | 中文名称 | 类型    | 描述                |
| ------------------ | -------- | ------- | ------------------- |
| success            | 成功标志 | Boolean | 操作是否成功        |
| message            | 消息     | String  | 操作结果消息        |
| code               | 返回代码 | Number  | 操作结果代码        |
| data               | 数据     | Object  | 返回数据对象        |
| data.batteryLevel  | 电量     | Double  | 机器人当前电量水平，范围0-1，表示0-100%  |

### 调用示例

```json
// 输入参数示例
{
  "vehicle": "AGV002"
}

// 成功响应示例
{
  "success": true,
  "message": "获取机器人 AGV002 电量成功，当前电量: 85.5%",
  "code": 200,
  "data": {
    "batteryLevel": 0.855
  }
}

// 失败响应示例
{
  "success": false,
  "message": "获取机器人电量失败: 机器人ID不存在",
  "code": 404
}
```

## 获取机器人PGV码 (GetPGVCodeBp)

本接口用于获取机器人的PGV码信息，用于定位和导航。

### 描述

本块用于获取指定机器人ID的PGV码信息，PGV码用于机器人的精确定位和导航，通过查询可以确定机器人是否正确识别到二维码信息。

### 输入参数

| 参数名   | 中文名称   | 是否必填 | 类型         | 描述             |
| -------- | ---------- | -------- | ------------ | ---------------- |
| vehicle  | 机器人ID   | 必填     | String       | 要查询的机器人ID |

### 输出参数

| 参数名          | 中文名称     | 类型    | 描述                |
| --------------- | ------------ | ------- | ------------------- |
| success         | 成功标志     | Boolean | 操作是否成功        |
| message         | 消息         | String  | 操作结果消息        |
| code            | 返回代码     | Number  | 操作结果代码        |
| data            | 数据         | Object  | 返回数据对象        |
| data.codeInfo   | 二维码信息   | Boolean | 机器人是否识别到有效的PGV码 |

### 调用示例

```json
// 输入参数示例
{
  "vehicle": "AGV003"
}

// 成功响应示例
{
  "success": true,
  "message": "获取机器人 AGV003 PGV码成功，二维码信息: 有效",
  "code": 200,
  "data": {
    "codeInfo": true
  }
}

// 失败响应示例
{
  "success": false,
  "message": "获取机器人PGV码失败: 无法连接到机器人",
  "code": 503
}
```