planet/docs/plans/earth-renderer-architecture-separation-plan.md

Earth Renderer / Logic Separation Plan

Source note: this plan absorbs useful ideas from a sisyphus-created draft formerly stored at .sisyphus/plans/earth-architecture-refactor.md.

Goal

将 Earth 前端继续往“逻辑层 / 状态层 / 渲染层”分离推进，降低后续这几类工作的耦合成本：

• Three.js 渲染重构
• 部分图层替换实现
• 未来 UE / Cesium 客户端迁移
• Earth 行为逻辑复用

Why This Matters

当前 Earth 已经有一些良好分层，例如：

• 图层显隐入口
• Cable state 枚举与状态 map
• 交互逻辑与实际视觉效果的部分分离

但还没有形成一套更明确的统一规则。现在的风险是：

• 同一类对象的 hover / locked / hidden / loading 语义不一致
• 状态和渲染更新散落在多个模块
• 后续再加新图层时容易复制旧逻辑

Target Architecture

Earth 对每类对象都尽量拆成三层：

1. state layer

   • 保存对象状态
   • 例如：normal / hovered / locked / hidden / loading

2. logic layer

   • 处理点击、悬停、锁定、过滤、显隐切换
   • 不直接关心 Three.js 具体材质怎么改

3. renderer layer

   • 根据状态更新 Three.js / HUD 外观
   • 是最容易针对不同渲染引擎替换的一层

Current Good Signals

当前已经接近这条方向的地方：

• cable 状态管理
• 部分 landing point 状态同步
• layer button 的统一状态入口
• tooltip / legend / info-card 开始朝状态驱动靠拢

Next Steps

1. Standardize object state enums

优先为这些对象建立更稳定的状态语义：

• cables
• satellites
• landing points
• BGP markers
• media / news 面板入口按钮

2. Unify state-to-visual adapters

为各模块建立更清晰的渲染适配函数，例如：

• applyCableVisualState()
• applySatelliteVisualState()
• applyBGPVisualState()

要求：

• 逻辑层只改状态
• 视觉层负责把状态映射到材质、透明度、发光、尺寸、文字

3. Separate Earth UI state from render state

HUD / 面板 / 图层按钮状态也需要和渲染状态分离：

• loading
• active
• locked
• hidden
• error

不要再让 UI 通过“猜渲染结果”推导业务状态。

4. Prepare migration-safe boundaries

后续如果做 UE / Cesium 客户端，尽量保留：

• 状态枚举
• 交互规则
• 数据层接口

只替换：

• Three.js 具体渲染实现
• HUD 展示实现

Practical Rule

后续 Earth 新功能开发时，优先问三个问题：

1. 这个状态由谁持有？
2. 这个交互逻辑在哪一层处理？
3. 这个视觉变化是否能在不改逻辑的情况下单独替换？

如果答不上来，就说明还在把状态、逻辑、渲染揉在一起。