# Earth Compute Center BGP-Style Plan

## Goal

这份文档定义如何按照 BGP 模块的产品方式，把“算力中心”提升为 Earth 上的一级能力。

这里的“按 BGP 方式”指的是：

- 有独立的数据语义和接口入口
- 有独立的 Earth 图层与图例
- 有独立的 hover / click / 选中态 / 详情卡
- 有独立的统计口径与后续专题页扩展空间

这里的“按 BGP 方式”不指：

- 机械复制 BGP 的 anomaly / incident / collector 三层事件模型
- 为静态算力设施强行引入不必要的复杂告警语义

算力中心本质上更接近“长期基础设施分布层”，不是“高频动态异常层”。
因此应该复用 BGP 的模块化方法，而不是照搬 BGP 的事件结构。

## Why

当前仓库里已经有算力相关基础：

- 后端已有 `top500` 和 `epoch_ai_gpu` 数据采集
- 可视化接口已有 `/api/v1/visualization/geo/supercomputers` 和 `/api/v1/visualization/geo/gpu-clusters`
- Earth 信息卡已对 `supercomputer` 和 `gpu_cluster` 做了基础类型兼容

但当前能力还停留在“数据可取到”的阶段，没有形成像 BGP 那样完整的可视化模块：

- Earth 缺少独立的算力图层加载模块
- 缺少算力 marker 体系和视觉层级
- 缺少算力图例、统计、开关和搜索接入
- 缺少与海缆、BGP、卫星的关系表达
- 缺少算力专题页和后续告警/研判扩展入口

所以当前真正的缺口不是“有没有数据”，而是“有没有产品级模块”。

## Core Principle

算力中心应当采用和 BGP 一致的模块化分层：

1. 数据层：稳定的数据契约和 GeoJSON 输出
2. 渲染层：独立的 Earth 图层、marker 和视觉状态管理
3. 交互层：hover、click、锁定态、详情卡、图例和统计
4. 扩展层：后续专题页、关系分析、告警和 AI 研判

但语义上必须保持算力中心自身的特点：

- `site / center` 是主对象，不是事件
- `capacity / rank / vendor / operator / status` 是主信息，不是异常严重度
- `distribution / concentration / dependency` 是后续分析方向，不是第一阶段必须项

## Recommended Scope

第一版“算力中心”建议统一承载两类对象：

- `supercomputer`
- `gpu_cluster`

并在 Earth 上收口为一个主题层：`compute_centers`

这样做有几个好处：

- 用户看到的是统一的“算力基础设施”语义，而不是零散数据源
- 后端仍可保留 `top500` 和 `epoch_ai_gpu` 的来源差异
- 前端可以在一个图层里再细分两种 marker 语言

## Current Gap

和 BGP 对比，当前差距主要在下面几层。

### 1. Data Contract Gap

现在的算力 GeoJSON 还是通用 `collected_data` 输出思路，字段较轻：

- `gpu_cluster` 只有基础名称和地点
- `supercomputer` 只暴露一部分性能字段
- 缺少统一的 `site_type / operator / capacity_band / source / updated_at / confidence`
- 缺少统一的算力层聚合出口

### 2. Earth Rendering Gap

当前 Earth 里没有类似 `bgp.js` 的算力模块：

- `constants.js` 没有算力 API 路径和视觉配置
- `main.js` 没有算力加载、拾取、状态同步和 HUD 更新
- `controls.js` 没有算力图层开关和启动加载优先级
- `layer-startup-tasks.js` 没有算力启动任务
- `legend.js` / `ui.js` 没有算力统计与图例模式

### 3. Interaction Gap

虽然 `info-card.js` 支持基础字段，但还没有形成 BGP 那种完整交互链路：

- 没有 hover / selected / dimmed 的视觉状态
- 没有算力对象专属 tooltip 与摘要文案
- 没有锁定后与其他基础设施的联动高亮
- 没有搜索、统计卡和详情组织方式

### 4. Product Expansion Gap

当前还没有“算力中心”专题页与分析语义：

- 没有全球分布/国家聚合/厂商聚合视图
- 没有算力与海缆/BGP/区域的关系表达
- 没有 AI brief / assessment 的后续落点

## Architecture Direction

推荐把算力中心做成“BGP 同级能力”，但采用更适合静态基础设施的结构。

### Backend

建议新增统一聚合接口，例如：

