导航关联数据
路线关联高精数据、前路高精上下文和 Lane Group 交通以静态 Lane Group 数据为基础，并需要导航系统提供车辆上下文、路线上下文或交通数据。核心静态地图查询不依赖这些输入。
数据责任边界
SD 道路段 / SD 边是导航系统使用的道路级道路段 / 边，用于把道路级路线与交通信息关联到高精 Lane Group。
| 分类 | 数据与职责 | 典型对象或字段 |
|---|---|---|
| 导航系统输入 | 匹配位置，在路、导航、仿真和偏航状态；SD 路线与道路段；按 SD 边提供的交通事件和流量 | coordinate、导航状态、WayReference、路线、道路段几何、交通数据 |
| HDMapSDK 地图 | 当前地图版本的 Lane Group，以及 SD 道路段与高精 Lane Group 的对应关系 | LaneGroupId、WayReference |
| 关联后的结果 | 将导航系统道路级上下文关联到一个或多个 Lane Group | ahead_links、ahead_lane_group_ids_along_route、TrafficMessage::lane_group_id |
交通关联的数据路径为 LaneGroupId → SD 道路段 / 边 → 导航系统交通数据 → TrafficMessage::lane_group_id。沿路线关联从导航系统的当前位置与 SD 路线出发，输出道路段匹配状态、Lane Group ID 和覆盖范围。
接口入口
| 接口 | 输入 | 输出 |
|---|---|---|
setNavigationStatusListener(callback) |
状态回调 | 匹配位置、前方路线片段和 Lane Group |
queryTraffic(messages, ids) |
一组 LaneGroupId |
与这些 Lane Group 关联的 TrafficMessage |
这两个入口都依赖导航系统输入。通信不可用或相关上下文无效时，应用停止使用受影响结果；静态 Lane Group 查询仍按自身状态处理。
路线关联与前路状态
路线关联高精数据与前路高精上下文是同一个 NavigationStatus 中的两类结果，不是两个独立服务。配置通信模块的项目连接设置并注册 setNavigationStatusListener(...) 后，HDMapSDK 接收车辆上下文与路线上下文，将道路段关联到高精 Lane Group，再周期性返回 NavigationStatus。新回调会替换已有回调，传入空回调可停止通知。
SDK 不指定回调线程或重入方式。回调只读取或转发当前结果；监听器变更和 shutdown() 由回调外的生命周期所有者执行。需要从回调触发停止时，先向生命周期任务发送信号，再由该任务检查监听器设置结果并完成关闭。
| 字段 | 形成方式 | 内容 |
|---|---|---|
coordinate |
导航系统输入 | 当前匹配位置和航向 |
ahead_lane_group_ids_along_route |
联合关联 | 车辆前方路线上的 Lane Group ID，第一项为车辆当前所在 Lane Group |
ahead_links |
联合关联 | 前方 SD 路线片段以及每个片段匹配到的高精 Lane Group |
is_in_navigation、is_in_simulation |
导航系统输入 | 当前导航状态 |
is_on_road、is_deviation |
导航系统输入 | 道路匹配和偏航状态 |
is_connected_to_navigation_sdk |
HDMapSDK 连接监控 | 通信可用性 |
is_navigation_sdk_notify_working |
导航系统输入心跳监控 | 导航系统的位置/状态消息是否在最大等待时间内持续到达 |
NavigationStatus::LinkOnRoute 把标准道路片段与高精 Lane Group 连接起来：
way_reference标识有方向的道路片段；link_match_status表示匹配处理中、已匹配或未匹配；matched_lane_group_ids_on_route给出该片段匹配到的 Lane Group；lane_group_ranges_on_link给出这些 Lane Group 在片段上的归一化范围；geometry在开启enable_output_along_route_link_geometry后返回路线片段几何。
车辆不在导航路线、发生偏航或匹配仍在进行时，相关数组可能为空。连接正常但消息超过 max_navigation_message_wait_time 后，应用也不使用旧的路线结果继续驱动业务。
场景代码见消费路线关联与前路结果。
交通数据
queryTraffic(...) 以 LaneGroupId 为应用侧查询键。HDMapSDK 使用当前地图版本的关系找到对应 SD 道路段 / 边，通过导航系统获取交通数据，再将事件和流量关联到 Lane Group。每个 TrafficMessage 包含：
| 字段 | 内容 |
|---|---|
lane_group_id |
交通信息关联的 Lane Group |
incidents |
事故、拥堵、封路、施工、天气、障碍等事件 |
incidents[].urgency、severity |
事件紧急程度和影响等级 |
incidents[].incident_position |
事件发生位置 |
incidents[].hazardous_position |
事件开始影响道路的位置 |
incidents[].is_blocking |
车辆是否仍可通行 |
flow.level |
关闭、拥堵、排队、低速、繁忙或畅通 |
flow.average_speed |
平均速度（米/秒），-1 表示不可用 |
接口只返回有交通内容且能够完成关联的 Lane Group，结果数量可能少于请求的 ID 数量。空结果表示当前没有返回交通消息；明确的畅通状态由 TrafficFlow::Level::FreeFlow 表示。应用同时检查通信可用性、本次查询 Status 和项目交付的交通内容时效规则，不能只依据数组是否为空判断交通链路健康。
TrafficMessage 公共模型不提供内容时间戳，is_navigation_sdk_notify_working 只反映导航系统的位置/状态消息是否持续到达，不能作为 HDMapSDK 输出回调节奏或交通事件、流量年龄的证明。navigation_status_notify_interval 单独控制 NavigationStatus 输出间隔。只有项目交付的上游内容时间戳或有效期契约可以证明内容年龄；应用接收时间只能限制结果在本地继续持有的时长。没有上游时间依据时，端到端新鲜度为未知。
场景代码见查询 Lane Group 交通。
标识与单位
| 内容 | 生命周期、单位或特殊值 |
|---|---|
WayId |
当前地图版本内有效；与 is_positive 组成有方向的 WayReference |
NormalizedRange |
[0.0, 1.0]；{0.0, 1.0} 覆盖完整参考对象 |
| GPS 航向 | 从正北顺时针，范围 [0, 360) |
| 交通平均速度 | 米/秒；-1 表示不可用 |
服务重建或地图版本变化后重新获取路线关联和交通结果。通信、导航状态和交通查询的失败处理见错误处理与可观测性，数据版本行为见数据与版本管理。