planet/docs/technical/earth-frontend-context.md

Earth Frontend Context

本文件描述当前 Earth 大屏前端的真实结构，重点是帮助后续继续改 HUD、图层、媒体面板、真实地形、BGP 可视化时，不再重复踩结构和状态同步上的坑。

相关规则建议一起参考：

• rules.md
• frontend-layout-guidelines.md

当前目标

Earth 前端不是普通管理页，它是独立的大屏展示前端。当前产品目标是：

• 维持地球视图的空间感和可读性
• 让 HUD、图层、媒体面板、BGP、卫星、海缆等保持统一交互
• 把加载中、已启用、已隐藏、锁定中这类状态做清楚

当前入口

React 路由入口：

• Earth.tsx

当前做法很简单：

• React 页面只负责提供一个全屏 iframe
• 真正的 Earth 应用运行在：
  • index.html

所以 Earth 前端本质上是 public/earth 下的一套独立静态应用。

当前文件分层

1. 页面入口与结构

• index.html

职责：

• HUD 基础 DOM
• 图层面板
• 媒体面板
• 工具栏
• 设置弹窗
• 兼容旧元素 id

2. 主运行时

• main.js

职责：

• 地球初始化
• Three.js 场景组装
• 数据加载与刷新
• 各图层集成
• Earth 级别状态同步

3. 地球控制层

• controls.js

职责：

• 工具栏交互
• 图层面板交互
• 旋转/缩放/布局
• HUD 面板拖拽
• 图层开关状态机

这份文件是 Earth 前端当前最核心的 UI 控制入口。

4. UI 与状态消息

• ui.js

职责：

• loading 面板
• status message
• tooltip / error / 清理逻辑

5. 地球与地形

• earth.js
• terrain.js

职责：

• 地球球体、云层、大气
• 真实地形 mesh
• terrain tile 拉取、解码、位移、着色

6. 图层模块

• satellites.js
• cables.js
• bgp.js
• news.js
• tv.js

职责：

• 各自的数据层
• 开关行为
• 面板内容
• hover/lock/selection 语义

当前样式分层

Earth 的 CSS 不是一份大样式表，而是分层管理：

• base.css
• hud.css
• toolbar.css
• layer-panel.css
• info-panel.css
• legend.css
• earth-stats.css
• coordinates-display.css
• tv-panel.css

当前建议：

• 通用 HUD 壳层写进 hud.css
• 单一面板特性写进各自子文件
• 不要把业务状态样式再散回 index.html

当前图层开关状态语义

Earth 图层按钮现在不应再只有“开/关”两态，而应支持：

• inactive
• active
• loading

当前入口在：

• controls.js
• layer-button-state.js

关键函数：

• updateLayerButtonState(button, isActive)
• setLayerButtonState(button, options)

setLayerButtonState 负责：

• loading 样式
• aria-busy
• 按钮禁用
• tooltip 更新
• 绑定状态文本更新
• 可选同步 active

因此后续如果别的图层也需要异步启用，应该直接走这套状态机，而不是再手写一套临时 loading class。

data-status-target

图层按钮可以通过：

• data-status-target

指向一个状态文本节点。当前 terrain 已接入：

• 按钮：#toggle-terrain
• 状态节点：#terrain-status

以后别的异步图层也可以沿用这套约定。

当前地形链路

真实地形首次启用会慢，原因不只是一个：

1. 需要拉取 Terrarium 瓦片
2. 需要解码图片
3. 需要按顶点采样高程
4. 需要重新写入 geometry 和 color
5. 需要重新计算法线与包围体

当前入口在：

• terrain.js

当前已经做了两层体验优化：

1. 图层开关 loading 状态持续可见
2. 页面空闲时会预热 ensureTerrainReady()

也就是说，后续再继续优化 terrain 时，优先顺序应该是：

1. 先保证用户感知正确
2. 再压缩首次等待
3. 最后才做更激进的几何/瓦片优化

当前高频风险点

1. 视觉状态和业务状态不同步

Earth 里最常见的 bug 不是“没渲染”，而是：

• 图层关了，tooltip 还在
• 锁定对象隐藏了，info card 还在
• legend 没跟图层切换
• loading 已结束，但按钮还像没开

后续改动必须优先检查状态同步。

2. HUD 布局问题先查结构，不要先打 CSS 补丁

Earth HUD 历史上反复出现：

• 面板只剩一条缝
• markdown 被裁掉
• tabs/iframe 被 overflow: hidden 吃掉

优先检查：

1. 谁负责高度
2. 谁负责滚动
3. 哪一层在裁剪

不要上来先加 overflow: hidden 或额外包装层。

3. Transitional path 必须收口

Earth 已经经历过多轮 HUD、toolbar、media panel 重构，所以最容易积累：

• 旧 helper
• 旧 class
• 旧 fallback 逻辑
• 已废弃变体

每次大功能完成后，都要做一次 cleanup pass。

当前推荐改动方式

如果后续继续改 Earth，建议按这个顺序：

1. 先确认改的是：
   • Three.js 渲染层
   • HUD 结构层
   • 图层状态层
   • 面板内容层
2. 如果涉及图层按钮，优先接入统一状态机
3. 如果涉及可见性切换，检查 tooltip / legend / info-card / lock 是否一起收口
4. 如果涉及面板布局，先查结构再动 CSS

当前与控制台前端的边界

Earth 前端和控制台前端不是同一套 UI 系统：

• 控制台前端：React + Ant Design 工作台
• Earth 前端：public/earth 原生 HUD + Three.js 展示面

因此：

• Earth 不应该直接复用 Ant Table / AppLayout 语义
• 控制台也不应该照搬 Earth HUD 动画和玻璃层语言

控制台相关结构见：

• admin-frontend-context.md