路径、标注与任务模板
资源保存与执行分离。保存路径、点位或模板不会自动切换地图，也不会启动导航环境。调用启动接口前应确认当前场景与资源 scene_name 一致；REST 简单启动路径不提供云端所有的地图修订保护。
9.1 路径对象 SavedPath
| 字段 | 类型 | 请求要求 / 含义 |
|---|---|---|
id | integer | 服务端资源 ID |
name | string | 路径名称 |
scene_name | string | 关联地图名 |
map_revision | string | 可选修订绑定，未知时为空 |
waypoints | Pose[] | 有序路径点，建议至少 2 点 |
created_at | string | 服务端创建时间 |
GET /v1/api/nav/paths
query scene_name:string 可选，省略查询全部。响应 data 为 SavedPath 数组，没有 items 包装层。
POST /v1/api/nav/paths
请求示例：
{"name":"大厅巡逻","scene_name":"office_1f","map_revision":"","waypoints":[{"x":0.0,"y":0.0,"theta":0.0},{"x":3.0,"y":1.0,"theta":1.5708}]}
返回保存后的 SavedPath。服务端还尝试生成同名 route 标注；该同步是尽力而为，失败只记日志，路径保存成功不保证标注也保存成功，可再查询 landmarks 确认。
DELETE /v1/api/nav/paths/{id}
path id 为整数，无请求体。成功 data=null；这里只删除路径记录，不应假定自动删除同名标注。ID 格式错误为 400/1001，存储错误通常为 500/2001。
POST /v1/api/nav/paths/start
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 提供非空 name 时优先按名称查找 |
scene_name | string | 与 name 配合，限定地图 |
path_id | integer | name 未提供时按 ID 查找 |
cycles | integer | <=0 按 1 |
{"name":"大厅巡逻","scene_name":"office_1f","cycles":2}
或 {"path_id":1,"cycles":1}。name 与 path_id 至少提供一种；两者都提供时 name 优先。坐标系固定为 map。返回 {"task_id":"..."}，并执行约 500 ms 快速失败检查。
9.2 地图标注 Landmark
| 字段 | 类型 | 说明 |
|---|---|---|
id | integer | 服务端 ID |
name、scene_name | string | 名称和地图；同地图名称唯一 |
map_revision | string | 可选地图修订 |
kind | string | point 或 route |
points | Pose[] | point 恰好 1 点；route 至少 2 点 |
created_at、updated_at | string | 服务端时间 |
| 接口 | 请求 | 响应 data |
|---|---|---|
GET /v1/api/nav/landmarks | query scene_name 可选 | Landmark[] |
POST /v1/api/nav/landmarks | Landmark 业务字段 | 新 Landmark |
PUT /v1/api/nav/landmarks/{id} | path 整数 id + 完整业务字段 | 更新后的 Landmark |
DELETE /v1/api/nav/landmarks/{id} | 无请求体 | null |
POST /v1/api/nav/landmarks/{id}/start | 可省略，或 {"cycles":1} | {"task_id":"..."} |
点位保存示例：
{"name":"前台","scene_name":"office_1f","map_revision":"","kind":"point","points":[{"x":3.2,"y":1.5,"theta":0.0}]}
PUT 不当作补丁使用，提交完整 name/scene_name/kind/points；path id 优先于请求体 id。启动时 point 转为单点导航、route 转为路径导航，frame_id 固定 map；cycles 仅对 route 有效，<=0 按 1。重复名称为 400/1001；部分校验/存储错误当前仍为 500/2001，不能假定所有未找到或非法标注均返回 404。
9.3 复杂任务模板 MissionTemplate
| 接口 | 请求 | 响应 data |
|---|---|---|
GET /v1/api/nav/mission-templates | query scene_name 必填且非空 | 模板数组 |
POST /v1/api/nav/mission-templates | 完整模板请求 | 新模板 |
PUT /v1/api/nav/mission-templates/{id} | 正整数 id + 完整模板请求 | 更新模板 |
DELETE /v1/api/nav/mission-templates/{id} | 无请求体 | null |
| 请求字段 | 类型 | 必填 / 默认 |
|---|---|---|
name、scene_name | string | 必填、去除空白后非空 |
map_revision | string | 可选 |
frame_id | string | 缺省 map |
default_params | object | 可选 |
steps | ComplexStep[] | 至少一步，校验规则同 6.2 |
{"name":"接待路线","scene_name":"office_1f","frame_id":"map","steps":[{"type":"navigate","target":{"x":3.2,"y":1.5,"theta":0.0}},{"type":"wait","wait_seconds":5}]}
响应在上述业务字段基础上增加 id、created_at、updated_at。没有模板 /start 接口；客户端从列表选择模板，把 frame_id/default_params/steps 与 mode="complex" 组成 Missions 请求。模板非法、名称重复：400/1001；ID 不存在：404/1002；存储故障：500/1003。