路线规划（步行 / 骑行 / 驾车 / 公交）

保持 demo 中 RoutePlanningActivity 写法与回调。此处统一参数差异，并给出四类调用示例。

1 通用参数（RouteParams）

参数	必/选	说明
setOrigin("lng,lat")	必	起点（经度在前，字符串）
setDestination("lng,lat")	必	终点（经度在前，字符串）
setRouteplanType(String)	驾车必	驾车类型，取值：TYPE_PICKUP("0" 接驾) / TYPE_DROPOFF("1" 送驾)
setDepartureTime(Long)	选	出发时间（Unix 秒）
setNeedPolyline(Boolean)	选	驾车如需返回 geo_list（路径点）
setEtaStrategy(Integer)	驾车选	ETA 计算策略
setWaypoints("lng,lat;lng,lat")	驾车选	途径点坐标串，分号分隔，最多 12 个
setDrivingStrategy(String)	驾车选	驾车选择策略，常量：DRIVING_STRATEGY_DEFAULT("1") / _TIME_FIRST("2") / _SHORT_DISTANCE("5") / _HIGHWAY_FIRST("11") / _NO_HIGHWAY("13")
setShowFields("segments,cost")	驾车选	返回扩展信息，逗号分隔；segments 分级路况、cost 费用
setRouteNum(Integer)	选	驾车/公交返回方案个数（公交 1-10，默认 5）
setCity("城市名")	公交必填	仅公交需要城市；其他模式不必填
setStrategy(Integer)	公交选	公交策略（如 BUS_STRATEGY_MIN_TRANSFER）

注意：请求坐标是 "lng,lat" 字符串；返回路径点在 RouteResponse.results[].routes[].geo_list 里，字段名为 latitude/longitude。

2 调用示例（四种模式）

RoutePlanningService routeSvc = mapClient.getRoutePlanningService();

// —— 步行 ——
routeSvc.planWalkingRouteAPI(
    RouteParams.create()
        .setOrigin("116.2807,40.04811")
        .setDestination("116.30334,40.05203"),
    new RpcRequestUtils.Callback<RouteResponse>() { /* 回调同现有写法 */ }
);

// —— 骑行 ——
routeSvc.planBikingRouteAPI(
    RouteParams.create()
        .setOrigin("116.2807,40.04811")
        .setDestination("116.30334,40.05203"),
    new RpcRequestUtils.Callback<RouteResponse>() { /* 回调同现有写法 */ }
);

// —— 驾车（若需路径点请开启 needPolyline） ——
routeSvc.planDrivingRouteAPI(
    RouteParams.create()
        .setOrigin("116.2807,40.04811")
        .setDestination("116.30334,40.05203")
        .setRouteplanType(RouteParams.TYPE_DROPOFF)           // 必填："0"接驾/"1"送驾
        .setDepartureTime(System.currentTimeMillis() / 1000)  // 可选
        .setNeedPolyline(true)                                // 返回 geo_list
        .setWaypoints("116.397128,39.916527;116.407396,39.904200") // 可选，最多12个
        .setDrivingStrategy(RouteParams.DRIVING_STRATEGY_TIME_FIRST) // 可选
        .setShowFields("segments,cost")                       // 可选：分级路况/费用
        .setRouteNum(3),                                      // 可选：返回方案数
    new RpcRequestUtils.Callback<RouteResponse>() { /* 回调同现有写法 */ }
);

// —— 批量驾车（一次提交多组起终点，统一回调） ——
java.util.List<RouteParams> batch = new java.util.ArrayList<>();
batch.add(RouteParams.create()
    .setOrigin("116.2807,40.04811")
    .setDestination("116.30334,40.05203")
    .setRouteplanType(RouteParams.TYPE_DROPOFF));
batch.add(RouteParams.create()
    .setOrigin("116.40,39.90")
    .setDestination("116.45,39.92")
    .setRouteplanType(RouteParams.TYPE_PICKUP));
routeSvc.planBatchDrivingRoutesAPI(
    batch,
    new RpcRequestUtils.Callback<RouteResponse>() { /* 回调同现有写法；results 顺序与入参一致 */ }
);

// —— 公交（city 必填，可选策略/方案数） ——
routeSvc.planBusRouteAPI(
    RouteParams.create()
        .setOrigin("116.2807,40.04811")
        .setDestination("116.30334,40.05203")
        .setCity("北京市")                                      // 必填
        .setStrategy(RouteParams.BUS_STRATEGY_MIN_TRANSFER)     // 可选
        .setRouteNum(3),                                        // 可选
    new RpcRequestUtils.Callback<BusRouteResponse>() { /* 回调同你现有写法 */ }
);

