本机任务队列

10.1 本机任务 LocalTask 模型

同一时刻只执行一个本机任务。导航、建图、重定位等任务共享队列，但不是所有 HTTP 操作都会入队，例如容器停止和参数设置有各自执行路径。

本章返回字段使用首字母大写，Status 为整数，Payload / ResultJSON 为 JSON 字符串。

字段	类型	说明
`ID`	string	本机任务 ID
`Type`	string	navigation / mapping / map_edit / relocation
`Status`	integer	0 pending、1 running、2 completed、3 failed、4 cancelled、5 stopping
`Payload`	string	请求载荷 JSON 的序列化字符串
`ResultJSON`	string	执行结果 JSON 字符串，可能为空
`CreatedAt`、`UpdatedAt`	string	创建与修改时间
`StartedAt`、`EndedAt`	string / null	开始、结束时间
`ErrorMsg`	string	失败原因，成功时通常为空
`ErrorCode`	integer	当前持久化路径通常为 0，不能只靠此字段判断失败
`IdempotencyKey`	string	提交幂等键
`TimeoutSeconds`	integer	正数为执行超时秒数；0 不设执行时限

示例（data）：

{
  "ID":"task-example-id","Type":"navigation","Status":0,
  "Payload":"{\"action\":\"navigate_to_pose\",\"x\":3.2,\"y\":1.5,\"frame_id\":\"map\"}",
  "ResultJSON":"","CreatedAt":"2026-11-13T08:00:00Z","UpdatedAt":"2026-11-13T08:00:00Z",
  "StartedAt":null,"EndedAt":null,"ErrorMsg":"","ErrorCode":0,
  "IdempotencyKey":"visit-frontdesk-001","TimeoutSeconds":120
}

普通流程为 pending → running → completed/failed；取消可经过 stopping → cancelled。建图停止可能是保存流程并最终 completed，不能把所有 CancelCurrent 都机械理解为最终 cancelled。

10.2 POST /v1/api/tasks/submit

字段	类型	必填 / 说明
`type`	string	必填，上述任务类型之一
`payload`	object	对应任务的执行参数
`idempotency_key`	string	可选，相同键与相同请求返回已有任务；同键不同请求拒绝
`timeout_seconds`	integer	可选，推荐非负；0 不限时

{"type":"navigation","payload":{"action":"navigate_to_pose","x":3.2,"y":1.5,"theta":0.0,"frame_id":"map"},"idempotency_key":"visit-frontdesk-001","timeout_seconds":120}

成功返回完整 LocalTask，不是只返回 task_id；该通用接口没有 Missions 的 500 ms 快速失败等待。客户端必须检查后续任务状态。

type	payload
navigation	`action` 必填：navigate_to_pose / navigate_fixed_point / navigate_through_poses / complex；按动作提供 x/y/theta/frame_id、waypoints/cycles 或 default_params/steps；可有 use_relocalization
mapping	`scene_name`、可选 runtime_version/runtime_image；普通客户端建议用建图专用接口完成运行时解析
relocation	`mode`，使用 global/origin/sequential
map_edit	云端地图编辑执行载荷，依赖内容下载、校验和回执上下文，不建议客户直接构造

未知任务类型、忙碌、幂等冲突等提交错误一般为 500/5001；地图名非法为 400/1001。幂等键作用域为设备本地任务存储，创建新的业务操作应使用新键。

10.3 查询任务

接口	参数	响应 data
`GET /v1/api/tasks`	下表 query	LocalTask[]，没有 items 包装
`GET /v1/api/tasks/current`	无	当前运行/停止中的 LocalTask，无则 null
`GET /v1/api/tasks/{id}`	path string id	指定 LocalTask，不存在为 404/1002

列表 query：

参数	类型 / 默认	说明
`status`	string，可选	逗号分隔整数，如 `0,1,5`；非整数字符返回 400
`type`	string，可选	逗号分隔类型，如 `navigation,mapping`
`limit`	integer，20	必须 >0；当前 handler 未设置统一最大值，无 offset/cursor 分页参数

curl -sS -G -H "Authorization: Bearer $ORSUS_TOKEN" \
  --data-urlencode 'status=0,1,5' --data-urlencode 'type=navigation' --data-urlencode 'limit=20' \
  "$ORSUS_ORIGIN/v1/api/tasks"

10.4 取消与队列推进

接口	请求	响应 / 约束
`DELETE /v1/api/tasks/{id}/cancel`	path id，无请求体	只取消 pending；其他状态报 500/5001；成功 data=null
`POST /v1/api/tasks/cancel_current`	无请求体	请求结束当前任务；成功 data=null
`POST /v1/api/tasks/start_next`	无请求体	手动唤醒下一排队任务；成功 data=null，不代表下一任务完成
`GET /v1/api/tasks/config`	无	`{"auto_start_next":true}`
`PUT /v1/api/tasks/config`	`{"auto_start_next":false}`	data=null；字段必填，false 合法

auto_start_next 控制任务之间自动衔接；停用后按业务确认再触发 start_next。取消当前任务与清空队列不同，尚未取消的 pending 任务仍存在。

10.1 本机任务 LocalTask 模型​

10.2 POST /v1/api/tasks/submit​

10.3 查询任务​

10.4 取消与队列推进​

10.1 本机任务 LocalTask 模型

10.2 POST /v1/api/tasks/submit

10.3 查询任务

10.4 取消与队列推进