错误处理与可观测性

HDMapSDK 使用激活状态和查询 Status 区分数据准备、无数据、授权、生命周期和持久数据问题。路线关联与交通能力还需结合导航支持信号判断，不能由静态地图服务状态推断其可用性。

服务状态

仅在成功后读取输出

多个查询接口只在成功时赋值。每次调用使用独立输出对象；返回非 OK 时忽略其中内容。

`ActivationStatusCode`	产品含义	应用处理
`OK`	激活有效	保存有效期并创建服务
`Expired`	授权已过期	恢复授权；仅按已批准策略处理受限缓存连续性
`Forbidden`	产品或设备被禁止	阻止启动并核对授权关系
`Inactivated`	设备尚未激活	确认网络和配置后重新激活
`AuthenticationFailure`	云端认证失败	检查凭据、系统时间、证书、端点和网络
`InitFailure`	请求字段或本地环境不完整	修复必填字段、目录或证书
`ActivationFailure`	激活流程失败	记录关联 ID 和脱敏上下文，按项目策略处理
`InternalError` / `UnknownError`	激活内部或未分类异常	检查连接与服务健康，有限重试并升级处理

getMapVersion(...) 成功表示服务已选中地图版本，不表示目标区域一定有数据；RunningMode::Normal 也不表示导航支持连接、车辆/路线上下文或交通数据正在更新。

信号	表示	应用处理
`is_connected_to_navigation_sdk == false`	通信模块不可用	停止使用沿路线结果；交通按本次查询 `Status` 处理
`is_navigation_sdk_notify_working == false`	导航系统的位置/状态消息未持续到达	将现有路线状态视为历史值，等待输入恢复
非导航、偏航或不在路	当前没有可直接消费的有效导航走廊	清除或降级路线叠加，等待新的有效状态
`LinkOnRoute::link_match_status` 仍在处理或未匹配	道路级路线尚未关联到高精 Lane Group	不使用对应 Lane Group 范围
`queryTraffic(...)` 非 `OK`	交通查询或关联未完成	按返回 `Status` 处理，不把空输出解释为畅通
`queryTraffic(...)` 为 `OK` 且数组为空	当前没有返回可关联的交通内容	表示无消息，不等同于明确 `FreeFlow`

协作链路恢复后，从新的 NavigationStatus 重建路线状态，并使用新的交通查询结果更新交通状态。

重试只用于幂等查询，并同时受以下条件约束：

日志接口包括 setLogLevel(LogLevel)、setLogHandler(LogHandler) 和 LogMessage。调试构建默认级别为 Warning，发布构建默认为 Disabled。

日志级别和处理回调是进程级共享配置，不属于单个 HDMapService 实例。应用设置唯一的日志生命周期所有者并串行调整配置；与 HDMapSDK 共享日志运行时的其他组件改变配置时，也会影响 HDMapSDK。

SDK 不指定日志回调所在线程。处理器需要线程安全、快速返回，不在回调路径执行磁盘压缩、网络上传或大块格式化。setLogHandler(...) 没有单独的注销接口，处理回调及其捕获上下文在 SDK 可能写日志期间保持有效。

敏感日志

初始化阶段的 Info 级诊断可能包含应用凭据、设备标识、端点和本地路径。量产使用项目批准的日志级别，并在导出前完成脱敏。

重复调用 shutdown() 没有额外效果。

DataError 表示持久数据损坏，通常不能通过查询重试恢复：

服务重建后重新获取所有运行时 ID，不把损坏前的 LaneGroupId、LaneId 或 LaneBoundaryId 用于新查询。