数据与版本管理

HDMapSDK 在同一服务中管理在线数据、本地缓存和地图版本。应用通过完整地图版本、RunningMode 和每次查询的 Status 判断当前数据状态。

数据来源与运行形态

形态	配置	启动条件	查询结果
在线流式	配置 `cloud_url`	有效激活、网络可达、云端存在兼容版本	缓存命中直接读取；未命中时按需下载
预置数据	持久目录已安装交付数据，`cloud_url` 可为空	有效本地激活回执、数据格式和版本兼容	只查询本地已有数据
弱网 / 断网	在线配置保留，但当前网络不可用	已有有效回执和缓存	命中继续；未命中可能等待、超时或无数据
受限模式	`getRunningMode(...)` 返回 `Restricted`	由 SDK 当前数据策略决定；结合激活、版本和查询状态定位原因	使用可接受缓存；缓存缺失时可能返回 `DataNotFound`

首次激活与首次数据准备

预置地图数据不能替代首次激活。出厂离线方案在生产流程中同时完成设备激活、数据预装、证书部署、系统时间校准和查询确认。

持久目录

HDMapServiceOptions::persistent_path 同时承载地图数据、缓存状态和激活回执：

每个服务实例使用专用目录，不与其他进程共享写入；
目录位于稳定持久分区，启动前已创建且可写；
容量覆盖 map_data_cache_space_limit，并包含回执、元数据、日志、升级和文件系统余量；
清理、备份、恢复和迁移保持文件完整性与权限；
数据损坏按受控恢复清单处理，持久根目录不作为自动清理目标。

缓存上限默认是 4096 MB。它是容量上限配置，不等于设备只需预留 4096 MB；文件系统仍需额外安全余量。

数据查询状态机

打开数据查询状态原图

`DataPending`

DataPending 表示相关数据仍在准备或下载：

只对幂等查询重试；
使用指数退避、总截止时间和取消信号；
每个请求设置最大尝试次数；
新位置或新版本出现时取消已失去业务价值的旧请求；
在后台任务中等待，不阻塞实时线程或界面线程。

`DataNotFound`

DataNotFound 表示当前版本、覆盖或缓存中没有所需数据。应用进入无高精数据路径，并按以下信息定位原因：

SDK 版本和完整地图版本；
脱敏区域、查询范围和运行形态；
交付覆盖与本地数据安装状态；
在线服务提供的版本和网络状态。

版本、覆盖、缓存或网络条件变化后，再重新发起查询。

版本选择

默认情况下 SDK 从可用版本中选择一个版本。项目需要固定、灰度或回滚验证时，可设置 hooks.map_version_selector。

#include <algorithm>
#include <string>
#include <vector>

#include "hdmap/hd_map_service.h"

void configureMapVersionSelector(
    tn::hdmap::HDMapServiceOptions& options,
    const std::string& approved_version)
{
    options.hooks.map_version_selector =
        [approved_version](
            const std::vector<std::string>& local_versions,
            const std::vector<std::string>& remote_versions) {
            const auto contains = [&approved_version](const auto& versions) {
                return std::find(
                           versions.begin(),
                           versions.end(),
                           approved_version) != versions.end();
            };

            if (contains(local_versions) || contains(remote_versions))
            {
                return approved_version;
            }

            // 空字符串表示交给 SDK 使用默认选择策略。
            return std::string{};
        };
}

在创建服务前，将批准的完整版本字符串传给 configureMapVersionSelector(options, approved_version)。

选择器返回 local_versions 或 remote_versions 中存在的完整值。返回未知值或空字符串时，SDK 使用默认策略。服务创建后调用 getMapVersion(...) 读取实际生效版本。

把版本字符串当作不透明值

完整版本可能同时表达多层数据修订。版本选择、日志和回滚都使用完整字符串。

版本切换影响

地图版本变化时：

丢弃所有 LaneGroupId、LaneId 和 LaneBoundaryId；
清理以运行时 ID 为键的业务缓存；
重新执行目标区域空间查询；
按新的空间查询结果重建几何、拓扑和导航关联。

旧版本的运行时 ID 不用于新服务实例。

运行模式（`RunningMode`）

getRunningMode(...) 返回：

模式	语义	应用行为
`Normal`	SDK 使用常规版本更新策略	分别监控网络、激活、地图版本和查询状态
`Restricted`	SDK 使用受限缓存版本；缺失数据可能不再补齐	告警并限制依赖新数据的功能，结合激活、版本和查询状态定位原因

RunningMode 不表示网络连通性或下载完成度；查询状态和地图版本提供实际数据状态。

授权过期后的连续性行为由项目交付策略决定，不是公共文档提供的统一承诺：

决策问题	应用观察	权威边界与动作
授权过期后是否创建服务	激活结果为 `Expired`	仅在项目交付策略明确允许受限缓存连续性时创建；否则停止启动并恢复授权
当前哪些数据可以使用	`RunningMode`、实际地图版本和每次查询的 `Status`	只使用本次查询返回 `OK` 的数据；`Restricted` 本身不保证目标区域、路线关联或交通可用
导航支持是否可以使用	通信可用性、导航系统输入心跳、路线匹配、交通查询状态与项目时效规则	与静态地图数据分开判断，不从 `Restricted` 推断导航支持可用
何时认为恢复完成	恢复后的激活结果、重新读取的 `RunningMode`、地图版本和目标查询结果	按项目交付的重新激活与服务恢复流程执行；网络重新连接本身不表示恢复完成

项目交付清单明确连续性策略的批准方、允许能力、恢复流程和验证点。没有这项交付策略时，应用不把 Expired 或 Restricted 当作可继续运行的授权。

区域数据更新

enableHomeAreaOta(true) 可开启交付定义的区域数据更新，默认关闭。

该接口控制区域更新开关：

区域定义、更新来源和触发条件由项目交付方案决定；
公共服务接口不提供通用的区域定义接口；
返回 OK 表示开关已接受，不表示数据下载完成；
下载状态、地图版本、缓存变化和覆盖点查询共同反映完成度。

未使用区域数据更新的项目保持默认关闭。

下载并发与网络

concurrent_download_file_count：

默认值为 5；
大于 20 的值会回落到 20；
提高并发可能降低冷缓存等待，但会增加处理器、内存、读写、网络突发和服务端压力；
弱网或低速存储项目根据交付配置设置下载并发。

预置数据与升级

预置或替换本地数据时先停止 HDMapSDK 服务，使用项目定义的原子切换或可回滚安装流程，并保持激活回执和持久目录权限。SDK 运行期间不直接覆盖缓存文件。

升级后通过 getMapVersion(...) 读取实际版本，并重新执行空间查询以获取当前运行时 ID。DataPending 采用有界等待；DataNotFound 进入无高精数据路径。