3 步行/骑行/驾车 — 响应结构（RouteResponse）

提示：v3 协议层级为 results[] → routes[]。results[] 为请求 pack（与批量入参顺序一致），routes[] 为该 pack 内的多条候选路线。距离/时长/路径点等位于 routes[]。

字段路径	类型	可空	单位/取值	说明	服务端字段
status	int	否	—	10000 成功	status
msg	string	是	—	文本提示	msg
traceId	string	是	—	TraceId	trace_id
results	array<object>	是	—	请求 pack 列表（与入参顺序一致）	results
results[].errcode	int	否	—	pack 错误码（0 正常）	errcode
results[].errmsg	string	是	—	pack 错误信息	errmsg
results[].routes	array<object>	是	—	候选路线列表（一般取第一个）	routes
results[].routes[].dist	double	是	米	总距离	dist
results[].routes[].duration	int	是	秒	总时长	duration
results[].routes[].tag	string	是	—	路线标签（如"推荐"等，服务端定义）	tag
results[].routes[].geoList	array<object>	是	—	结构化路径点（需 needPolyline=true）	geo_list
results[].routes[].geoList[].latitude	double	是	—	路径点纬度	latitude
results[].routes[].geoList[].longitude	double	是	—	路径点经度	longitude

读取示例（取第一个 pack 的第一条路线：总距离/时长 + 起终点）

RouteResponse rr = data;
if (rr != null && rr.results != null && !rr.results.isEmpty()) {
  RouteResponse.Result r0 = rr.results.get(0);
  RouteResponse.Route route = (r0.routes != null && !r0.routes.isEmpty()) ? r0.routes.get(0) : null;
  if (route != null) {
    double distM = route.dist == null ? 0.0 : route.dist;
    int durS = route.duration == null ? 0 : route.duration;
    RouteResponse.GeoPoint start = (route.geoList != null && !route.geoList.isEmpty()) ? route.geoList.get(0) : null;
    RouteResponse.GeoPoint end = (route.geoList != null && !route.geoList.isEmpty()) ? route.geoList.get(route.geoList.size()-1) : null;
    String line = "路线: 距离=" + distM + "米 | 时长=" + durS + "秒"
                + " | tag=" + stringOrDash(route.tag)
                + " | 起点=" + stringOrDash(start == null ? null : start.latitude) + ","
                + stringOrDash(start == null ? null : start.longitude)
                + " | 终点=" + stringOrDash(end == null ? null : end.latitude) + ","
                + stringOrDash(end == null ? null : end.longitude);
    // tv.setText(line);
  }
}

批量驾车结果遍历：results[] 与入参 List<RouteParams> 一一对应，遍历时建议同时检查 results[i].errcode 是否为 0，再读取 results[i].routes[0]。

---

4 公共交通路径规划 — 响应结构（BusRouteResponse）

A. 顶层与方案字段

字段路径	类型	可空	单位/取值	说明	服务端字段
status	int	否	—	业务状态码，10000 成功	status
msg	string	是	—	文本提示	msg
traceId	string	是	—	TraceId	trace_id
results	array<object>	是	—	方案列表	results
results[].origin	string	是	"lng,lat"	方案起点	origin
results[].destination	string	是	"lng,lat"	方案终点	destination
results[].cost	int	是	分	总费用（展示/100）	cost
results[].duration	int	是	秒	总时长	duration
results[].distance	double	是	米	总距离	distance
results[].walkingDistance	double	是	米	总步行距离	walking_distance
results[].segments	array<object>	是	—	由步行/公交段组成	segments

B. 分段（segments）与步行段（walking）

字段路径	类型	可空	单位/取值	说明	服务端字段
results[].segments[].mode	string	是	WALKING / TRANSIT	段类型	mode
results[].segments[].walking	object	是	—	步行段详情	walking
results[].segments[].walking.origin	string	是	"lng,lat"	步行起点	origin
results[].segments[].walking.destination	string	是	"lng,lat"	步行终点	destination
results[].segments[].walking.distance	double	是	米	步行段距离	distance
results[].segments[].walking.duration	int	是	秒	步行段时长	duration
results[].segments[].walking.steps	array<object>	是	—	步行分步（可选）	steps

C. 步行分步（walking.steps[]）

