# 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 全量清理
- 错误状态隔离

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