导航参数与参数方案
8.1 三种状态必须分开
- 已保存参数：本机数据库中的配置。
- 运行参数：当前导航容器参数服务中的值。
- 启动回放结果：保存值在容器启动后应用、匹配及验证的结果。
保存成功不等于已经生效。/nav/set_nav_params 先保存，运行时就绪后尝试应用；/nav/params/set 先下发运行时，仅持久化运行时接受的参数。
8.2 POST /v1/api/nav/params/list
无请求体。返回嵌套参数树：
{"parameters":{"navigation":{"free_navigation":{"linear_speed":{"access":"rw","type":"float","value":0.4,"writable":true}}}}}
叶子 access:string、type:string、value:any、writable:boolean；树的完整内容、access/type 的字符串以及取值范围由当前导航镜像返回，示例不是固定清单。可读取到的字段不一定在端侧写入白名单内。
8.3 查询运行值与保存值
三个接口都需要 JSON：
{"names":["navigation:free_navigation:linear_speed","robot:footprint"]}
| 接口 | 数据来源 | 响应 data 结构 |
|---|---|---|
POST /v1/api/nav/params/get | 运行时 | {"parameters":{"参数名":ParamResult}} |
POST /v1/api/nav/get_nav_params | 运行时 | {"参数名":ParamResult} |
POST /v1/api/nav/get_saved_nav_params | 本机保存值 | {"参数名":ParamResult} |
names 是 string[]。客户端应至少请求一个明确名称，不依赖空数组的下游行为。ParamResult：success:boolean、value:any、message:string。例如 /params/get：
{"parameters":{"navigation:free_navigation:linear_speed":{"success":true,"value":0.4,"message":""}}}
单项 success=false 仍可能在外层 code=0 的响应中出现。
8.4 保存 / 设置参数
两个接口的请求体都是直接的参数名到值映射，不要再套一层 params 或 values：
{"navigation:free_navigation:linear_speed":0.4,"navigation:fixed_point_navigation:holonomic":false}
| 接口 | 行为 | 响应 data |
|---|---|---|
POST /v1/api/nav/set_nav_params | 校验并保存；运行时可用则立即应用，不可用则延后 | 参数名 → ParamSetResult；在线应用时可额外出现键 offline_save |
POST /v1/api/nav/params/set | 下发运行时，把成功项保存到数据库 | {"results":{参数名:ParamSetResult},"offline_save":ParamSetResult} |
ParamSetResult：success:boolean、message:string，可含 value:any。offline_save 是结果对象，不是 boolean。离线保存示例：
{"navigation:free_navigation:linear_speed":{"success":true,"message":"已保存，导航启动后应用","value":0.4}}
运行时设置示例：
{"results":{"navigation:free_navigation:linear_speed":{"success":true,"message":"","value":0.4}},"offline_save":{"success":true,"message":""}}
外层成功不是所有参数成功，必须遍历 results 或参数映射。失败项不应在 UI 上显示为“已生效”。同一请求可能部分成功，不能把它当成原子事务。
8.5 当前写入白名单与校验
以下名称来自端侧 ParamManager，适用于保存、运行时设置、参数方案校验；实际数值边界还需遵循导航镜像约束。
| 参数名 | JSON 类型 | 含义 |
|---|---|---|
robot:lidar_mount_position | number[3] | 雷达安装位置 |
robot:footprint | number[][2] | 机器人轮廓多边形 |
general:min_obstacle_height | number | 最小障碍物高度 |
general:max_obstacle_height | number | 最大障碍物高度 |
navigation:free_navigation:linear_speed | number | 自由导航线速度 |
navigation:free_navigation:angular_speed | number | 自由导航角速度 |
navigation:free_navigation:xy_goal_tolerance | number | 平面到点容差 |
navigation:free_navigation:yaw_goal_tolerance | number | 朝向容差 |
navigation:free_navigation:safety_distance | number | 安全距离 |
navigation:fixed_point_navigation:max_linear_speed | number | 定点最大线速度 |
navigation:fixed_point_navigation:max_angular_speed | number | 定点最大角速度 |
navigation:fixed_point_navigation:holonomic | boolean | 全向运动配置 |
navigation:fixed_point_navigation:xy_goal_tolerance | number | 定点位置容差 |
navigation:fixed_point_navigation:yaw_goal_tolerance | number | 定点朝向容差 |
navigation:fixed_point_navigation:lateral_safety_distance | number | 横向安全距离 |
navigation:fixed_point_navigation:forward_safety_distance | number | 前向安全距离 |
所有 number 必须有限；不接受字符串代替数值，boolean 也不接受字符串。lidar_mount_position 恰好 3 个数。footprint 至少 3 个点，每点 2 个有限数，坐标绝对值不超过 5 m，面积 0.01–10 m²，不自交，原点必须严格在内部且不落在边界。
{"robot:footprint":[[-0.3,-0.2],[0.3,-0.2],[0.3,0.2],[-0.3,0.2]]}
历史名称会规范化：
| 旧名 | 当前名称 |
|---|---|
linear_speed | navigation:free_navigation:linear_speed |
angular_speed | navigation:free_navigation:angular_speed |
robot_footprint | robot:footprint |
fixed_point_safety_distance | navigation:fixed_point_navigation:forward_safety_distance |
holonomic | navigation:fixed_point_navigation:holonomic |
navigation:free_navigation:min_obstacle_height | general:min_obstacle_height |
navigation:free_navigation:max_obstacle_height | general:max_obstacle_height |
current_map 虽有到 general:map_name 的名称映射，但该名称不在当前写入白名单，不能通过这个兼容名称实现地图切换。
8.6 健康与回放结果
POST /v1/api/nav/params/health 无请求体，返回 {"healthy":true}。
GET /v1/api/nav/params/apply_status 无参数，返回：
| 字段 | 类型 | 说明 |
|---|---|---|
state | string | idle、running、success、failed、skipped |
message | string | 说明文本 |
saved_count、applied_count、matched_count | integer | 保存项、已下发项、原值已经匹配项数量 |
failed_count、verified_count、unverified_count | integer | 失败、验证成功、未验证数量 |
applied、matched | string[]，可省略 | 参数名列表 |
failed、verify_failed、unverified | object[]，可省略 | 每项 {name:string,message:string} |
offline_save | ParamSetResult | 下游离线保存结果 |
started_at、finished_at | string，可省略 | 本次回放时间 |
未执行回放时为 idle；不能只查保存接口就推断参数启动后有效。
8.7 参数方案 CRUD 与应用
| 接口 | 请求 | 响应 data |
|---|---|---|
GET /v1/api/nav/param-presets | 无 | Preset[] |
POST /v1/api/nav/param-presets | name + params | 新 Preset |
PUT /v1/api/nav/param-presets/{id} | 正整数 id；完整 name + params | 更新后的 Preset |
DELETE /v1/api/nav/param-presets/{id} | 正整数 id，无请求体 | null |
POST /v1/api/nav/param-presets/{id}/apply | 正整数 id，无请求体 | preset_id、all_succeeded、results |
{"name":"室内低速","params":{"navigation:free_navigation:linear_speed":0.3}}
name 必须非空，params 必须为非空对象并通过白名单校验。Preset 响应增加 id:integer、created_at:string、updated_at:string；应用后可有 last_applied_at:string，未应用时可能省略。
{"preset_id":1,"all_succeeded":true,"results":{"navigation:free_navigation:linear_speed":{"success":true,"message":"已保存，导航启动后应用","value":0.3}}}
应用方案复用保存逻辑，离线时可以成功保存；all_succeeded=true 不保证立即生效。导航任务运行、暂停或停止中时拒绝切换：409/4002。非法 ID、名称重复、参数无效：400/1001；不存在：404/1002。PUT 是完整资源更新，不是局部 PATCH。