导航任务 Missions

新应用推荐使用 Missions。它统一单点、定点直达、路线及复杂任务的创建、查询与取消；底层仍使用本机串行任务队列。

6.1 POST /v1/api/nav/missions

请求字段	类型	适用范围与约束
mode	string，必填	standard、direct、route、complex
frame_id	string	建议明确传 map；HTTP 层没有给所有模式统一补默认值
target	Pose	standard/direct 必须提供对象；应显式提供 x/y/theta
waypoints	Pose[]	route 必填，至少 1 项
cycles	integer	route 循环次数；<=0 按 1；不是无限循环标志
default_params	object	complex 的默认参数字典
steps	ComplexStep[]	complex 必填，至少 1 项

Pose 为 {"x":number,"y":number,"theta":number}。模式语义：

mode	内部 action	用途
standard	navigate_to_pose	常规规划到目标
direct	navigate_fixed_point	定点直达控制；具体避障和运动策略由导航运行时实现
route	navigate_through_poses	按顺序经过路径点，按 cycles 循环
complex	complex	导航、定点、旋转、等待组成的步骤序列

单点示例：

{"mode":"standard","frame_id":"map","target":{"x":3.2,"y":1.5,"theta":0.0}}

定点直达示例：

{"mode":"direct","frame_id":"map","target":{"x":1.0,"y":0.0,"theta":1.5708}}

路线示例：

{"mode":"route","frame_id":"map","cycles":2,"waypoints":[{"x":1.0,"y":0.0,"theta":0.0},{"x":3.0,"y":2.0,"theta":1.5708}]}

6.2 ComplexStep 数据结构与执行语义

字段	类型	条件与含义
type	string，必填	navigate、fixed_point、rotate、wait
frame_id	string，可选	navigate/fixed_point 本步坐标系，省略继承任务 frame_id
target	Pose	navigate/fixed_point 必须提供
theta	number	rotate 的相对旋转量；省略会变成 0，应显式填写
wait_seconds	number	wait 必填且 >=0，允许小数
params	object，可选	本步使用的运行时参数，整体覆盖 default_params 的选择，不逐字段合并
on_failure	string	abort（省略等价）、skip、retry
retry	integer	on_failure=retry 时 >=1；表示初次尝试之后的额外重试次数

{
  "mode":"complex",
  "frame_id":"map",
  "default_params":{"navigation:free_navigation:linear_speed":0.4},
  "steps":[
    {"type":"navigate","target":{"x":3.2,"y":1.5,"theta":0.0}},
    {"type":"wait","wait_seconds":2.5},
    {"type":"fixed_point","target":{"x":4.0,"y":1.5,"theta":1.5708},"on_failure":"retry","retry":2},
    {"type":"rotate","theta":1.5708}
  ]
}

规则：

• complex 不能同时携带 target、非空 waypoints 或非零 cycles。
• wait 步骤不下发参数；rotate 固定使用 base_footprint，不使用请求中的 frame_id。
• 参数按步骤保留在运行时。未提供有效新参数时不会自动恢复默认值；提供本步 params 时也不会自动清除字典之外的已有运行参数。
• skip 会把失败步骤记作 skipped 并继续；整个任务 completed 不代表所有步骤都成功执行，检查 step_result 或应用侧记录。
• retry=2 最多执行该步骤 3 次；失败策略只处理步骤错误，取消任务会结束执行。

6.3 创建响应与快速失败

完整响应示例：

{
  "code":0,"msg":"success",
  "data":{
    "mission_id":"mission-example-id","status":"pending",
    "progress":{"percent":0,"method":"state_only","phase":"pending","completed_units":0,"current_unit":0,"total_units":0,"confidence":"low","updated_at":1794556800000}
  }
}

提交后服务端检查最多约 500 ms 的快速失败，失败则返回 500/2001。响应中的创建时 status 可能落后于任务当前状态，收到 ID 后使用查询接口。Missions 请求不接收 idempotency_key 或 timeout_seconds，不能靠添加未知字段获得这些能力。

6.4 GET /v1/api/nav/missions/{id}

path id 为创建时返回的 string。无请求体。

{
  "mission_id":"mission-example-id","mode":"complex","status":"running",
  "total_steps":4,"current_step":1,
  "progress":{"percent":25,"method":"step_count","phase":"waiting","completed_units":1,"current_unit":2,"total_units":4,"step_type":"wait","confidence":"high","updated_at":1794556800000}
}

current_step 从 0 开始，开始执行后才可能出现；progress.current_unit 从 1 开始。非导航任务或不存在的 ID 返回 404/1002。失败原因的详细持久化信息可通过相同 ID 的 /tasks/{id} 查看 ErrorMsg。

6.5 DELETE /v1/api/nav/missions/{id}

无请求体。取消 pending 的任务、请求取消 running/stopping 的任务；已 completed/failed/cancelled 则直接成功。响应 data=null。成功不保证机器人在该 HTTP 返回时已经完成物理停止，继续观察任务状态。

6.6 状态与进度模型

mission status	含义	是否终态
pending	排队等待	否
running	正在执行；下游导航暂停时任务仍可保持此状态	否
stopping	正在结束/取消	否
completed	执行完成	是
failed	失败	是
cancelled	取消完成	是

不存在独立的 Missions paused 状态；暂停显示需结合 /nav/navigation_status。

progress 字段	类型	说明
percent	number	0–100；运行中最多 99，completed 才为 100
method	string	remaining_path、waypoint_count、step_count、rotation、state_only
phase	string	当前阶段，例如 pending/planning/waiting；保留未知值以兼容运行时
completed_units、current_unit、total_units	integer	已完成、当前、总单元数
current_cycle、total_cycles	integer，可选	路线循环计数
current_waypoint、total_waypoints	integer，可选	路径点计数
remaining_distance_m	number，可选	剩余距离估计，米
eta_seconds	integer，可选	预计剩余秒数，不是截止时间
step_type、step_result	string，可选	复杂步骤类型和结果
attempt	integer，可选	当前额外重试计数；初次为 0，0 可省略
confidence	string	估算可信度，由当前数据决定
updated_at	integer	Unix 毫秒

进度是内存中的辅助估算，不是机器人安全反馈，也不是持久化审计。重启或历史记录清理后可能退化为 state_only；以任务终态判断完成，不用 percent 代替状态。