更优的路

功能介绍

导航过程中，SDK 在达到一定条件时开始检查是否存在更优路线。发现候选路线且满足阈值时，通过 NavigationEventListener.onBetterRouteDetected 推送 BetterRouteProposal（可选更优路，需 HMI 决策是否切换）。

用户确认后调用 NavigationSession.acceptRouteProposal(proposal)；SDK 处理成功后，换路进度由换路通知的 onNavigationRouteUpdating 通知（reason 常为 SAVE_TIME 等）。

与自动换路的区别：

回调	性质	HMI 动作
`onBetterRouteDetected`	可选更优路提案（定时/路况等）	展示对比，用户确认后 `acceptRouteProposal`
`onNavigationRouteUpdating`	换路已在进行或已完成（偏航、内部更新等）	按 `status` 刷新路线上下文与地图

前置条件： 已注册 NavigationEventListener 并持有 NavigationSession（startNavigation 返回值）。

核心接口

接口	说明
`NavigationEventListener.onBetterRouteDetected(proposal)`	检测到更优路候选或检测结束（无可选更优路/出错）
`NavigationSession.acceptRouteProposal(proposal)`	用户接受提案；成功后会触发 `onNavigationRouteUpdating`
`NavigationServiceOptions.Builder.setBetterRouteOptions(...)`	创建 `NavigationService` 时配置检测策略
`NavigationSession` 动态 API	导航中调整定时检测、路况触发、节省时长阈值等

流程概览

导航中（默认定时 + 路况检测开启）
        ↓
onBetterRouteDetected(proposal)
        ↓
status == NEW_ROUTE_DETECTED → HMI 展示 savedTime / 新路对比
        ↓
用户确认 → navigationSession.acceptRouteProposal(proposal)
        ↓
onNavigationRouteUpdating(STARTED → SUCCEEDED)   ← 见「换路通知」

status == NO_BETTER_ROUTE 表示已检测但当前路仍最优，一般无需弹窗。status == ERROR_OCCURRED 表示求路出错。

`onBetterRouteDetected` 与 `BetterRouteProposal`

fun onBetterRouteDetected(proposal: BetterRouteProposal)

收到后先读 proposal.status，再读 reason、betterRoute、savedTime 等。

`BetterRouteProposal.Status`

状态	说明
`NEW_ROUTE_DETECTED`	发现更优候选路；可读 `betterRoute`、`savedTime`
`NO_BETTER_ROUTE`	已触发检测（如路况），但当前路仍最优
`ERROR_OCCURRED`	求路过程出错

`BetterRouteProposal.Reason`

常量	说明
`SAVE_TIME`	预计节省时间（定时/路况触发的主场景）
`AVOID_BLOCKING_TRAFFIC`	避开阻塞交通（乘用车未开 `avoidTrafficClosure` 时，或卡车阻塞路况）
`AVOID_TIMED_RESTRICTION`	仅卡车：避开限时通行；乘用车限时限制通常直接自动换路，不经过本提案
`CHARGING_STATION_UNAVAILABLE`	仅 EV：前方规划充电站不可用
`LOW_ARRIVAL_BATTERY_LEVEL`	仅 EV：预计到达电量过低

常用字段

字段	说明
`betterRoute`	候选更优路线（`Route`）；Cloud 求路通常为完整引导，Onboard 可能先给部分引导
`currentRoute`	当前被监控的导航路线
`savedTime`	相较当前路预计节省时间（秒）
`blockingIncidents` / `blockingFlows`	`AVOID_BLOCKING_TRAFFIC` 时，当前路上的阻塞事件/交通流
`timeRestrictionEdges`	`AVOID_TIMED_RESTRICTION` 时，受限 edge 信息
`stationInfo`	`CHARGING_STATION_UNAVAILABLE` 时，充电站信息
`lowArrivalBatteryInfo`	`LOW_ARRIVAL_BATTERY_LEVEL` 时，低电量信息

接受更优路：`acceptRouteProposal`

val accepted = navigationSession.acceptRouteProposal(proposal)

提案被接受后，新路会应用到导航会话及关联组件。
返回 true 表示执行成功；随后关注 onNavigationRouteUpdating 完成地图与路线上下文更新。
返回 false 表示未接受成功（例如确认前路线已变，或已错过通往更优路的岔口）。
仅当 proposal.status == NEW_ROUTE_DETECTED 且用户确认切换时调用。

创建时配置：`BetterRouteOptions`

