453 lines
14 KiB
Markdown
453 lines
14 KiB
Markdown
# 换机器人接口文档
|
||
|
||
本文档描述了VWED系统换机器人功能的API接口，用于在任务执行过程中动态更换执行机器人。
|
||
|
||
## 基础信息
|
||
|
||
- 基础路径：`/api/vwed-task-record`
|
||
- 接口标签：`VWED任务运行记录`
|
||
- 版本：v1.0
|
||
|
||
## 功能概述
|
||
|
||
换机器人功能允许在任务执行过程中更换执行机器人，主要用于以下场景：
|
||
|
||
1. **机器人故障**：当前执行机器人出现硬件或软件故障
|
||
2. **电量不足**：当前机器人电量过低，需要更换到电量充足的机器人
|
||
3. **性能优化**：根据实际情况选择更合适的机器人执行任务
|
||
4. **负载均衡**：优化机器人资源分配，提高系统整体效率
|
||
|
||
该功能支持两种场景：
|
||
- **未载货场景**：机器人尚未携带货物，从原任务中自动提取参数
|
||
- **已载货场景**：机器人已经携带货物，需要指定目标库位和执行动作
|
||
|
||
## 接口清单
|
||
|
||
| 序号 | 接口名称 | 接口路径 | 请求方式 | 接口描述 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 1 | 换机器人 | `/switch-robot/{task_record_id}` | POST | 动态更换任务执行机器人 |
|
||
|
||
---
|
||
|
||
## 接口详情
|
||
|
||
### 1. 换机器人
|
||
|
||
#### 接口说明
|
||
|
||
在任务执行过程中动态更换执行机器人。系统会终止当前任务的所有待执行块，动态添加新的任务块（选择机器人 → 获取库位 → 执行通用动作），并通过调度器实时生效，保持任务连续运行。
|
||
|
||
**核心特性**：
|
||
- ✅ 支持未载货和已载货两种场景
|
||
- ✅ 智能参数提取（未载货时从原任务自动提取）
|
||
- ✅ 实时生效（无需重启任务）
|
||
- ✅ 保持任务ID不变
|
||
- ✅ 完整的操作日志记录
|
||
|
||
#### 请求路径
|
||
|
||
```
|
||
POST /api/vwed-task-record/switch-robot/{task_record_id}
|
||
```
|
||
|
||
#### 路径参数
|
||
|
||
| 参数名 | 类型 | 是否必须 | 描述 |
|
||
| --- | --- | --- | --- |
|
||
| task_record_id | string | 是 | 任务记录ID，必须是正在运行中的任务 |
|
||
|
||
#### 请求头
|
||
|
||
| 参数名 | 类型 | 是否必须 | 描述 |
|
||
| --- | --- | --- | --- |
|
||
| Content-Type | string | 是 | application/json |
|
||
| x-access-token | string | 否 | 系统任务令牌，用于主系统认证 |
|
||
|
||
#### 请求体参数
|
||
|
||
| 参数名 | 类型 | 是否必须 | 描述 |
|
||
| --- | --- | --- | --- |
|
||
| robot_name | string | 否 | 机器人名称（如：AGV_001） |
|
||
| robot_group | string | 否 | 机器人组（如：group_A） |
|
||
| robot_label_group | string | 否 | 机器人标签组（如：label_1） |
|
||
| switch_reason | string | 是 | 更换原因（如：机器人电量不足、机器人故障等） |
|
||
| has_cargo | boolean | 是 | 是否载货，true-已载货，false-未载货 |
|
||
| site_id | string | 条件必填 | 库位ID（已载货时必填，如：AP540） |
|
||
| action | string | 条件必填 | 执行动作（已载货时必填，如：pick、drop） |
|
||
|
||
**参数说明**：
|
||
- `robot_name`、`robot_group`、`robot_label_group` 至少提供一个，用于选择新的机器人
|
||
- 当 `has_cargo=true` 时，`site_id` 和 `action` 为必填项
|
||
- 当 `has_cargo=false` 时，系统会从原任务定义中自动提取 `site_id` 和 `action`
|
||
|
||
#### 响应结果
|
||
|
||
**成功响应**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "换机器人成功(未载货场景)",
|
||
"data": {
|
||
"task_record_id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"switch_reason": "机器人AGV_001电量不足",
|
||
"has_cargo": false,
|
||
"robot_name": "AGV_002",
|
||
"robot_group": "group_A",
|
||
"robot_label_group": "label_1",
|
||
"site_id": "AP154",
|
||
"action": "pick",
|
||
"key_route": "LM532",
|
||
"added_blocks": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应**：
|
||
|
||
1. 任务记录不存在：
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"message": "未找到任务记录 {task_record_id}"
|
||
}
|
||
```
|
||
|
||
2. 任务状态错误：
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "任务状态为 {status},只能对运行中的任务换机器人"
|
||
}
|
||
```
|
||
|
||
3. 任务定义格式错误：
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "任务定义格式不正确"
|
||
}
|
||
```
|
||
|
||
4. 已载货场景参数不足：
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "已载货场景需要提供库位ID和执行动作"
|
||
}
|
||
```
|
||
|
||
5. 系统异常：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "换机器人失败: {错误详情}"
|
||
}
|
||
```
|
||
|
||
#### 响应字段说明
|
||
|
||
| 字段名 | 类型 | 描述 |
|
||
| --- | --- | --- |
|
||
| task_record_id | string | 任务记录ID |
|
||
| switch_reason | string | 更换原因 |
|
||
| has_cargo | boolean | 是否载货 |
|
||
| robot_name | string | 新机器人名称 |
|
||
| robot_group | string | 新机器人组 |
|
||
| robot_label_group | string | 新机器人标签组 |
|
||
| site_id | string | 目标库位ID |
|
||
| action | string | 执行动作（pick/drop/其他） |
|
||
| key_route | string | 关键路径（从原任务提取或使用site_id） |
|
||
| added_blocks | integer | 添加的新任务块数量（固定为1，包含3个子块） |
|
||
|
||
---
|
||
|
||
## 使用场景和示例
|
||
|
||
### 场景1：未载货 - 机器人电量不足
|
||
|
||
**业务场景**：
|
||
机器人AGV_001正在前往取货点的途中，尚未取货，系统检测到其电量不足，需要更换为电量充足的AGV_002继续执行任务。
|
||
|
||
**请求示例**：
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/vwed-task-record/switch-robot/550e8400-e29b-41d4-a716-446655440000" \
|
||
-H "Content-Type: application/json" \
|
||
-H "x-access-token: your-token-here" \
|
||
-d '{
|
||
"robot_name": "AGV_002",
|
||
"robot_group": "group_A",
|
||
"robot_label_group": "label_1",
|
||
"switch_reason": "机器人AGV_001电量不足，更换为AGV_002",
|
||
"has_cargo": false
|
||
}'
|
||
```
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "换机器人成功(未载货场景)",
|
||
"data": {
|
||
"task_record_id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"switch_reason": "机器人AGV_001电量不足，更换为AGV_002",
|
||
"has_cargo": false,
|
||
"robot_name": "AGV_002",
|
||
"robot_group": "group_A",
|
||
"robot_label_group": "label_1",
|
||
"site_id": "AP154",
|
||
"action": "pick",
|
||
"key_route": "LM532",
|
||
"added_blocks": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
**系统行为**：
|
||
1. 终止当前任务的所有待执行块
|
||
2. 从原任务定义中自动提取：
|
||
- `site_id`: "AP154"（目标取货点）
|
||
- `action`: "pick"（取货动作）
|
||
- `key_route`: "LM532"（关键路径）
|
||
3. 添加3个新任务块：
|
||
- 选择机器人块：选择AGV_002
|
||
- 获取库位块：获取AP154库位信息
|
||
- 执行通用动作块：执行pick动作
|
||
4. 更新任务定义并通过调度器实时生效
|
||
5. AGV_002继续执行原任务的剩余步骤
|
||
|
||
---
|
||
|
||
### 场景2：已载货 - 机器人故障需要转运
|
||
|
||
**业务场景**：
|
||
机器人AGV_001已经在AP154取货，正在前往目标放货点AP540的途中发生故障。需要将货物转运到临时库位AP300，然后更换为AGV_003继续执行任务。
|
||
|
||
**请求示例**：
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/vwed-task-record/switch-robot/550e8400-e29b-41d4-a716-446655440000" \
|
||
-H "Content-Type: application/json" \
|
||
-H "x-access-token: your-token-here" \
|
||
-d '{
|
||
"robot_name": "AGV_003",
|
||
"robot_group": "group_B",
|
||
"switch_reason": "机器人AGV_001故障，货物转运至AP300后更换为AGV_003",
|
||
"has_cargo": true,
|
||
"site_id": "AP300",
|
||
"action": "drop"
|
||
}'
|
||
```
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "换机器人成功(已载货场景)",
|
||
"data": {
|
||
"task_record_id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"switch_reason": "机器人AGV_001故障，货物转运至AP300后更换为AGV_003",
|
||
"has_cargo": true,
|
||
"robot_name": "AGV_003",
|
||
"robot_group": "group_B",
|
||
"robot_label_group": null,
|
||
"site_id": "AP300",
|
||
"action": "drop",
|
||
"key_route": "LM532",
|
||
"added_blocks": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
**系统行为**：
|
||
1. 终止当前任务的所有待执行块
|
||
2. 使用请求参数：
|
||
- `site_id`: "AP300"（临时转运点）
|
||
- `action`: "drop"（放货动作）
|
||
3. 添加3个新任务块：
|
||
- 选择机器人块：选择AGV_003
|
||
- 获取库位块：获取AP300库位信息
|
||
- 执行通用动作块：执行drop动作
|
||
4. 更新任务定义并通过调度器实时生效
|
||
5. AGV_001将货物放到AP300后，AGV_003接管任务继续执行
|
||
|
||
---
|
||
|
||
## 技术实现说明
|
||
|
||
### 处理流程
|
||
|
||
```
|
||
1. 接收换机器人请求
|
||
↓
|
||
2. 验证任务状态（必须是RUNNING）
|
||
↓
|
||
3. 解析任务定义
|
||
↓
|
||
4. 终止调度器中的当前任务
|
||
↓
|
||
5. 终止所有待执行的任务块
|
||
↓
|
||
6. 提取或使用参数
|
||
├─ 未载货：从原任务提取 keyRoute, targetSiteLabel, action
|
||
└─ 已载货：使用请求参数 site_id, action
|
||
↓
|
||
7. 构建3个新任务块
|
||
├─ CSelectAgvBp：选择机器人块
|
||
├─ GetIdleSiteBp：获取库位块
|
||
└─ CAgvOperationBp：执行通用动作块
|
||
↓
|
||
8. 更新任务定义（追加新块到rootBlock）
|
||
↓
|
||
9. 更新数据库（task_def_detail, ended_reason）
|
||
↓
|
||
10. 通知调度器更新任务定义（实时生效）
|
||
↓
|
||
11. 返回换机器人结果
|
||
```
|
||
|
||
### 核心数据结构
|
||
|
||
**添加的任务块结构**：
|
||
|
||
```json
|
||
{
|
||
"id": "new_block_id_1",
|
||
"name": "switch_robot_xxx",
|
||
"blockType": "CSelectAgvBp",
|
||
"label": "选择执行机器人(换机器人)",
|
||
"description": "换机器人: {switch_reason}",
|
||
"inputParams": {
|
||
"vehicle": {"value": "AGV_002", "type": "Simple", "required": false},
|
||
"group": {"value": "group_A", "type": "Simple", "required": false},
|
||
"label_group": {"value": "label_1", "type": "Simple", "required": false},
|
||
"keyRoute": {"value": "LM532", "type": "Simple", "required": true}
|
||
},
|
||
"children": {
|
||
"default": [
|
||
{
|
||
"id": "new_block_id_2",
|
||
"name": "get_site_xxx",
|
||
"blockType": "GetIdleSiteBp",
|
||
"label": "获取库位(换机器人)",
|
||
"inputParams": {
|
||
"siteId": {"value": "AP154", "type": "Simple", "required": false},
|
||
"locked": {"value": false, "type": "Simple", "required": true},
|
||
"lock": {"value": true, "type": "Simple", "required": false}
|
||
},
|
||
"children": {}
|
||
},
|
||
{
|
||
"id": "new_block_id_3",
|
||
"name": "action_xxx",
|
||
"blockType": "CAgvOperationBp",
|
||
"label": "机器人通用动作(换机器人)",
|
||
"inputParams": {
|
||
"targetSiteLabel": {"value": "AP154", "type": "Simple", "required": true},
|
||
"task": {"value": "pick", "type": "Simple", "required": false},
|
||
"spin": {"value": "", "type": "Simple", "required": false}
|
||
},
|
||
"children": {}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 数据库变更
|
||
|
||
**任务记录表（vwed_taskrecord）**：
|
||
- `task_def_detail`：更新为包含新任务块的定义
|
||
- `ended_reason`：记录换机器人原因，格式：`换机器人(未载货/已载货): {switch_reason}`
|
||
|
||
**任务块记录表（vwed_blockrecord）**：
|
||
- 所有未完成的块：
|
||
- `status`：更新为 2002（CANCEL）
|
||
- `ended_on`：记录终止时间
|
||
- `ended_reason`：记录终止原因，格式：`换机器人终止: {switch_reason}`
|
||
|
||
---
|
||
|
||
## 注意事项和最佳实践
|
||
|
||
### 使用限制
|
||
|
||
1. **任务状态要求**：
|
||
- 只能对状态为 `RUNNING`（1001）的任务执行换机器人操作
|
||
- 已完成、失败、取消的任务无法换机器人
|
||
|
||
2. **参数要求**：
|
||
- 至少提供一个机器人选择参数（robot_name、robot_group、robot_label_group）
|
||
- 已载货场景必须提供 site_id 和 action
|
||
|
||
3. **并发控制**：
|
||
- 同一任务不应同时执行多次换机器人操作
|
||
- 建议在调用前检查任务当前状态
|
||
|
||
### 最佳实践
|
||
|
||
1. **参数选择**：
|
||
- 优先使用 `robot_name` 指定具体机器人
|
||
- 使用 `robot_group` 让系统从组中自动选择
|
||
- 使用 `robot_label_group` 基于标签筛选机器人
|
||
|
||
2. **未载货场景**：
|
||
- 系统会自动从原任务中提取参数，无需手动指定 site_id 和 action
|
||
- 适用于机器人尚未开始实际操作的情况
|
||
|
||
3. **已载货场景**：
|
||
- 必须明确指定目标库位和动作
|
||
- 建议先将货物放到临时库位，再更换机器人继续后续任务
|
||
- action 常用值：`pick`（取货）、`drop`（放货）
|
||
|
||
4. **错误处理**：
|
||
- 换机器人失败时，原任务会保持原状态
|
||
- 建议实现重试机制
|
||
- 记录详细的换机器人日志用于问题追溯
|
||
|
||
5. **监控和日志**：
|
||
- 通过 `ended_reason` 字段追踪换机器人历史
|
||
- 通过任务块记录查看被终止的块
|
||
- 建议在业务系统中记录换机器人操作日志
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| 错误码 | 错误信息 | 说明 | 解决方案 |
|
||
| --- | --- | --- | --- |
|
||
| 404 | 未找到任务记录 | 任务记录ID不存在 | 检查任务记录ID是否正确 |
|
||
| 400 | 只能对运行中的任务换机器人 | 任务状态不是RUNNING | 确认任务正在运行中 |
|
||
| 400 | 任务定义解析失败 | 任务定义JSON格式错误 | 检查任务定义数据完整性 |
|
||
| 400 | 任务定义格式不正确 | 缺少必要的定义字段 | 确保任务定义包含detail和rootBlock |
|
||
| 400 | 已载货场景需要提供库位ID和执行动作 | 已载货时缺少site_id或action | 补充完整的请求参数 |
|
||
| 500 | 换机器人失败 | 系统内部错误 | 查看详细错误日志，联系技术支持 |
|
||
|
||
---
|
||
|
||
## 相关接口
|
||
|
||
- [获取任务记录详情](./任务记录接口文档.md#5-获取任务记录详情)：查看换机器人后的任务状态
|
||
- [获取任务块运行记录](./任务记录接口文档.md#1-获取任务块运行记录)：查看被终止的块和新添加的块
|
||
- [获取任务执行结果](./任务记录接口文档.md#4-获取任务执行结果)：查看完整的任务执行历史
|
||
- [终止任务](./任务记录接口文档.md#3-终止任务)：如果换机器人失败，可以终止任务
|
||
|
||
---
|
||
|
||
## 更新日志
|
||
|
||
| 版本 | 日期 | 更新内容 | 作者 |
|
||
| --- | --- | --- | --- |
|
||
| v1.0 | 2025-10-09 | 初始版本，支持未载货和已载货两种场景 | Claude |
|
||
|
||
---
|
||
|
||
## 技术支持
|
||
|
||
如有问题，请联系：
|
||
- 技术文档：[VWED任务模块接口文档](./README.md)
|
||
- 问题反馈：提交Issue到项目仓库
|