- `/api/v1/visualization/geo/compute-centers`

它的职责是把：

- `top500`
- `epoch_ai_gpu`

统一转换成一个主题层输出，同时保留对象细分类型：

- `site_type: supercomputer | gpu_cluster`

建议统一字段至少包括：

- `id`
- `name`
- `site_type`
- `country`
- `city`
- `latitude`
- `longitude`
- `operator`
- `vendor`
- `capacity_value`
- `capacity_unit`
- `capacity_band`
- `rank`
- `source`
- `updated_at`
- `location_precision`
- `geography_mode`
- `is_estimated`
- `estimated_reason`
- `metadata`

这里建议优先做“统一聚合出口”，而不是一开始就新增独立数据库表。

原因：

- 当前源数据更新频率低，先复用 `collected_data` 成本更低
- 可以先把 Earth 产品体验做完整
- 如果后续要做历史趋势、关系推断、告警，再评估是否拆成独立模型

### Frontend Earth

建议新增独立模块，例如：

- `frontend/public/earth/js/compute-centers.js`

职责参照 `bgp.js`：

- 拉取算力中心 GeoJSON
- 创建 marker
- 管理 hover / selected / dimmed 状态
- 输出图例项
- 输出统计摘要
- 提供 overlay 和详情格式化辅助函数

推荐视觉分层：

1. `supercomputer` 用更稳定、更规整的设施型符号
2. `gpu_cluster` 用更活跃、更现代的密度型符号
3. 选中态通过 halo / ring / related infrastructure highlight 表达

视觉上应避免把算力中心做成“BGP 事件点”那种高频脉冲风格。
它应该更像长期存在的高价值设施。

## Phases

## Phase 1: Unified Earth Layer

目标：

- 先把算力中心做成 Earth 上可用、可点、可解释的一级图层

工作项：

- 新增统一算力 GeoJSON 接口
- 新增 `compute-centers.js`
- 在 `constants.js` 增加 API 路径和视觉配置
- 在 `controls.js` 增加算力图层开关与启动元数据
- 在 `layer-startup-tasks.js` 增加算力启动加载任务
- 在 `main.js` 接入算力拾取、hover、click、锁定态和 HUD 统计
- 在 `ui.js` / `legend.js` / `index.html` 增加算力统计与图例入口
- 在 `info-card.js` 提升算力详情字段组织
- 对无法精确定位、但可按国家或弱线索推测的大概位置，仍然生成地图点位
- 这类对象必须带显式“估算位置”状态，例如图标问号角标与详情说明

完成标准：

- Earth 上能独立显示/隐藏算力中心
- 两类对象有可区分的视觉表达
- hover / click / 详情卡 / 图例 / 统计全部打通
- 精确位置与估算位置在图标或文案上可区分，不会误导为同一精度
- 不干扰现有海缆、卫星、BGP 的交互链路

## Phase 2: Relationship Layer

目标：

- 让算力中心不只是“点”，而是和其他基础设施产生上下文关系

工作项：

- 建立算力中心与国家/区域聚合摘要
- 增加与附近海缆登陆点的关系提示
- 增加与 BGP 事件/观测范围的空间邻近提示
- 增加与卫星覆盖或区域连通性的实验性提示

完成标准：

- 点击算力中心时，用户能看到“它和哪些基础设施相关”
- 信息表达以辅助判断为主，不做夸张推断

## Phase 3: Compute Center Observatory

目标：

- 把算力中心从 Earth 图层扩展成独立专题观测能力

工作项：

- 新增算力中心专题页
- 提供国家/厂商/类型/容量分布统计
- 支持列表、筛选、详情和历史快照
- 预留 AI brief / assessment 入口

完成标准：

- 算力中心不再只是 Earth 上的视觉点位
- 能作为独立业务上下文进入日常观察与研判

## Phase 4: Alerts And Assessment

目标：

- 在不滥造“假动态告警”的前提下，引入真正有价值的变化感知

候选方向：

- 新增大规模算力中心
- 既有中心容量显著变化
- 国家/区域集中度显著变化
- 高价值中心与关键网络基础设施关系变化

完成标准：

- 告警来自可解释的结构变化
- 不把静态数据硬做成噪声式实时事件流

## Implementation Notes

建议按下面顺序推进：

