foodie-server/docs/map-api-usage.md

地图功能使用现状

面向后端维护者的地图能力清单。2026-09-29 起，百度、Mapbox 的外部接口已标记停用：代码保留、行为未变，仅加注解与本文记录，禁止新增调用。

外部地图服务状态

服务	能力	封装位置	状态
Google	Directions 路线	GetArea.getluxian → /utils/getluxianjvli	在用（key 硬编码，切换计划中作废）
Google	Nearby/Geocoding 逆地理	GetArea.getgoogle / getgoogleadd → /utils/getLocationAddr(type=1)、/utils/getAddr	在用（key 硬编码）
Google	Routes API v2	GoogleRoutesDistanceProvider（闪送报价距离）	在用（key 走字典 sys_googlemap_key；可经距离来源开关切自部署，见下节）
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）

能力	位置	实现
外卖运费估算	/utils/getyunfei	GetJvli.getDistance Haversine 直线 + pos_freight 跳表
打车计价	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（现状）
SELF_HOSTED	闪送路线距离走自部署地图（Foodie_HCM_Map GET /route/multi）

仅在启用的字典项中，恰好一条 is_default=Y 时才采用该项的值；没有默认项、多个默认项或默认值未知时均回退 GOOGLE。安装 SQL 在 updatesql/sql.md，会创建 GOOGLE（默认）与 SELF_HOSTED 两项。切换时在后台把旧项改为 N、目标项改为 Y；后台保存字典数据会更新缓存，手工执行 SQL 后则需在后台刷新字典缓存或重启服务。新增一行选项或只改排序不会切换。回滚同理，无需发版。

实现：DistanceSourceRouteProvider（@Primary 委托）+ SelfHostedRouteDistanceProvider（单次请求地图 GET /route/multi?coords=，多站点按用户顺序途经、整线道路距离；map.self-hosted.base-url 配置地址，默认 http://127.0.0.1:8080）。失败语义与 Google 路径一致——路线失败/超时/吸附失败直线兜底并落库 STRAIGHT_LINE；坐标越界（OUTSIDE_REGION）不降级，报「地址超出可服务范围」。

地图侧配套（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、逆地理等代理接口仍在 Google（属 032 US3，需 App 配合）。

存量调用点警示

• PosOrderController.setYjsdTime（state=4 订单的预计送达时间，调用方为改单状态取餐分支与测试端点 /testYjsdTime）已停用（2026-09-29 标记）：方法不再使用，保留调用不影响状态流转；其依赖的 getMotorbikeDuration（Mapbox driving ×1.5）因此实际无在用调用。切自部署路线源（032）时可一并清理。
• /utils/getLocationAddr 的 type=0 百度分支保留兜底；App 端应使用 type=1 谷歌分支。
• GetJvli.getOptimalRoute（Google Routes v2）全库无调用方，属死代码，不在本次标注范围。
• GetArea/GetJvli 硬编码的 Google key 与 Mapbox token 已随 git 历史泄漏，切换自部署后应全部作废。

关联

• 切换计划：specs/032-self-hosted-map-integration/spec.md（自部署 Foodie_HCM_Map：PostGIS 搜索 + OSRM 算路 + OpenFreeMap 底图；plan/tasks 未生成，未开工）
• 自部署地图仓库：D:\QtwCode\foodie\Foodie_HCM_Map