# 地图功能使用现状

面向后端维护者的地图能力清单。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 历史泄漏，切换自部署后应全部作废。

## 关联

- 台湾 OSM 需求差距与后续事项（2026-10-10，先记录、暂不实施）：[osm-requirements-assessment.md](../specs/032-self-hosted-map-integration/osm-requirements-assessment.md)。测试服务器已支持独立机车路网，但 foodie 自部署适配尚未传车型；现有 car-only 假设不代表该测试服务现状。
- 切换规格：`specs/032-self-hosted-map-integration/spec.md`（自部署 Foodie_HCM_Map：PostGIS 搜索 + OSRM 算路 + OpenFreeMap 底图）。2026-10-12 四项机车模型评估已验证，见 [model-evaluation.md](../specs/032-self-hosted-map-integration/model-evaluation.md)；plan/tasks 仅覆盖评估，后续生产改造尚未开始。
- 自部署地图仓库：`D:\QtwCode\foodie\Foodie_HCM_Map`