maps-location

多区域地图与定位 Skill

覆盖"中国大陆用高德、其他地区用 Google/Mapbox"的双源路由。所有 <PLACEHOLDER> 替换为项目实际值。

核心决策依据是数据的归属地（如 hotel.country / 业务实体的 country），不是用户 IP、不是手机系统区域——同一个 App 里，展示北京的店用高德，展示东京的店用 Google，由数据决定。

1. ★ 地图源路由矩阵

数据归属地	地图源	网络路径
中国大陆（country='CN'）	高德 Amap	直连（国内节点快、合规）
港澳台（HK/MO/TW）	Google Maps 或 Mapbox	Google 走海外中转；Mapbox 直连
海外（JP/US/EU/...）	Google Maps 或 Mapbox	同上

flavor 叠加约束：

• cn_android：禁 Google（对应 cn-android-flavor §1）→ 只能用高德；若 cn 包需要显示海外地图，用高德的海外底图或静态图代理，不引入 Google Maps SDK
• overseas_android / iOS：用 Google Maps 或 Mapbox；中国大陆数据仍建议走高德静态图（Google 在华不可靠）
• ★ 路由决策放后端 _resolveMapSource(entityId)，前端只拿"用哪个源 + 已代理好的 URL"，不自己判断

2. 后端源决策 + Google 在华中转

// map.service.ts
type MapSource = 'amap' | 'google' | 'mapbox';

resolveMapSource(country: string): MapSource {
  if (country === 'CN') return 'amap';
  // 港澳台 + 海外：按项目策略选 google 或 mapbox
  return process.env.OVERSEAS_MAP_PROVIDER === 'mapbox' ? 'mapbox' : 'google';
}

Google Maps API 在中国大陆被墙 → 后端经海外节点中转（对应项目 nginx gemini_proxy.conf 同款思路）：

.env:
GOOGLE_MAPS_KEY=<SERVER_SIDE_KEY>                 # ★ 服务端 key，限 IP，不下发前端
GMAPS_PROXY_BASE=https://<OVERSEAS_PROXY>/gmaps   # 海外 Nginx 反代 maps.googleapis.com
AMAP_WEB_KEY=<AMAP_WEB_SERVICE_KEY>               # 高德 Web 服务 key（服务端）
AMAP_JS_KEY=<AMAP_JS_KEY>                         # 高德 JS API key（前端/H5 用，配安全密钥）
MAPBOX_TOKEN=<MAPBOX_TOKEN>
OVERSEAS_MAP_PROVIDER=google                       # 或 mapbox

海外 Nginx 需代理三类端点（对应你项目已有的 /gmaps/static /gmaps/geocode/ /gplaces/）：

location /gmaps/static/   { proxy_pass https://maps.googleapis.com/maps/api/staticmap; }
location /gmaps/geocode/  { proxy_pass https://maps.googleapis.com/maps/api/geocode/; }
location /gplaces/        { proxy_pass https://maps.googleapis.com/maps/api/place/; }

3. 静态地图（对客 H5 / 卡片最常用）

后端统一出静态图 URL，前端只贴 <img>，天然规避 SDK 与被墙问题：

staticMapUrl(source: MapSource, lat: number, lng: number, zoom = 15): string {
  switch (source) {
    case 'amap':                                          // 高德静态图
      return `https://restapi.amap.com/v3/staticmap?location=${lng},${lat}`
        + `&zoom=${zoom}&size=750*400&markers=mid,,A:${lng},${lat}&key=${process.env.AMAP_WEB_KEY}`;
    case 'google':                                        // 经海外中转
      return `${process.env.GMAPS_PROXY_BASE}/static/?center=${lat},${lng}`
        + `&zoom=${zoom}&size=750x400&markers=color:red%7C${lat},${lng}&key=${process.env.GOOGLE_MAPS_KEY}`;
    case 'mapbox':
      return `https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/`
        + `pin-s+f00(${lng},${lat})/${lng},${lat},${zoom}/750x400?access_token=${process.env.MAPBOX_TOKEN}`;
  }
}

• ★ 高德坐标是 经度,纬度(lng,lat)；Google 是 纬度,经度(lat,lng)——顺序反了地图就飘到别的国家，这是头号 bug
• ★ 高德用 GCJ-02 火星坐标，Google/Mapbox 用 WGS-84；跨源传坐标必须转换（见 §5）