字段路径	类型	可空	单位/取值	说明	服务端字段
results[].segments[].walking.steps[].instruction	string	是	—	指令（文字描述）	instruction
results[].segments[].walking.steps[].road	string	是	—	道路名	road
results[].segments[].walking.steps[].distance	double	是	米	分步距离	distance
results[].segments[].walking.steps[].duration	int	是	秒	分步时长	duration
results[].segments[].walking.steps[].polyline	string	是	"lng,lat;..."	分步折线	polyline
results[].segments[].walking.steps[].action	array<string>	是	—	行为（语义标签）	action
results[].segments[].walking.steps[].actionCode	array<int>	是	—	行为编码	action_code
results[].segments[].walking.steps[].direction	array<string>	是	—	方向描述	direction

D. 公交段（metrobus[]）与站点（BusStop）

字段路径	类型	可空	单位/取值	说明	服务端字段
results[].segments[].metrobus	array<object>	是	—	公交段（可能多条线路）	metrobus
results[].segments[].metrobus[].name	string	是	—	线路名（展示主文案）	name
results[].segments[].metrobus[].id	string	是	—	线路 ID	id
results[].segments[].metrobus[].type	int	是	—	线路类型（服务端定义）	type
results[].segments[].metrobus[].departureStop	object	是	—	上车站	departure_stop
results[].segments[].metrobus[].departureStop.name	string	是	—	上车站名	name
results[].segments[].metrobus[].departureStop.id	string	是	—	上车站 ID	id
results[].segments[].metrobus[].departureStop.location	string	是	"lng,lat"	上车站坐标	location
results[].segments[].metrobus[].arrivalStop	object	是	—	下车站	arrival_stop
results[].segments[].metrobus[].arrivalStop.name	string	是	—	下车站名	name
results[].segments[].metrobus[].arrivalStop.id	string	是	—	下车站 ID	id
results[].segments[].metrobus[].arrivalStop.location	string	是	"lng,lat"	下车站坐标	location
results[].segments[].metrobus[].startStation	string	是	—	首发站名（线路端点）	start_station
results[].segments[].metrobus[].terminalStation	string	是	—	终到站名（线路端点）	terminal_station
results[].segments[].metrobus[].distance	double	是	米	本段距离	distance
results[].segments[].metrobus[].duration	int	是	秒	本段时长	duration
results[].segments[].metrobus[].cost	int	是	分	本段费用	cost
results[].segments[].metrobus[].firstTime	string	是	"HH:mm"	首班时间	first_time
results[].segments[].metrobus[].lastTime	string	是	"HH:mm"	末班时间	last_time
results[].segments[].metrobus[].polyline	string	是	"lng,lat;..."	公交折线	polyline
results[].segments[].metrobus[].viaStopsCount	int	是	—	途经站数量	via_stops_count
results[].segments[].metrobus[].viaStops	array<object>	是	—	途经站列表	via_stops
results[].segments[].metrobus[].viaStops[].name	string	是	—	站名	name
results[].segments[].metrobus[].viaStops[].id	string	是	—	站点 ID	id
results[].segments[].metrobus[].viaStops[].location	string	是	"lng,lat"	坐标	location

备注：距离统一为米、时长为秒、费用为分；坐标字符串统一 "lng,lat"；折线统一 "lng,lat;lng,lat;..."。

读取示例（Top1 方案 + 第一段公交上/下车站）

BusRouteResponse br = data;
if (br != null && br.results != null && !br.results.isEmpty()) {
  BusRouteResponse.BusRouteResult r0 = br.results.get(0);
  String cost = (r0.cost == null) ? "-" : String.format(java.util.Locale.US, "%.2f元", r0.cost / 100.0);
  int mins = r0.duration == null ? 0 : r0.duration / 60;

  String lineName = "-", onStop = "-", offStop = "-";
  if (r0.segments != null) {
    for (BusRouteResponse.BusSegment seg : r0.segments) {
      if ("TRANSIT".equals(seg.mode) && seg.metrobus != null && !seg.metrobus.isEmpty()) {
        BusRouteResponse.BusDetail bus = seg.metrobus.get(0);
        lineName = stringOrDash(bus.name);
        onStop = (bus.departureStop != null) ? stringOrDash(bus.departureStop.name) : "-";
        offStop = (bus.arrivalStop != null) ? stringOrDash(bus.arrivalStop.name) : "-";
        break;
      }
    }
  }

  String line = "公交Top1: 起点=" + stringOrDash(r0.origin)
              + " | 终点=" + stringOrDash(r0.destination)
              + " | 费用=" + cost + " | 总时长≈" + mins + "分钟"
              + " | 第一段=" + lineName + "（" + onStop + " → " + offStop + "）";
  // tv.setText(line);
}

---