map-api-usage.md 6.9 KB
地图功能使用现状
面向后端维护者的地图能力清单。2026-10-26 更新：外卖/闪送算路和新选址支持双来源；Google保留，可通过字典回滚。百度、Mapbox保留原停用边界，禁止新增调用。
外部地图服务状态
| 服务 | 能力 | 封装位置 | 状态 |
|---|---|---|---|
| Directions 路线 | GetArea.getluxian → /utils/getluxianjvli |
Google分支兼容保留；自部署分支转换相同legs结构 | |
| Google / 自部署 | 旧附近/逆地理 | /utils/getLocationAddr(type=1)、/utils/getAddr |
按来源开关选择；SELF_HOSTED只调用MapLegacyLocationService，GOOGLE保留旧返回和语言兼容 |
| Routes API v2 | GoogleRoutesDistanceProvider（闪送报价距离） |
在用（key 走字典 sys_googlemap_key；可经距离来源开关切自部署，见下节） |
|
| Google / 自部署 | 外卖道路矩阵 | DistanceSourceRouteMatrixProvider |
普通/v2/多店共用；自配送运费同口径，自取/堂食不算路 |
| Google / 自部署 | 搜索/附近/反查/详情 | /system/map/* |
新App统一接入，token鉴权，结构一致；旧直连Google页面保留 |
| Mapbox | Directions cycling | GetArea.getmpluxian → /utils/getluxianjvliMp |
已停用（@Deprecated，端点保留） |
| Mapbox | Directions driving 耗时 | GetArea.getMotorbikeDuration |
已停用（见下方存量调用点） |
| 百度 | 逆地理 reverse_geocoding | GetArea.getarearess → /utils/getLocationAddr(type=0) |
已停用（分支保留兜底） |
| 百度 | 坐标转换 geoconv | GetArea.setlatlng → /utils/setLocat |
已停用（端点保留） |
不依赖外部地图的能力（纯数学 / 纯 DB）
| 能力 | 位置 | 实现 |
|---|---|---|
| 打车计价 | TaxiPricesController /ganyunfei |
直线距离 + taxi_prices 表 |
| 两点距离 | UserOrderController /getDistance、GetArea.getDistance |
Haversine 纯数学 |
| GCJ02→WGS84 | /utils/GCJ2TOWGS |
纯数学转换 |
| 地址簿最近地址 | /system/address/getzuijinaddress |
DB 排序 |
| 骑手派单 / 附近订单 | PosOrderMapper.getqisjvli / getstate |
MySQL st_distance DB 半径 |
| 闪送报价兜底 | FlashDeliveryRouteService |
Google 路线失败时直线距离 + distanceSource=STRAIGHT_LINE 落库 |
距离来源开关（032 US1，2026-09-29 实现）
字典 sys_map_distance_source（平台后台 系统管理-字典管理）：
| 值 | 行为 |
|---|---|
GOOGLE（默认） |
闪送Google Routes、外卖Google矩阵、新选址Google |
SELF_HOSTED |
闪送GET /route/multi、外卖POST /route/matrix、新选址自部署 |
仅在启用的字典项中，恰好一条 is_default=Y 时才采用该项的值；没有默认项、多个默认项或默认值未知时均回退 GOOGLE。安装 SQL 在 updatesql/sql.md，会创建 GOOGLE（默认）与 SELF_HOSTED 两项。切换时在后台把旧项改为 N、目标项改为 Y；后台保存字典数据会更新缓存，手工执行 SQL 后则需在后台刷新字典缓存或重启服务。新增一行选项或只改排序不会切换。回滚同理，无需发版。
实现：两类路线提供器共用 MapSourceSelector，自部署统一通过 SelfHostedMapClient，默认反代地址 http://127.0.0.1:8080/api。闪送按用户1/2传motorcycle/car；外卖默认car保留当前Google DRIVE计价口径，可显式配置自部署车型。闪送故障直线兜底并落库STRAIGHT_LINE，越界不降级；外卖失败拒绝报价，不能直线补价或部分成功。读令牌仅请求头，读超时默认18秒，与地图16秒矩阵预算协调。
地图侧配套（2026-09-29，Foodie_HCM_Map 仓库）：routing.py 泛化 calculate_route_multi（N 站点单次 OSRM 请求、逐站吸附校验）+ 新端点 /route/multi（coords=lat,lng;...，2～30 站），/route 两点入口保持不变。多站点错误中，越界或吸附失败可定位时返回从 1 开始的 point_index；OSRM NoSegment 映射为 SNAP_TOO_FAR，整体不可达 NoRoute 为 NO_ROUTE 且不伪造站点序号。032 US4 的地图侧扩展已落地，foodie 不再需要逐段累加。部署时若走地图 Nginx 的 8080 入口，map.self-hosted.base-url 应包含 /api；直接访问地图 API 服务则按实际入口配置。
边界：开关影响外卖/闪送报价、新选址及旧/getluxianjvli、/getyunfei、/getLocationAddr、/getAddr。2026-10-28起旧地址入口在SELF_HOSTED下不访问Google/Baidu或旧Redis语言缓存，失败不跨源；返回旧地址/候选结构、额外精度与确认标识，附近保留10km/最多20项。自部署不支持停用的百度type=0，防止旧页面把WGS84再次转换。前端地图页面仍由前端人员迁移，浏览器/App直连Google的请求不受此开关控制。/getyunfei保留jvli/freight/yunf字段，但改用道路矩阵和同一跳表；下单金额差异必须重报。
旧结算页/getluxianjvli参数约定为latlng1=收货点、latlng2=门店，内部按门店→收货点请求两种来源。保留绘图结构，但用于计价的首段distance.value以同源权威矩阵为准，避免Google Directions与矩阵选路差异造成重复报价仍无法下单。该兼容接口暂需路线和矩阵两次请求，升级完整deliveryQuote后只需矩阵一次。/getyunfei参数顺序则为lat1/lng1=门店、lat2/lng2=收货点，两者不要混用。
存量调用点警示
PosOrderController.setYjsdTime（state=4 订单的预计送达时间，调用方为改单状态取餐分支与测试端点/testYjsdTime）已停用（2026-09-29 标记）：方法不再使用，保留调用不影响状态流转；其依赖的getMotorbikeDuration（Mapbox driving ×1.5）因此实际无在用调用。切自部署路线源（032）时可一并清理。/utils/getLocationAddr当前在用type=1，按开关选Google或自部署。停用的type=0只在Google兼容分支保留；自部署拒绝，不伪造百度坐标。GetJvli.getOptimalRoute（Google Routes v2）全库无调用方，属死代码，不在本次标注范围。GetArea/GetJvli的历史硬编码凭据由运维单独核对限制和轮换；不能在保留Google回滚需求时直接作废全部有效密钥。新接口只读服务端字典，不复制硬编码密钥。