155 lines
4.0 KiB
Markdown
155 lines
4.0 KiB
Markdown
# 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 语义不一致
|
||
- 状态和渲染更新散落在多个模块
|
||
- 后续再加新图层时容易复制旧逻辑
|
||
|
||
## Current High-Frequency Risks
|
||
|
||
### 1. Visual state and business state drift apart
|
||
|
||
Earth 里最常见的 bug 不是“没渲染”，而是状态没有一起收口：
|
||
|
||
- 图层关了，tooltip 还在
|
||
- 锁定对象隐藏了，info card 还在
|
||
- legend 没跟图层切换
|
||
- loading 已结束，但按钮还像没开
|
||
|
||
后续架构治理需要把这类同步责任从临时 UI patch 转为统一状态流。
|
||
|
||
### 2. HUD layout fixes skip structure analysis
|
||
|
||
Earth HUD 历史上反复出现：
|
||
|
||
- 面板只剩一条缝
|
||
- markdown 被裁掉
|
||
- tabs / iframe 被 `overflow: hidden` 吃掉
|
||
|
||
这类问题应纳入布局治理计划，而不是散落在单个功能改动里临时修。
|
||
|
||
### 3. Transitional paths keep accumulating
|
||
|
||
Earth 已经经历过多轮 HUD、toolbar、media panel 重构，容易留下：
|
||
|
||
- 旧 helper
|
||
- 旧 class
|
||
- 旧 fallback 逻辑
|
||
- 已废弃变体
|
||
|
||
架构分离阶段需要把 cleanup pass 作为计划项，而不是让技术上下文承担提醒职责。
|
||
|
||
### 4. Cruise logic and business events couple too deeply
|
||
|
||
巡航相关风险是通用巡航层继续混入业务事件细节，导致 BGP、新闻、卫星、海缆各自复制一套状态机。
|
||
|
||
架构目标应保持：
|
||
|
||
- 通用巡航层管理目标、队列、focus、停留、隐藏和切换
|
||
- 业务模块只提供队列、坐标、卡片内容和高亮副作用
|
||
|
||
## 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. 这个视觉变化是否能在不改逻辑的情况下单独替换？
|
||
|
||
如果答不上来，就说明还在把状态、逻辑、渲染揉在一起。
|