planet/docs/technical/zh/location-pipeline-user.md

Earth 位置候选采集使用手册

位置候选采集用于给 Earth 上的算力中心和 BGP 观测站补齐或核验经纬度。它不会要求用户手工输入坐标，而是把源数据、开放组织注册 API 和在线地理编码结果整理成候选列表，供用户预览和后续认领。

适用对象

当前支持：

• 算力中心：TOP500 超算、Epoch AI GPU 集群。
• BGP 观测站：RIPE RIS rrcXX collector。

BGP 事件的位置默认继承所属 collector。事件本身暂不提供单独按钮；后续 ASN 设施、Prefix 地理位置或 PeeringDB 算法接入后会继续走同一条管线。

用户能看到什么

在 Earth 上点击算力中心或 BGP 观测站后，详情卡会展示位置相关字段：

字段	含义
位置精度	精确坐标、站点级位置、城市级位置 或 位置未确认
位置来源	源数据坐标、ROR 组织注册 API、Nominatim 在线搜索，或已存储的 BGP collector 维表位置
位置置信度	后端 resolver 给出的相对置信度百分比
核验状态	已确认、估算位置或在线检索结果待确认
解析依据	为什么选择这个位置，例如匹配了哪个站点或城市
匹配的位置名称	开放来源、在线结果或已存储 collector 位置中的规范名称
位置核验时间	已确认位置的核验日期，在线候选通常为空

算力中心 GeoJSON 不再渲染国家质心、未知位置或 [0, 0] 占位点。无法达到城市级精度的数据会进入接口的 unresolved 列表，并在图层开关左上角显示待定位数量。点击这个通知气泡会打开待定位列表。

地图上带 ? 的算力中心不是 unresolved。它们已经有坐标，只是 needs_confirmation=true 或来自在线地理编码，仍需人工核验。真正 unresolved 的记录没有可信经纬度，因此不会出现在地球上。

自动采集候选

1. 打开 http://localhost:3000/earth。
2. 打开 算力中心 或 BGP 观测 图层。
3. 点击目标对象打开详情卡。
4. 点击 自动采集坐标候选 或 重新自动采集坐标。
5. 等待详情卡列出最多 5 个候选位置。
6. 点击候选行里的 预览，Earth 会飞到该候选经纬度附近。

候选列表会显示：

• 候选名称。
• 精度：精确、站点或城市。
• 来源 resolver。
• 置信度。
• 经纬度。

点击候选行里的 保存 会把所选候选写入算力中心位置维表。保存成功后，算力中心图层会刷新；如果该记录原本在待定位列表中，待定位数量也会减少。

待定位列表和一键采用

算力中心图层按钮左上角的通知气泡显示当前 unresolved 数量。点击后会在图层面板右侧打开固定列表：

1. 列表只包含没有可信经纬度的算力中心。
2. 单条 采集 会调用候选接口，并展示最多 5 个候选供预览和保存。
3. 顶部 一键采用 会从上到下逐条采集候选，选择置信度最高且有有效经纬度的候选保存。
4. 成功保存一条后，该行会立即从列表中移除，下面的序号自动上移，通知气泡数量同步减少。
5. 批量结束后，前端会刷新算力中心图层，确保 UI 和后端真实状态一致。

如果某条记录没有任何可保存候选，系统不会用国家中心点、厂商总部或硬编码 hint 伪造位置。该记录会留在列表中，并显示后端返回的失败原因和已尝试查询，等待人工补充更可靠的地址或坐标证据。

后端接口

前端按钮调用的接口如下：

POST /api/v1/visualization/compute-centers/{source_id}/collect-location
POST /api/v1/visualization/compute-centers/{source_id}/location
POST /api/v1/bgp/collectors/{collector_id}/collect-location

两个 collect-location 接口返回相同结构：

{
  "success": true,
  "candidates": [],
  "best_candidate": {},
  "attempted_queries": [],
  "context": {}
}

当没有候选达到城市级精度时，success 为 false，响应会包含 failure_reason 和已尝试的查询文本，便于判断是源数据字段不足、开放来源缺项，还是在线地理编码没有命中。

数据维护建议

算力中心和 BGP 观测站都不再维护本地候选注册表。算力中心的人工确认位置保存在 compute_center_locations 数据库维表中，唯一键是 (source, source_id)；BGP 观测站的当前位置保存在 bgp_collector_locations 数据库维表中，旧 RIPE RIS 城市级坐标只作为初始化 seed 写入，默认仍需人工核验。

维护算力中心时优先补齐：

• source / source_id：例如 top500 + top500_50。
• name / operator / site。
• city / country。
• latitude / longitude。
• precision：precise、site 或 city。
• confidence：0 到 1 的置信度。
• location_source / source_url / source_note / raw_payload：证据来源。
• needs_confirmation / verification_status / verified_at：人工核验状态和日期。

维护 BGP 观测站时优先补齐：

• collector_id：例如 rrc12。
• site / operator：站点和运营方。
• city / country / region。
• latitude / longitude。
• precision：precise、site 或 city。
• confidence：0 到 1 的置信度。
• source / source_url / raw_payload：证据来源。
• verification_status / verified_at：人工核验状态和日期。

如果只是知道城市，不知道设施坐标，应使用城市级精度，不要填一个看似精确但无法核验的点位。

常见问题

为什么有些算力中心不显示在 Earth 上

Earth 只渲染达到城市级或更高精度的坐标。源数据没有坐标、已验证位置没有命中、在线搜索也没有城市级结果时，记录会进入 unresolved，避免在地图上出现误导性的国家中心点或 [0, 0]。

为什么在线搜索结果显示“待确认”

Nominatim/OpenStreetMap 结果来自在线地理编码，可能匹配到同名城市、机构或园区。它可以用于快速定位和预览，但在写入已验证位置前应人工确认。

为什么 BGP 事件没有全部落到 Amsterdam

旧逻辑中，事件可能因为 operator="RIPE NCC" 这种通用字段误匹配到 rrc00。当前 BGP 事件继承只按所属 collector 在 DB-backed cache 中严格查找，不再用 registry 模糊匹配。