planet/docs/plans/earth-compute-center-bgp-style-plan.md

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 一级模块，再继续推进关系层和专题页。