Regional数据下载

1. 功能介绍

RegionalDownloadManager 用于管理分区域地图数据（RDM）下载生命周期，支持：

查询区域数据状态
启动/暂停/恢复/取消下载
应用已下载数据
清理下载缓存与卸载已安装数据

该能力支持以下数据工作模式：

Pure Streaming mode（无预装数据）
Hybrid mode（有预装数据）

与流式地图下载不同，Regional 数据下载更偏向“按区域包管理”的离线能力建设，适合车机预下载、区域扩容、分包更新等场景。

主要流程（按数据域）：

阶段	Nav 数据	Search 数据
`startDownload`	将目标区域数据下载到 Streaming 目录。	先下载搜索区域压缩包。
`applyData`	将 Streaming 目录中的已下载区域数据复制到 `downloadedRegionalDataDir`（`SDKOptions.Builder.setRegionalDataDir(...)`）目录，使其成为 base 数据的一部分。	解压压缩包并落地为本地搜索数据，同时删除对应压缩包。
`purgeDownloadData`	删除 apply 之前仍留在 Streaming 目录中的对应下载数据（Nav 数据有效）。	Search 数据通常不需要此步骤。
`removeInstalledData`	删除 apply 之后已安装到本地的数据（即已进入 base 数据部分的数据）。	删除 apply 之后已安装的本地搜索数据。

状态流转图（RegionalDownloadManager）：

Regional DataState 状态流转图

使用前置条件（务必确认）：

项目云端数据必须已支持 Regional download 能力，否则本功能不可用。
对存量车，如果本地已预装“不支持 Regional download”的旧数据，HMI 需先自行删除该数据，再启用新功能；否则会导致 Regional 下载/应用流程无法正常使用。

2. 核心接口

入口类：com.telenav.sdk.rdm.api.RegionalDownloadManager

接口	说明
`getInstance()`	获取单例
`initialize(context, sdkOptions, mode)`	初始化下载管理器（进程内先调用）
`dispose()`	释放资源，后续使用前需重新 `initialize`
`startDownload(dataId, progressCallback)`	启动下载
`pauseDownload(dataId)`	暂停下载
`resumeDownload(dataId, progressCallback)`	恢复下载
`cancelDownload(dataId)`	取消下载
`applyData(dataId, stateCallback)`	应用已下载数据
`queryDataStatus(dataId)`	查询当前区域状态（WorkerThread）
`purgeDownloadData(dataId)`	清理临时下载数据（WorkerThread）
`removeInstalledData(dataId)`	卸载已安装区域数据（WorkerThread，可抛异常）

初始化配置接口（SDKOptions / NavSDKOptions）：

接口	说明
`SDKOptions.Builder.setRegionalDataDir(downloadedRegionalDataDir)`	设置 Regional 下载数据目录（需可读写）。若同时设置 `sdkDataDir`，两者应保持一致，避免数据目录不一致导致初始化/加载异常。
`NavSDKOptions.Builder.enableDownloadMapData(enabled)`	开关地图数据下载能力。`false` 时不再触发地图数据下载流程；RDM 场景需要保持 `true`。
`NavSDKOptions.Builder.setMapStreamingSpaceLimit(size)`	设置常规流式地图数据空间上限（默认 1GB，最小 512MB）。达到上限后会优先清理旧的常规流式数据。
`NavSDKOptions.Builder.setSpaceDownloadSizeLimit(size)`	设置“区域包（space）下载”空间上限（默认 512MB，范围 128MB~512GB，超范围会被 SDK 自动收敛）。达到上限后不会再启动新的 space 下载任务。

说明：setMapStreamingSpaceLimit(...) 与 setSpaceDownloadSizeLimit(...) 共同决定地图下载总体占用上限；两类空间预算建议由 HMI 按项目磁盘策略统一规划。

3. 关键模型

3.1 DownloadMode

