逆地理编码（坐标转地址）#

验证状态：已源码核验、未联调（上游 Nominatim/Photon 服务不在本工作区）；适用基线：源码归纳 @ 2026-09-14

用途与场景#

把经纬度解析为地址文本。Web 用同一双提供者策略调用两个操作：先 Nominatim、校验不过再用 Photon 兜底，结果进 IndexedDB 缓存（TTL/容量由 location-cache 管理）。中心 Java 服务不参与，/nominatim、/photon 前缀由部署反向代理改写转发。

使用位置#

页面/功能	角色或空间分支
双提供者装配（Nominatim → Photon 兜底）	登录用户地图页
Nominatim 调用与结果校验	同上
Photon 调用与结果校验	同上

端点#

GET /nominatim/reverse?{qs} 与 /photon/reverse?{qs}（浏览器 → 部署反代 → 外部/自建地理编码服务，中心 Java 服务不参与）— 把经纬度解析为地址文本（Nominatim 优先、Photon 兜底）。

两个前缀均在 allowlist 豁免登记（外部服务），无清单层条目；反代转发规则以部署仓 nginx 配置为样例（Nominatim 为自建 mediagis 容器、Photon 转发 komoot 公共服务）。

动线与完成判据#

response.ok 且校验通过、返回非 undefined 地址即成功；HTTP 失败抛错交由 location-cache 兜底（to + log），不弹全局错误。negative result（无效响应）同样以 undefined 表达并走缓存标记。

错误与边界#

上游不可达/限流表现为非 2xx 或超时；Web 对两个上游各一次尝试，均无效则返回 undefined（不重试逻辑在缓存层）。自建 Nominatim 的数据覆盖与时效由部署数据决定（样例：中国 PBF + Geofabrik 增量，es-server-sz-1/es-nominatim/docker-compose.yml）。与其他第三方资源共同边界见地图底图瓦片源。

调用关系与资源清理#

无长连接资源。结果与 negative result 均进 location-cache（IndexedDB，TTL 由该层管理）；调用方只消费 findReverseAddressAt。

已知缺口#

上游 Nominatim/Photon 响应字段全集与错误形态不在本工作区；nginx 转发配置仅以两个部署仓为样例，目标环境未核验；公共 Photon 服务的配额与政策未评估。