EV算路

1. 功能说明

EV 算路用于在路线规划阶段同时考虑电量与充电策略，输出“可到达”的导航路线。
与普通算路相比，EV 算路会基于车辆电量状态和 ChargingPlanPreference，在必要时自动规划充电站停靠点，并在结果中返回对应充电动作信息。

说明：能力本质依赖云端 EV 规划数据与站点可用性，集成时应按“在线能力”使用。

2. 核心接口

接口	说明
`NavigationService.createNavigableEvTripPlanTask(request)`	创建 EV 算路任务（默认配置）
`NavigationService.createNavigableEvTripPlanTask(request, config)`	创建 EV 算路任务（可选 `HybridClientConfig`）
`EvTripPlanRequest.Builder`	构建 EV 算路请求
`ChargingPlanPreference.Builder`	配置充电规划偏好

补充：

任务返回仍为 Task<RouteResponse>，状态码与普通算路一致（参考算路结果）。

3. 请求模型

3.1 EvTripPlanRequest

EvTripPlanRequest 在起终点、途经点、路径偏好上与普通 RouteRequest 类似，核心差异是增加了 chargingPlanPreference。

字段 / Builder	说明
`startLocation` / `destinationLocation`	起点与终点，必填
`setWaypoints(...)`	途经点（可选）
`routePreferences(...)`	路径偏好（可选）
`setChargingPlanPreference(...)`	EV 充电规划偏好（关键）
`setRouteCount(...)`	请求路线条数，默认 `1`，建议 `< 4`
`setHeading(...)` / `setSpeedInMps(...)`	起步方向和速度（可选）；默认分别为 `-1`（未知方向）和 `0`

补充说明（与 EvTripPlanRequest.kt 对齐）：

Builder(start, destination) 初始化时，如果 start.location 携带 bearing/speed，会自动写入 heading/speedInMps。
setWaypoints(...) 每次调用会覆盖之前设置的途经点列表。
routeCount 建议小于 4（性能建议），默认值为 1。

3.2 ChargingPlanPreference（关键参数）

参数	说明
`setEnableChargingPlanning(boolean)`	关键开关：是否启用自动充电规划。关闭后不自动补充充电动作，且导航过程中也不会再根据当前电量动态规划充电站，存在不可达风险
`setPlanningStrategy(...)`	规划策略：高功率优先 / 少绕路优先 / 备选路线策略
`setPreferredConnectorTypes(...)`	偏好充电枪型
`setPreferredChargerBrands(...)`	偏好充电品牌
`setPreferredChargerEmspIds(...)`	偏好 eMSP
`setPreferredArrivalBatteryLevel(...)`	到达终点期望电量（`[0,90]`）
`setPreferToChargeUponArrival(...)`	是否偏好到达后再充电
`setPreferredStartChargingBatteryLevel(...)`	期望开始充电电量百分比（`[10,90]`）
`setPreferredStopChargingBatteryLevel(...)`	期望停止充电电量百分比（`[50,100]`）
`setChargingStationBlocklist(...)`	禁用站点列表（Entity ID）

约束建议： - 到达电量阈值设置过高会提升“无可行充电方案”概率。

相关导航阶段行为与事件处理，见 EV导航。

4. 计算 EV 路线

4.1 示例：构建请求并执行任务

val chargingPreference = ChargingPlanPreference.Builder()
    .setEnableChargingPlanning(true)
    .setPlanningStrategy(PlanningStrategy.HigherPowerChargerStrategy)
    .setPreferredArrivalBatteryLevel(20)
    .setPreferredStartChargingBatteryLevel(20)
    .setPreferredStopChargingBatteryLevel(80)
    .build()

val request = EvTripPlanRequest.Builder(
    GeoLocation(37.386300, -122.005090),
    GeoLocation(37.398760, -121.977360)
)
    .setChargingPlanPreference(chargingPreference)
    .setRouteCount(1)
    .build()

val navigationService = NavigationService.Factory.createInstance()
val task = navigationService.createNavigableEvTripPlanTask(request)

task.runAsync { routeResponse ->
    if (routeResponse.response.status == DirectionErrorCode.OK &&
        !routeResponse.response.result.isNullOrEmpty()
    ) {
        val route = routeResponse.response.result[0]
        // 处理 route
    }
    task.dispose()
}

4.2 多途经点 EV 算路

val request = EvTripPlanRequest.Builder(origin, destination)
    .setWaypoints(
        listOf(
            Waypoint(GeoLocation(37.398160, -121.977160)),
            Waypoint(GeoLocation(37.328760, -121.927360))
        )
    )
    .setChargingPlanPreference(chargingPreference)
    .build()

5. 结果读取（EV 特有）

EV 路线中的充电动作挂在 Route.travelPoints[*].chargingPlan 上：

chargingPlan == null：该点无充电动作；
chargingPlan != null：该点包含计划充电动作（到达/离开电量、充电时长等）。

6. 注意事项

EV 算路建议在联网场景使用；网络不佳可能影响充电站选择质量或导致失败。
车辆 EV 参数（电池、电量、连接器）应先完成配置，再发起 EV 算路。
Task 使用后需调用 dispose()，避免资源泄漏。
求路成功后进入导航阶段的 EV 事件处理，参考 EV导航。

字段	说明
`TravelPoint.autoPlanned`	是否系统自动补充的点（常见于 EV 自动补站）
`ChargingPlan.chargingInstruction.chargingDuration`	预计充电时长（秒）
`ChargingPlan.chargingInstruction.arrivalBatteryLevel`	到站预计电量（%）
`ChargingPlan.chargingInstruction.departureBatteryLevel`	离站建议电量（%）
`ChargingPlan.chargingStation.chargingConnector.maxPower`	站点可用最大充电功率（kW）