枚举值	说明
`NAV_ONLY`	仅下载导航数据
`SEARCH_ONLY`	仅下载搜索数据
`NAV_AND_SEARCH`	同时下载导航与搜索数据

3.2 RegionalDataId

RegionalDataId 用于标识下载范围：

spaceNames: List<String>：导航域最小下载单元（space）
subRegionId: String：搜索域最小下载单元（sub-region）

约束：两者至少提供一个，否则构造参数非法。

项目约束：当前项目支持的 spaceNames 与 subRegionId 列表由 HMI 侧维护；实际使用前需先与泰为产品经理确认可用清单与版本口径。

3.3 RegionalDownloadProgress（下载进度）

字段	说明
`progress`	聚合总进度（0~100）
`state`	当前进度状态（`ProgressState`）
`navProgress`	导航域进度（可空）
`searchProgress`	搜索域进度（可空）

ProgressState 取值：

UNINITIALIZED
RUNNING
SUCCEEDED
FAILED
CANCELED
PAUSED

3.4 RegionalDataInfo（状态查询）

queryDataStatus 返回 RegionalDataInfo，包含：

state: DataState（聚合状态）
navStatus: DataInfo?
searchStatus: DataInfo?

DataState 常见阶段：

UPDATE_TO_DATE
HAS_NEW_VERSION
PARTIAL_DOWNLOADED
DOWNLOADED_BUT_NOT_APPLIED
APPLIED
FAILED_TO_APPLY
FAILED_TO_LOAD_NEW_DATA
DATA_ERROR
UNSUPPORTED

4. 典型流程

getInstance()
   ↓
initialize(context, sdkOptions, mode)
   ↓
queryDataStatus(dataId)                 // 先看当前状态
   ↓
startDownload(dataId, progressCallback)
   ↓
RUNNING / PAUSED / RESUME / CANCELED / SUCCEEDED
   ↓
applyData(dataId, stateCallback)        // 下载成功后应用
   ↓
queryDataStatus(dataId) == APPLIED

5. 示例代码

val manager = RegionalDownloadManager.getInstance()

val inited = manager.initialize(
    context = appContext,
    sdkOptions = sdkOptions,
    mode = DownloadMode.NAV_AND_SEARCH
)
if (!inited) return

val dataId = RegionalDataId(
    spaceNames = listOf("NA_US_CA"),
    subRegionId = "US-CA"
)

manager.startDownload(dataId, object : RegionalDownloadManager.ProgressCallback {
    override fun onProgress(progress: RegionalDownloadProgress) {
        // progress.progress / progress.state / progress.navProgress / progress.searchProgress
    }
})

// 下载完成后应用数据
manager.applyData(dataId) { state ->
    // state: ProgressState
}

6. 错误码与返回值

多数操作返回 Int 结果码，常见值来自 RegionalDownloadErrorCode：

错误码	值	说明
`OK`	0	请求被接受/执行成功
`UNKNOWN`	-1	未知错误
`UNSUPPORTED`	-6	当前环境不支持
`DATA_SWITCHING`	-7	数据切换中
`INSUFFICIENT_STORAGE`	-1001	存储空间不足
`INVALID_PARAMETER`	3	参数非法
`DATA_NOT_AVAILABLE`	6	数据不可用
`LAST_UPDATE_ONGOING`	15	上一次更新仍在进行
`INVALID_CALL_STATE`	16	调用时机/状态不合法
`UNKNOWN_SEARCH_ERROR`	1024	搜索域未知错误

7. 线程与调用注意事项

initialize(...)、queryDataStatus(...)、purgeDownloadData(...)、removeInstalledData(...) 标注 @WorkerThread，不要在主线程执行。
removeInstalledData(...) 可能抛出 SdkException，请显式捕获。
start/pause/resume/cancel/apply 为异步受理型接口，返回 0 仅表示“请求已接收”，最终结果需看回调或后续状态查询。
dispose() 后实例失效，后续操作前必须重新 initialize(...)。