导航控制与重定位
7.1 POST /v1/api/nav/start_navigation
单点导航旧入口仍有真实实现。必需 JSON 对象：
{"x":3.2,"y":1.5,"theta":0.0,"frame_id":"map"}
x/y/theta 为 number，frame_id 为 string。缺失数值在当前旧入口会默认为 0，客户端应全部显式提供。响应 data={"task_id":"..."}；通过 /tasks/{id} 或 /nav/missions/{id} 查询。不会自动调用 nav/startup。
7.2 POST /v1/api/nav/start_path_navigation
{"waypoints":[{"x":1.0,"y":0.0,"theta":0.0},{"x":3.0,"y":2.0,"theta":1.5708}],"frame_id":"map","cycles":1}
waypoints 为 Pose[]，frame_id 为 string，cycles 为 integer。新客户端优先使用 /nav/missions 的 route 模式以获得明确的入参校验。响应 data={"task_id":"..."}，同样有约 500 ms 快速失败检查。
7.3 停止、暂停、恢复
| 接口 | 请求 | 响应 data | 语义 |
|---|---|---|---|
POST /v1/api/nav/stop_navigation | 无 | null | 调用本机队列 CancelCurrent，作用于当前任务；不是指定 mission ID 的取消 |
POST /v1/api/nav/pause_navigation | 无 | null | 请求导航下游暂停 |
POST /v1/api/nav/resume_navigation | 无 | null | 请求导航下游恢复 |
这组接口是软件控制，不是硬件急停协议。按任务取消优先使用 /nav/missions/{id}，避免操作到之后已经开始的新任务。
7.4 导航状态与规划路径
| 接口 | 请求 | 响应 data |
|---|---|---|
POST /v1/api/nav/navigation_status | 无请求体 | NavStatus |
POST /v1/api/nav/navigation_task_status | 无请求体 | 与上一接口相同 |
POST /v1/api/nav/get_plan_path | 无请求体 | {"global":[[x,y],...]} |
NavStatus：
{"status":"navigating","relocalization":"successful","global_relocalization":"idle","navigation_session":{"runtime_instance":"runtime-example","scene_name":"office_1f","map_revision":"revision-example","localization_ready":true}}
| 字段 | 类型 / 取值 |
|---|---|
status | stop、navigating、paused、arrived、failed |
relocalization | disabled、successful、failed |
global_relocalization | idle、running、successful、failed |
navigation_session | 可选对象；runtime_instance、scene_name、map_revision 为 string，localization_ready 为 boolean |
该状态反映导航运行时当前状态，不携带某个历史任务的完成保证。get_plan_path.global 每项只有两个坐标，不包含 theta。
7.5 POST /v1/api/nav/clear_obstacles
JSON 可省略。scope: string 可取 all（默认）、nearby；nearby 为全局地图中机器人附近 10 米见方的范围。
{"scope":"nearby"}
同步等待清障；不停止当前导航，可能触发重新规划。成功响应 data=null；成功只表示清障操作完成，环境障碍可能再次被感知写入。空体或 {} 使用 all；null、非对象、非法 scope 为 400/3106。HTTP 200 + code 3101 表示忙碌，非清障成功。其余专用错误码见 2.6。
7.6 局部重定位开关与手动位姿
| 接口 | JSON 请求 | 响应 data |
|---|---|---|
POST /v1/api/nav/relocalization_toggle | {"enable":true} | null |
POST /v1/api/nav/set_relocalization_pose | {"x":0.0,"y":0.0,"z":0.0,"theta":0.0} | null |
enable 为 boolean，当前 handler 缺失该字段时按 false；应显式提供。位姿字段均为 number，缺失时按 0；应提供完整位姿。局部重定位开关与“执行一次全局重定位”是不同操作。
7.7 全局重定位
| 接口 | 请求 | 响应 data |
|---|---|---|
POST /v1/api/nav/global_relocalization | 可省略，或 {"mode":"sequential"} | {"mode":"sequential","accum_time_msec":0}，时间值以实际返回为准 |
POST /v1/api/nav/cancel_global_relocalization | 无请求体 | {"cancelled":true,"reason":"..."} |
mode 取 global、origin、sequential，缺省/空值使用 sequential；其他值 400/1001。启动成功后查询 NavStatus.global_relocalization 确认结果；accum_time_msec 是下游返回的毫秒信息，不是客户端必须等待的固定时长。reason 原样传递，不作为稳定枚举。
导航本章通用错误：JSON 非法 400/1001；容器未运行、Docker 不可用等导航错误 500/2001；下游调用失败可为 502/1005。