1. 先统一 GeoJSON 契约
2. 再做 Earth 独立模块和图层开关
3. 再补详情卡、图例和统计
4. 最后才做关系层和专题页

这样可以避免一开始把范围摊得过大。

## Unknown Location Strategy

由于部分算力数据源不会直接提供经纬度，未知位置补全不能只依赖“继续找 API 字段”。
更稳妥的方式是做成一条分层富化链路，而不是单一猜测规则。

推荐按下面优先级推进：

1. 直接源信息

- 源记录显式给出 `latitude / longitude`
- 源记录给出 `city / region / facility / campus / operator`
- 源页面详情、内嵌 JSON、结构化元数据、新闻稿链接里能抽出地点线索

2. 名称与机构归一化

- 建立 `canonical_name / aliases / operator / facility` 归一化表
- 把 `cluster name`、`operator`、`campus name` 归一到同一个实体
- 优先解决同一对象多写法导致的命中失败，而不是先扩大猜测范围

3. 本地位置注册表

- 用仓库内可维护的 registry 保存高价值对象的位置知识
- 每条记录至少包含：`canonical_name`、`aliases`、`operator`、`country`、`region`、`city`、`lat`、`lon`、`confidence`、`source_note`
- 转换层优先读取 registry，避免地点知识长期散落在转换代码里

4. 分层回退定位

- `precise`
- `estimated_site`
- `estimated_city`
- `estimated_region`
- `estimated_national_hub`
- `estimated_country`

这里建议把“国家内主要算力城市”作为国家质心之前的一层。
例如没有美国精确位置时，优先考虑已知的主要算力/数据中心城市候选，而不是直接落在几何质心。

5. 候选证据富化

- 如果源 API 无地点信息，可以允许采集链路读取公开辅助证据
- 例如机构官网、数据中心介绍页、新闻稿、百科型页面、公开 PDF
- 但只提取“地点线索”，不把外部页面上的经纬度当真值直接写回

6. 人工校验闭环

- 对高价值且仍然未知的对象输出待核验清单
- 把人工确认结果回写到位置注册表
- 后续采集继续优先复用这层人工确认结果

### Additional Solution Paths

除了静态映射表，还可以考虑下面这些办法：

- 基于国家和运营方建立“主要园区候选集”，用稳定散列把同国未知节点分散到若干可信城市，而不是全部压到一个点
- 基于数据中心/云厂商公开 region 列表建立 `operator -> city set` 候选映射，用于云 GPU 集群类对象
- 把“估算依据”结构化，例如 `matched_alias`、`matched_operator`、`matched_city_text`、`fallback_country_hub`
- 给位置补全增加 `last_verified_at`，便于后续按时间重新校验老旧映射
- 单独维护“不可可靠定位”状态；这类对象仍可在国家级聚合统计中出现，但可以允许用户在地图上过滤掉
- 后续如果你们愿意投入更多，可把这条链路做成小型 enrichment pipeline，而不是仅在 API 转换时临时判断

## Non-Goals

第一阶段不建议做这些内容：

- 不复制 BGP 巡航模式到算力中心
- 不先做复杂实时 websocket 推送
- 不先引入独立 `compute_center_incident` 一类模型
- 不先做全量 AI 分析面板

原因是算力中心的第一需求是“被看清楚”，不是“被实时播报”。
但“被看清楚”不等于“只显示精确坐标对象”。
对于没有精确经纬度、但能推测到国家或区域级位置的算力中心，应优先以上图并标注估算状态的方式处理，而不是直接在地图上消失。

## Acceptance Checklist

- 后端存在统一的算力中心 GeoJSON 出口
- Earth 有独立算力图层模块，而不是散落在 `main.js`
- 页面上有清晰的算力开关、图例和统计
- `supercomputer` 和 `gpu_cluster` 在视觉和详情上都可区分
- 估算位置对象在地图和详情中都有明确状态提示
- 现有 BGP / 海缆 / 卫星功能无回归
- 代码结构上为后续专题页和关系分析留出了明确扩展点

## Summary

这项工作的本质不是“再多画几个点”。

它应该把算力中心从已有数据源，升级成与 BGP 同级的 Earth 观测主题：

- 有独立语义
- 有独立图层
- 有独立交互
- 有后续分析扩展能力

推荐先完成 Phase 1，把算力中心做成真正可用的 Earth 一级模块，再继续推进关系层和专题页。