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

# Earth Frontend Context

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

相关规则建议一起参考：

- [rules.md](/home/ray/dev/linkong/planet/rules.md)
- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/frontend-layout-guidelines.md)

## 当前目标

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

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

## 当前入口

React 路由入口：

- [Earth.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Earth/Earth.tsx)

当前做法很简单：

- React 页面只负责提供一个全屏 `iframe`
- 真正的 Earth 应用运行在：
  - [index.html](/home/ray/dev/linkong/planet/frontend/public/earth/index.html)

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

## 当前文件分层

### 1. 页面入口与结构

- [index.html](/home/ray/dev/linkong/planet/frontend/public/earth/index.html)

职责：

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

### 2. 主运行时

- [main.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/main.js)

职责：

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

### 3. 地球控制层

- [controls.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js)

职责：

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

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

### 4. UI 与状态消息

- [ui.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/ui.js)

职责：

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

### 5. 地球与地形

- [earth.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/earth.js)
- [terrain.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/terrain.js)

职责：

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

### 6. 图层模块

- [satellites.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/satellites.js)
- [cables.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/cables.js)
- [bgp.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/bgp.js)
- [news.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/news.js)
- [tv.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/tv.js)

职责：

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

## 当前样式分层

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

- [base.css](/home/ray/dev/linkong/planet/frontend/public/earth/css/base.css)
- [hud.css](/home/ray/dev/linkong/planet/frontend/public/earth/css/hud.css)
- [toolbar.css](/home/ray/dev/linkong/planet/frontend/public/earth/css/toolbar.css)
- [layer-panel.css](/home/ray/dev/linkong/planet/frontend/public/earth/css/layer-panel.css)
- [info-panel.css](/home/ray/dev/linkong/planet/frontend/public/earth/css/info-panel.css)
- [legend.css](/home/ray/dev/linkong/planet/frontend/public/earth/css/legend.css)
- [earth-stats.css](/home/ray/dev/linkong/planet/frontend/public/earth/css/earth-stats.css)
- [coordinates-display.css](/home/ray/dev/linkong/planet/frontend/public/earth/css/coordinates-display.css)
- [tv-panel.css](/home/ray/dev/linkong/planet/frontend/public/earth/css/tv-panel.css)

当前建议：

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

## 当前图层开关状态语义

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

- `inactive`
- `active`
- `loading`

当前入口在：

- [controls.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js)
- [layer-button-state.js](/home/ray/dev/linkong/planet/frontend/public/earth/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](/home/ray/dev/linkong/planet/frontend/public/earth/js/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](/home/ray/dev/linkong/planet/docs/technical/frontend-admin-frontend-context.md)