# 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) - [bgp-cruise-adapter.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/bgp-cruise-adapter.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) - [cruise-sequencer.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/cruise-sequencer.js) - [callout-connector.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/callout-connector.js) 职责： - 各自的数据层 - 开关行为 - 面板内容 - hover/lock/selection 语义 其中巡航模式现在已经拆成两层： - `cruise-sequencer.js` - 负责目标队列顺序、停留时长、切换节奏、打断与恢复 - `callout-connector.js` - 负责卡片连线 SVG、路径计算与绘制动画 - `bgp-cruise-adapter.js` - 负责 BGP 巡航展示适配：目标排序、卡片落点、连线路径、focus/overlay/info-card 时序 当前 BGP 巡航只是这套能力的一个调用方，不应再把“按队列巡航”和“BGP 事件展示”混写在同一个状态机里。 ## 当前样式分层 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。 ### 4. 巡航与业务事件不要再深度耦合 当前正确边界应该是： - 通用巡航层只知道： - 当前目标 - 队列顺序 - 相机 focus - 停留 / 隐藏 / 切换 - 业务模块只负责： - 提供目标队列 - 提供 focus 坐标 - 提供卡片内容 - 提供高亮/图层副作用 如果以后再给海缆、卫星或新闻做巡航，不应复制一套新的 `main.js` 状态变量，而应复用： - [cruise-sequencer.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/cruise-sequencer.js) - [callout-connector.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/callout-connector.js) - [bgp-cruise-adapter.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/bgp-cruise-adapter.js) 这种业务适配层模式 ## 当前推荐改动方式 如果后续继续改 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)