IP 定位#

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

用途与场景#

以客户端出口 IP 粗定位（城市级）作为「我的位置」兜底。浏览器直连环境变量配置的 IP 查询服务，中心服务不参与。结果进 localStorage 缓存（TTL 由 location-cache 管理）。

使用位置#

页面/功能	角色或空间分支
IP 定位 loader	登录用户（无需中心权限）
HTTP 客户端	同上

端点#

GET {VITE_IP_QUERY_SERVICE_URL}/json（浏览器 → 第三方 IP 查询服务直连，中心不参与；仓库 env 样例为 ipinfo.io）— 以客户端出口 IP 粗定位（城市级）。

该地址属外部地图服务（非本站端点，allowlist 豁免登记），无清单层条目。 Web 只消费响应 loc（"lat,lon" 形态）并做范围校验；更换部署可经环境变量指向兼容形态的自建服务。

动线与完成判据#

response.ok 且 loc 校验通过返回 {longitude, latitude} 即成功；HTTP 失败抛错、非法 loc 返回 undefined，均由 location-cache 兜底（to + log），不弹全局错误。

错误与边界#

第三方服务限流/不可达时 HTTP 非 200 或响应缺 loc，Web 记为 negative result 并走缓存；无重试装配。与其他第三方资源共同边界见地图底图瓦片源。

调用关系与资源清理#

无长连接资源。结果与 negative result 进 localStorage（MY_POSITIONING_STORAGE_KEY）；调用方只消费 locateByIp/readMyPositioning。

已知缺口#

上游 ipinfo.io 响应字段全集、限流阈值与政策不在本工作区；VITE_IP_QUERY_SERVICE_URL 在不同部署的实际取值未核验（仅仓库内两份 env 样例）。