planet/docs/earth-module-plan.md

Earth 模块整治计划

背景

planet 前端中的 Earth 模块是当前最重要的大屏 3D 星球展示能力，但它仍以 legacy iframe 页面形式存在：

• React 页面入口仅为 Earth.tsx
• 实际 3D 实现位于 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 增加：
  • 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 全量清理
• 错误状态隔离

这个阶段不追求“更炫”，先追求“更稳”。稳定下来之后，再进入性能和架构层的优化。