# Earth 位置候选采集使用手册

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

## 适用对象

当前支持：

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

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

## 用户能看到什么

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

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

这里的 Nominatim 指 OpenStreetMap 生态中的在线地理编码服务。它会把地点名称、城市、国家、机构或园区查询文本转换为可能的经纬度候选，但结果可能命中同名地点或过宽泛的行政区，因此界面会把这类结果标为待确认。

算力中心 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 伪造位置。该记录会留在列表中，并显示后端返回的失败原因和已尝试查询，等待人工补充更可靠的地址或坐标证据。

## 后端接口

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

```http
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` 接口返回相同结构：

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

常规候选为空时，接口会通过当前默认 AI Provider 做一次 LLM factcheck 兜底。LLM 候选始终需要人工确认，不会自动保存；只有达到城市级或更高精度、非零坐标且置信度足够的 JSON 结果才会出现在候选列表中。当仍没有候选达到城市级精度时，`success` 为 `false`，响应会包含 `failure_reason`、`llm_failure_reason` 和已尝试的查询文本，便于判断是源数据字段不足、开放来源缺项、在线地理编码没有命中，还是 LLM 返回不可用。

## 数据维护建议

算力中心和 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 结果来自在线地理编码，可能匹配到同名城市、机构或园区。它可以用于快速定位和预览，但在写入已验证位置前应人工确认。

### LLM 兜底会不会直接改地图？

不会。LLM 只在用户点击采集候选且常规来源没有候选时运行，并只返回待确认候选。Earth 首屏 GeoJSON、定时采集和批量渲染不会自动调用 LLM；只有用户保存候选后，位置才会进入维表并参与后续渲染。

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

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