166 lines
4.2 KiB
Markdown
166 lines
4.2 KiB
Markdown
# 地球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() |
|