网约车集成地图

核心功能

路线规划 — 驾车路线，支持多策略（最快/最短/避高速）
导航分段 — 返回每段路的指令、距离、时长、道路名称、转弯动作
Polyline 渲染 — 路线坐标串解码后在地图上绘制折线
路况状态 — 返回畅通/缓行/拥堵/严重拥堵
逆地理编码 — 坐标转地址文字描述
降级容错 — 高德不可用→百度→直线距离兜底

核心调用流程

司机端页面（PickupPage / InTripPage） │ ▼ 调用 routeService.ts API Gateway POST /driver/auth/routePlan │ ▼ gRPC 调用 driver-srv GetRoutePlan() │ ▼ 调用 common/pkg/map_route.go │ ├─ 优先 → 高德地图 restapi.amap.com/v3/direction/driving ├─ 回退 → 百度地图 api.map.baidu.com/direction/v2/driving └─ 兜底 → Haversine 直线距离 │ ▼ 返回统一格式 Polyline 前端 Leaflet 地图渲染路线

地图集成的使用好处

1. 提升用户体验
实时路线引导 — 司机无需手动输入目的地，系统自动规划最优路线
直观展示 — 司机能清楚看到起点、终点、当前位置，乘客上车点一目了然
预估到达时间 — 显示距离和预计时长，司机心中有数

2. 保障行车安全
减少手机操作 — 司机不需要边开车边看文字地址，降低分心风险
转弯提示 — 导航分段指令（左转、右转、直行）让变道更从容

3.费用计算准确
精准距离 — 基于实际路线距离计费，而非直线距离，避免绕路纠纷
等待费用 — 等待乘客时有计时依据（5 分钟倒计时）

4.提升运营效率
智能派单 — 平台可根据司机位置就近派单
轨迹可追溯 — 行程路线记录便于后期审核、申诉处理

5.高可用容错
双 Provider 策略 — 高德为主、百度兜底，任一服务异常不影响业务
直线距离兜底 — API 全挂时仍能基于 Haversine 公式提供粗略估算

6.统一数据结构
前后端解耦 — 后端统一封装 Polyline 返回格式，前端只负责渲染，降低维护成本
可扩展性强 — 后续可轻松接入实时导航、偏航检测、多途经点等高级功能

为什么要使用地图集成

没有地图集成时的痛点

使用地图集成后

核心原因

地图是出行平台的基础能力— 打车本质上就是"从 A 点到 B 点的位移"，没有地图就不知道 A 在哪、B 在哪、怎么走、收多少钱。

常用功能调用示例

地址转经纬度（地理编码）
调用 geocode 接口，传入地址返回坐标
经纬度转地址（逆地理）
regeo 接口，定位后获取省市区街道
路线规划（驾车 / 步行 / 公交）
direction 接口，传入起点终点返回路线距离、时长
POI 搜索（周边商铺）
place 接口，搜索酒店、停车场

常见报错排查

KEY 错误 / 未配置白名单：检查平台应用域名、包名
地图空白：容器必须设置宽高
定位失败：HTTPS 环境、浏览器定位权限开启
接口返回 INVALID_KEY：密钥类型选错（Web / 小程序 / 服务端 key 不通用）