docs: add architecture refactor and webgl instancing plans

.sisyphus/plans/earth-architecture-refactor.md

@@ -0,0 +1,165 @@
+# 地球3D可视化架构重构计划
+
+## 背景
+
+当前 `frontend/public/earth` 3D地球可视化系统基于 Three.js 构建，未来需要迁移到 Unreal Engine (Cesium)。为降低迁移成本，需要提前做好**逻辑与渲染分离**的架构设计。
+
+## 目标
+
+- 将线缆高亮逻辑与渲染实现分离
+- 保持交互逻辑可复用，只需重写渲染层
+- 为后续迁移到 UE/Cesium 做好准备
+
+## 已完成
+
+### 1. 状态枚举定义 (constants.js)
+
+```javascript
+export const CABLE_STATE = {
+  NORMAL: 'normal',
+  HOVERED: 'hovered',
+  LOCKED: 'locked'
+};
+```
+
+### 2. 线缆状态管理 (cables.js - 数据层)
+
+```javascript
+const cableStates = new Map();
+
+export function getCableState(cableId) { ... }
+export function setCableState(cableId, state) { ... }
+export function clearAllCableStates() { ... }
+export function getCableStateInfo() { ... }
+```
+
+### 3. 逻辑层调用 (main.js)
+
+```javascript
+// 悬停
+setCableState(cable.userData.cableId, CABLE_STATE.HOVERED);
+
+// 锁定
+setCableState(cableId, CABLE_STATE.LOCKED);
+
+// 恢复
+setCableState(cableId, CABLE_STATE.NORMAL);
+clearAllCableStates();
+
+// 清除锁定时
+clearLockedObject() {
+  hoveredCable = null;
+  clearAllCableStates();
+  ...
+}
+```
+
+### 4. 渲染层 (main.js - applyCableVisualState)
+
+```javascript
+function applyCableVisualState() {
+  const allCables = getCableLines();
+  const pulse = (Math.sin(Date.now() * CABLE_CONFIG.pulseSpeed) + 1) * 0.5;
+  
+  allCables.forEach(c => {
+    const cableId = c.userData.cableId;
+    const state = getCableState(cableId);
+    
+    switch (state) {
+      case CABLE_STATE.LOCKED:
+        // 呼吸效果 + 白色
+        c.material.opacity = CABLE_CONFIG.lockedOpacityMin + pulse * CABLE_CONFIG.pulseCoefficient;
+        c.material.color.setRGB(1, 1, 1);
+        break;
+      case CABLE_STATE.HOVERED:
+        // 白色高亮
+        c.material.opacity = 1;
+        c.material.color.setRGB(1, 1, 1);
+        break;
+      case CABLE_STATE.NORMAL:
+      default:
+        if (lockedObjectType === 'cable' && lockedObject) {
+          // 其他线缆变暗
+          c.material.opacity = CABLE_CONFIG.otherOpacity;
+          ...
+        } else {
+          // 恢复原始
+          c.material.opacity = 1;
+          c.material.color.setHex(c.userData.originalColor);
+        }
+    }
+  });
+}
+```
+
+## 待完成
+
+### Phase 1: 完善状态配置 (constants.js)
+
+```javascript
+export const CABLE_CONFIG = {
+  lockedOpacityMin: 0.6,
+  lockedOpacityMax: 1.0,
+  otherOpacity: 0.5,
+  otherBrightness: 0.6,
+  pulseSpeed: 0.003,
+  pulseCoefficient: 0.4,
+  // 未来可扩展
+  // lockedLineWidth: 3,
+  // normalLineWidth: 1,
+};
+```
+
+### Phase 2: 卫星状态管理 (satellites.js)
+
+参考线缆状态管理，为卫星添加类似的状态枚举和状态管理函数：
+
+```javascript
+export const SATELLITE_STATE = {
+  NORMAL: 'normal',
+  HOVERED: 'hovered',
+  LOCKED: 'locked'
+};
+```
+
+#### 卫星数据源说明
+
+- **当前使用**: CelesTrak (https://celestrak.org) - 免费，无需认证
+- **后续计划**: Space-Track.org (https://space-track.org) - 需要认证，数据更权威
+- 迁移时只需修改 `satellites.js` 中的数据获取逻辑，状态管理和渲染逻辑不变
+
+### Phase 3: 统一渲染接口
+
+将所有对象的渲染逻辑抽象为一个统一的渲染函数：
+
+```javascript
+function applyObjectVisualState() {
+  applyCableVisualState();
+  applySatelliteVisualState();
+  applyLandingPointVisualState();
+}
+```
+
+### Phase 4: UE 迁移准备
+
+迁移到 Unreal Engine 时：
+1. 保留 `constants.js` 中的枚举和配置
+2. 保留 `cables.js` 中的数据层和状态管理
+3. 保留 `main.js` 中的交互逻辑
+4. **仅重写** `applyCableVisualState()` 等渲染函数
+
+---
+
+## 架构原则
+
+1. **状态与渲染分离** - 对象状态由数据层管理，渲染层只负责根据状态更新视觉效果
+2. **逻辑可复用** - 交互逻辑（点击、悬停、锁定）在迁移时应直接复用
+3. **渲染可替换** - 渲染实现可以针对不同引擎重写，不影响逻辑层
+
+## 文件变更记录
+
+| 日期 | 文件 | 变更 |
+|------|------|------|
+| 2026-03-19 | constants.js | 新增 CABLE_STATE 枚举 |
+| 2026-03-19 | cables.js | 新增状态管理函数 |
+| 2026-03-19 | main.js | 使用状态管理，抽象 applyCableVisualState() |