release: bump version to 0.49.0

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

@@ -0,0 +1,127 @@
+# 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 伪造位置。该记录会留在列表中，并显示后端返回的失败原因和已尝试查询，等待人工补充更可靠的地址或坐标证据。
+
+## 后端接口
+
+前端按钮调用的接口如下：
+
+```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": {}
+}
+```
+
+当没有候选达到城市级精度时，`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 模糊匹配。