# 地图功能使用现状

面向后端维护者的地图能力清单。2026-10-26 更新：外卖/闪送算路和新选址支持双来源；Google保留，可通过字典回滚。百度、Mapbox保留原停用边界，禁止新增调用。

## 外部地图服务状态

| 服务 | 能力 | 封装位置 | 状态 |
|---|---|---|---|
| Google | Directions 路线 | `GetArea.getluxian` → `/utils/getluxianjvli` | Google分支兼容保留；自部署分支转换相同legs结构 |
| Google / 自部署 | 旧附近/逆地理 | `/utils/getLocationAddr`(type=1)、`/utils/getAddr` | 按来源开关选择；SELF_HOSTED只调用MapLegacyLocationService，GOOGLE保留旧返回和语言兼容 |
| 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回滚需求时直接作废全部有效密钥。新接口只读服务端字典，不复制硬编码密钥。

## 关联

- 台湾真实路段、车型法规、时速、动态限制、全境性能与地址体检仍待部署验收，详见[差距记录](../specs/032-self-hosted-map-integration/osm-requirements-assessment.md)。本地适配现已显式传车型，不代表生产已部署。
- 切换规格：[032](../specs/032-self-hosted-map-integration/spec.md)。当前双地图实施计划/任务与历史机车评估分别记录；[前端接入](../specs/032-self-hosted-map-integration/frontend-app-integration.md)、[发布与回滚](../specs/032-self-hosted-map-integration/release-runbook.md)。
- 自部署地图仓库：`D:\QtwCode\foodie\Foodie_HCM_Map`