val navigationService = NavigationService.Factory.createInstance(
    NavigationServiceOptions.Builder()
        .setBetterRouteOptions(
            BetterRouteOptions.Builder()
                .setCheckIntervalSeconds(300)              // 定时检测间隔，[1, 3600] 秒；超范围则关闭定时检测
                .setMinTrafficDegradationToCheck(10)       // 路况恶化阈值（占剩余 ETT 的 %），默认 10
                .setMinRemainingTimeToCheck(600)            // 剩余行程至少多少秒才检测，[60, 1200]，默认 600
                .setMinTimeBeforeSwitchToBetterRoute(60)    // 切换前当前路至少剩余行驶时间，[20, 600]，默认 60
                .setMinTimeSavingPercentToConsiderBetter(10) // 新路须比当前路快多少 %，[0, 70]，默认 10；0 表示任意新路即更优
                .setMinAbsoluteTimeSavingToConsiderBetter(600) // 或绝对节省至少多少秒，默认 600；与百分比满足其一即可
                .build()
        )
        .build()
)

Builder 方法	说明	默认（未设置时）
`setCheckIntervalSeconds`	定时检测间隔（秒）	约为路线 ETT 的 20%，上限 1 小时
`setMinTrafficDegradationToCheck`	路况恶化占剩余 ETT 的百分比，达到则触发检测	10
`setMinRemainingTimeToCheck`	距下一停靠点/终点剩余时间下限（秒）	600
`setMinTimeBeforeSwitchToBetterRoute`	偏离当前路进入新路前，当前路最少剩余行驶时间（秒）	60
`setMinTimeSavingPercentToConsiderBetter`	相对节省时间阈值（%）	10
`setMinAbsoluteTimeSavingToConsiderBetter`	绝对节省时间阈值（秒）	600

相对与绝对节省时间为或关系：满足其一即视为「足够更优」。

导航中动态配置：`NavigationSession`

startNavigation 返回的 NavigationSession 可在导航过程中调整（会覆盖创建时的部分设置）：

API	说明	默认
`enableBetterRouteCheckTimer(enable)`	开启/关闭定时更优路检测	开启
`enableTrafficHandling(enable)`	开启/关闭路况触发更优路检测	开启
`setBetterRouteCheckInterval(seconds)`	定时检测间隔 `[1, 3600]`；超范围则关闭定时器	继承 `BetterRouteOptions`
`setMinTimeSavedPercentage(percentage)`	相对节省时间阈值 `[0, 70]` %；`0` 表示任意新路即更优；覆盖创建时百分比设置	10
`setBetterRouteTrafficMinDegradation(percentage)`	路况恶化阈值 `[0, 100]` %	10

以上动态 API 在更优路检测器不可用时返回 false（setMinTimeSavedPercentage 无返回值）。

navigationSession?.apply {
    enableBetterRouteCheckTimer(true)
    enableTrafficHandling(true)
    setBetterRouteCheckInterval(180)
    setMinTimeSavedPercentage(15)
    setBetterRouteTrafficMinDegradation(10)
}

示例代码

override fun onBetterRouteDetected(proposal: BetterRouteProposal) {
    when (proposal.status) {
        BetterRouteProposal.Status.NEW_ROUTE_DETECTED -> {
            val savedSec = proposal.savedTime ?: 0
            mainHandler.post {
                showBetterRouteDialog(
                    savedTimeSec = savedSec,
                    onAccept = {
                        if (navigationSession?.acceptRouteProposal(proposal) == true) {
                            // 换路进度见 onNavigationRouteUpdating
                        }
                    }
                )
            }
        }
        BetterRouteProposal.Status.NO_BETTER_ROUTE -> {
            // 可选：调试日志，一般无需打扰用户
        }
        BetterRouteProposal.Status.ERROR_OCCURRED -> {
            Log.w(TAG, "better route check failed: ${proposal.reason}")
        }
    }
}

override fun onNavigationRouteUpdating(progress: BetterRouteUpdateProgress) {
    // 接受提案后的换路结果，见「换路通知」
}

注意事项

可选性： onBetterRouteDetected 不会自动换路；未调用 acceptRouteProposal 则继续当前路线。
回调线程： Message 线程，弹窗与 UI 请切主线程。
先读 status： 仅 NEW_ROUTE_DETECTED 时展示切换 UI 并调用 acceptRouteProposal。
acceptRouteProposal 可能失败： 返回 false 时提案未生效。常见原因：用户确认前导航路线已发生变化，或车辆已驶过通往更优路的岔口/合流点，提案不再有效。
与备选路区分： 备选路提供的是与当前导航路线不同的路线选择，不一定是更优路；切换走 acceptAlternativeRoute，对应 onNavigationRouteUpdating 的 ALTERNATIVE_ROUTE_SELECTED，见备选路。
驾驶安全： 提示频率与交互方式应克制，避免频繁打断驾驶员；用户拒绝后可做短时免打扰。

更优的路

功能介绍

核心接口

流程概览

onBetterRouteDetected 与 BetterRouteProposal

BetterRouteProposal.Status

BetterRouteProposal.Reason