# 协作机器人飞拍接口

本文仅保留协作机器人后端需要调用的两个接口：设置运行速度、启动已存在的飞拍任务。不包含初始化、连接、使能、任务上传或任务管理。

服务地址示例：`http://<飞拍服务地址>:<端口>`。

## 1. 设置运行速度

```http
POST /set_speedRatio/
Content-Type: application/json
```

请求体：

```json
{
  "speed": 0.7
}
```

| 字段 | 类型 | 范围 | 说明 |
| --- | --- | --- | --- |
| `speed` | number | `0.01` ～ `1.0` | 运行速度倍率；`1.0` 为全速，`0.7` 为 70% 速度。 |

成功响应：`200 OK`

```json
{
  "message": "set_speedRatio executed",
  "returnCode": 0
}
```

参数不在范围内时返回 `400 Bad Request`：

```json
{
  "detail": "Speed ratio must be between 0.01 and 1.0."
}
```

应在启动飞拍前设置速度。当前接口不约定任务执行过程中的动态改速。

## 2. 启动飞拍任务

```http
POST /execute_flyshot/
Content-Type: application/json
```

请求体：

```json
{
  "name": "协作机器人飞拍任务名",
  "move_to_start": true,
  "method": "icsp",
  "save_traj": false,
  "use_cache": true,
  "wait": false
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `name` | string | 已存在的飞拍任务名称。 |
| `move_to_start` | boolean | 是否先移动到飞拍轨迹起点；建议为 `true`。 |
| `method` | string | 轨迹规划方法；使用 `"icsp"`。 |
| `save_traj` | boolean | 是否保存规划导出信息；启动任务时使用 `false`。 |
| `use_cache` | boolean | 是否复用规划缓存；建议为 `true`。 |
| `wait` | boolean | `false` 表示启动后立即返回；本接口使用 `false`。 |

成功响应：`200 OK`

```json
{
  "status": "FlyShot executed",
  "success": true
}
```

`wait=false` 时，`200` 仅表示任务已接受并开始调度，不表示飞拍已经完成。

启动失败时返回 `500 Internal Server Error`：

```json
{
  "detail": "具体失败原因"
}
```

## 3. 调用顺序

```text
POST /set_speedRatio/  →  收到 returnCode = 0  →  POST /execute_flyshot/
```

curl 示例：

```bash
curl -X POST 'http://<飞拍服务地址>:<端口>/set_speedRatio/' \
  -H 'Content-Type: application/json' \
  -d '{"speed":0.7}'

curl -X POST 'http://<飞拍服务地址>:<端口>/execute_flyshot/' \
  -H 'Content-Type: application/json' \
  -d '{"name":"协作机器人飞拍任务名","move_to_start":true,"method":"icsp","save_traj":false,"use_cache":true,"wait":false}'
```