📝 docs(api): 添加协作机器人飞拍接口文档

* 说明运行速度倍率设置接口与返回结果
* 说明飞拍启动接口、调用顺序和 curl 示例

docs/collaborative-robot-flyshot-start-api.md

@@ -0,0 +1,109 @@
+# 协作机器人飞拍接口
+
+本文仅保留协作机器人后端需要调用的两个接口：设置运行速度、启动已存在的飞拍任务。不包含初始化、连接、使能、任务上传或任务管理。
+
+服务地址示例：`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}'
+```