Stabilize Earth module and fix satellite TLE handling
This commit is contained in:
linkong
210
docs/earth-module-plan.md
Normal file
210
docs/earth-module-plan.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# Earth 模块整治计划
|
||||
|
||||
## 背景
|
||||
|
||||
`planet` 前端中的 Earth 模块是当前最重要的大屏 3D 星球展示能力，但它仍以 legacy iframe 页面形式存在：
|
||||
|
||||
- React 页面入口仅为 [Earth.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Earth/Earth.tsx)
|
||||
- 实际 3D 实现位于 [frontend/public/earth](/home/ray/dev/linkong/planet/frontend/public/earth)
|
||||
|
||||
当前模块已经具备基础展示能力，但在生命周期、性能、可恢复性、可维护性方面存在明显隐患，不适合长期无人值守的大屏场景直接扩展。
|
||||
|
||||
## 目标
|
||||
|
||||
本计划的目标不是立刻重写 Earth，而是分阶段把它从“能跑的 legacy 展示页”提升到“可稳定运行、可持续演进的大屏核心模块”。
|
||||
|
||||
核心目标：
|
||||
|
||||
1. 先止血，解决资源泄漏、重载污染、假性卡顿等稳定性问题
|
||||
2. 再梳理数据加载、交互和渲染循环，降低性能风险
|
||||
3. 最后逐步从 iframe legacy 向可控模块化架构迁移
|
||||
|
||||
## 现阶段主要问题
|
||||
|
||||
### 1. 生命周期缺失
|
||||
|
||||
- 没有统一 `destroy()` / 卸载清理逻辑
|
||||
- `requestAnimationFrame`
|
||||
- `window/document/dom listeners`
|
||||
- `THREE` geometry / material / texture
|
||||
- 运行时全局状态
|
||||
都没有系统回收
|
||||
|
||||
### 2. 数据重载不完整
|
||||
|
||||
- `reloadData()` 没有彻底清理旧场景对象
|
||||
- cable、landing point、satellite 相关缓存与对象存在累积风险
|
||||
|
||||
### 3. 渲染与命中检测成本高
|
||||
|
||||
- 鼠标移动时频繁创建 `Raycaster` / `Vector2`
|
||||
- cable 命中前会重复做 bounding box 计算
|
||||
- 卫星每帧计算量偏高
|
||||
|
||||
### 4. 状态管理分裂
|
||||
|
||||
- 大量依赖 `window.*` 全局桥接
|
||||
- 模块之间靠隐式共享状态通信
|
||||
- React 外层无法有效感知 Earth 内部状态
|
||||
|
||||
### 5. 错误恢复弱
|
||||
|
||||
- 数据加载失败主要依赖 `console` 和轻提示
|
||||
- 缺少统一重试、降级、局部失败隔离机制
|
||||
|
||||
## 分阶段计划
|
||||
|
||||
## Phase 1：稳定性止血
|
||||
|
||||
目标：
|
||||
|
||||
- 不改视觉主形态
|
||||
- 优先解决泄漏、卡死、重载污染
|
||||
|
||||
### 任务
|
||||
|
||||
1. 补 Earth 生命周期管理
|
||||
|
||||
- 为 [main.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/main.js) 增加：
|
||||
- `init()`
|
||||
- `destroy()`
|
||||
- `reloadData()`
|
||||
三类明确入口
|
||||
- 统一记录并释放：
|
||||
- animation frame id
|
||||
- interval / timeout
|
||||
- DOM 事件监听
|
||||
- `window` 暴露对象
|
||||
|
||||
2. 增加场景对象清理层
|
||||
|
||||
- 为 cable / landing point / satellite sprite / orbit line 提供统一清理函数
|
||||
- reload 前先 dispose 旧对象，再重新加载
|
||||
|
||||
3. 增加 stale 状态恢复
|
||||
|
||||
- 页面重新进入时，先清理上一次遗留选择态、hover 态、锁定态
|
||||
- 避免 iframe reload 后出现旧状态残留
|
||||
|
||||
4. 加强失败提示
|
||||
|
||||
- 电缆、登陆点、卫星加载拆分为独立状态
|
||||
- 某一类数据失败时，其它类型仍可继续显示
|
||||
- 提供明确的页面内提示而不是只打 console
|
||||
|
||||
### 验收标准
|
||||
|
||||
- 页面重复进入 / 离开后内存不持续上涨
|
||||
- 连续多次点“重新加载数据”后对象数量不异常增加
|
||||
- 单一数据源加载失败时页面不整体失效
|
||||
|
||||
## Phase 2：性能优化
|
||||
|
||||
目标：
|
||||
|
||||
- 控制鼠标交互和动画循环成本
|
||||
- 提升大屏长时间运行的稳定帧率
|
||||
|
||||
### 任务
|
||||
|
||||
1. 复用交互对象
|
||||
|
||||
- 复用 `Raycaster`、`Vector2`、中间 `Vector3`
|
||||
- 避免 `mousemove` 热路径中频繁 new 对象
|
||||
|
||||
2. 优化 cable 命中逻辑
|
||||
|
||||
- 提前缓存 cable 中心点 / bounding 数据
|
||||
- 移除 `mousemove` 内重复 `computeBoundingBox()`
|
||||
- 必要时增加分层命中：
|
||||
- 先粗筛
|
||||
- 再精确相交
|
||||
|
||||
3. 改造动画循环
|
||||
|
||||
- 使用真实 `deltaTime`
|
||||
- 把卫星位置更新、呼吸动画、视觉状态更新拆成独立阶段
|
||||
- 为不可见对象减少无意义更新
|
||||
|
||||
4. 卫星轨迹与预测轨道优化
|
||||
|
||||
- 评估轨迹更新频率
|
||||
- 对高开销几何计算增加缓存
|
||||
- 限制预测轨道生成频次
|
||||
|
||||
### 验收标准
|
||||
|
||||
- 鼠标移动时不明显掉帧
|
||||
- 中高数据量下动画速度不受帧率明显影响
|
||||
- 长时间运行 CPU/GPU 占用更平稳
|
||||
|
||||
## Phase 3：架构收编
|
||||
|
||||
目标：
|
||||
|
||||
- 降低 legacy iframe 架构带来的维护成本
|
||||
- 让 React 主应用重新获得对 Earth 模块的控制力
|
||||
|
||||
### 任务
|
||||
|
||||
1. 抽离 Earth App Shell
|
||||
|
||||
- 将数据加载、错误状态、控制面板状态抽到更明确的模块边界
|
||||
- 减少 `window.*` 全局依赖
|
||||
|
||||
2. 规范模块通信
|
||||
|
||||
- 统一 `main / controls / cables / satellites / ui` 的状态流
|
||||
- 明确只读配置、运行时状态、渲染对象的职责分层
|
||||
|
||||
3. 评估去 iframe 迁移
|
||||
|
||||
- 中期可以保留 public/legacy 资源目录
|
||||
- 但逐步把 Earth 作为前端内嵌模块而不是完全孤立页面
|
||||
|
||||
### 验收标准
|
||||
|
||||
- Earth 内部状态不再大量依赖全局变量
|
||||
- React 外层可以感知 Earth 加载状态和错误状态
|
||||
- 后续功能开发不再必须修改多个 legacy 文件才能完成
|
||||
|
||||
## 优先级建议
|
||||
|
||||
### P0
|
||||
|
||||
- 生命周期清理
|
||||
- reload 清理
|
||||
- stale 状态恢复
|
||||
|
||||
### P1
|
||||
|
||||
- 命中检测优化
|
||||
- 动画 `deltaTime`
|
||||
- 数据加载失败隔离
|
||||
|
||||
### P2
|
||||
|
||||
- 全局状态收编
|
||||
- iframe 架构迁移
|
||||
|
||||
## 推荐实施顺序
|
||||
|
||||
1. 先做 Phase 1
|
||||
2. 再做交互热路径与动画循环优化
|
||||
3. 最后再考虑架构迁移
|
||||
|
||||
## 风险提示
|
||||
|
||||
1. Earth 是 legacy 模块，修复时容易牵一发而动全身
|
||||
2. 如果不先补清理逻辑，后续所有性能优化收益都会被泄漏问题吃掉
|
||||
3. 如果过早重写而不先止血，短期会影响现有演示稳定性
|
||||
|
||||
## 当前建议
|
||||
|
||||
最值得马上启动的是一个小范围稳定性 sprint：
|
||||
|
||||
- 生命周期清理
|
||||
- reload 全量清理
|
||||
- 错误状态隔离
|
||||
|
||||
这个阶段不追求“更炫”，先追求“更稳”。稳定下来之后，再进入性能和架构层的优化。
|
||||
Reference in New Issue
Block a user