planet/docs/plans/earth-interactable-layer-plan.md

# Earth Interactable Layer Plan

## 背景

状态：Phase 1 已经开始落地，Phase 2 的 BGP 事件 / 观测站迁移和 Phase 3 的算力中心迁移也已完成。`frontend/public/earth/js/interactable.js` 已新增，AIS 船只、BGP 事件、BGP 观测站和算力中心图层已经改为通过 `createInteractableLayer()` 使用通用批量 `Points`、hover / locked overlay、默认 glow、状态更新、asset icon 预加载、屏幕空间 picking、固定 / 距离缩放和跨 Interactable 同坐标关系元数据。登陆点因 `THREE.Points` 边缘深度裁切和贴地层级要求，已退回专用 `THREE.Sprite` 黄色球路径，并与海缆同高度同 renderOrder。后续阶段聚焦把可复用的扩圈 / 雷达扇形动画正式沉淀成 `animations` 扩展。

当前实现说明和接入示例见：

- [earth-interactable-usage.md](/home/ray/dev/linkong/planet/docs/technical/zh/earth-interactable-usage.md)

当前 AIS 船只图层已经形成了一个适合作为基准的交互图标模式：

- 普通态使用批量 `THREE.Points` 渲染，避免每个对象一个 `Sprite` 带来的 draw call 和透明排序压力。
- hover / locked 态使用单点 overlay 叠加 glow，不改变普通批次，交互反馈清晰且成本低。
- moving / anchored 船只通过 canvas 点纹理表达不同形状，moving 船只还按航向分桶。
- 拾取走屏幕空间命中，拖动和惯性期间跳过高频 hover picking。
- 图层高度贴近地表，仅保留很小的深度余量，避免“浮在表面层”的观感。

这个模式不应该只服务船只。后续 BGP 事件、BGP 观测站、算力中心、新闻事件、告警、地面传感器等都可能需要“图标类可交互元素”。如果每个图层继续各写一套 icon、glow、hover、locked、动画、picking 和图例逻辑，视觉会漂移，性能策略也会重复分叉。登陆点已经验证为例外：需要完整贴地且不被球面边缘裁切时，专用 Sprite 路径比通用 `Points` 更合适。

目标是把船只图层的成功做法抽象成一个通用接口：业务图层只描述“要画什么、在哪里、怎么交互”，底层统一负责批量渲染、默认 glow、状态 overlay、动画槽位、拾取和生命周期。

## 目标

1. 建立统一的 Earth 交互图标接口，作为未来地表图标类元素的默认入口。
2. 以 AIS 船只 glow 为默认 glow 视觉，其它图标默认沿用同一套 glow 质感。
3. 保留图标颜色、状态颜色、hover 放大、locked 强调、dimmed 聚焦、动画扩展等能力。
4. 支持 canvas / SVG / image icon，不强行要求所有图标都可重着色。
5. 保持船只当前性能路线：批量绘制普通态，少量 overlay 处理交互态。
6. 给 BGP 事件扩圈、BGP 观测站雷达扇形等补充动画留出正式扩展点。

## 非目标

- 不在第一阶段重写所有 Earth 图层。
- 不把卫星、海缆、国家边界、真实地形这类非图标图层纳入同一个接口。
- 不为了抽象牺牲业务图标的差异表达，例如船只航向、BGP 事件严重级别、观测站雷达扫掠。
- 不要求图片图标支持运行时重着色；图片图标只能通过预制多状态图片或 overlay tint 做有限表达。

## 核心设计

建议新增一个通用模块，例如：

```text
frontend/public/earth/js/interactable.js
```

它导出一个工厂或注册函数：

```js
createInteractableLayer({
  id,
  earth,
  renderOrder,
  altitudeOffset,
  icon,
  scale,
  glow,
  colors,
  states,
  animations,
  picking,
  data,
  getPosition,
  getKind,
  getRotation,
  getPayload,
});
```

业务模块仍保留自己的数据加载、图例、详情卡字段和业务语义。例如 `vessels.js` 负责 AIS 数据和船型映射，但 icon 渲染、hover overlay、locked overlay、默认 glow 和屏幕空间 picking 可以逐步迁入 `interactable.js`。

## 参数草案

| 参数 | 类型 / 示例 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `id` | `"vessels"` | 必填 | 图层唯一标识，用于 debug、picking、legend 和状态缓存。 |
| `earth` | `THREE.Object3D` | 必填 | 图层挂载目标，通常是 Earth root。 |
| `renderOrder` | `4.4` | `4` | 普通 icon 批次和 overlay 的基础渲染顺序。 |
| `altitudeOffset` | `0.2` | `0.2` | 图层高度，语义为 `CONFIG.earthRadius + altitudeOffset`。地表图标默认贴近真实地形基础层。 |
| `icon` | `{ type, source, draw, size, bins }` | 必填 | 图标来源。支持 canvas draw、SVG URL、image URL、内置 shape。 |
| `icon.fitSize` | `60` 或 `{ width: 60, height: 60 }` | `atlasCellSize` | asset 图标在 atlas canvas 内的最大绘制尺寸，默认居中等比 contain。SVG / 图片文件只负责原始形状，不需要为了显示大小手写 transform。 |
| `scale` | `{ base, min, max }` | `{ base: 1 }` | 基础缩放和距离稳定范围。当前船只可映射到 `VESSEL_POINT_SIZE` / `baseScale`。 |
| `sizeMode` | `"fixed" / "distance"` | `"fixed"` | 是否固定屏幕像素尺寸；非 fixed 时按相机到地表距离做比例缩放。 |
| `sizeScale` | `{ min, max, referenceFov }` | `{ min: 0.12, max: 3, referenceFov: 75 }` | `sizeMode !== "fixed"` 时的缩放限制和参考视角。 |
| `glow.enabled` | `true / false` | `true` | 是否启用默认 glow。默认 glow 以船只 hover / locked overlay 为基准。 |
| `glow.intensity` | `0.0 - 2.0` | `1` | glow 强度，内部映射到 canvas `shadowBlur`、opacity 或 shader uniform。 |
| `glow.colorMode` | `"state" / "icon" / "fixed"` | `"state"` | glow 颜色来源，默认跟随状态颜色。 |
| `hover.scale` | `1.0 - 2.0` | `1.18` | hover 放大倍率。当前船只保持同尺寸 glow overlay，接口仍保留放大能力供其它图层使用。 |
| `hover.mode` | `"scale" / "glow-only" / "custom"` | `"scale"` | hover 反馈方式。船只可用 `"glow-only"`，其它图标默认放大。 |
| `colors.normal` | `"#4A90D9"` | icon 原色 | 普通态颜色。只有可上色 icon 生效。 |
| `colors.hover` | `"#7dd3fc"` | normal | hover 态颜色。 |
| `colors.locked` | `"#ffffff"` | hover | locked 态颜色。 |
| `colors.dimmed` | `"#9B9B9B"` | normal | 聚焦其它对象时的弱化颜色。 |
| `colors.byKind` | `{ cargo: "#4A90D9" }` | `{}` | 按业务类型着色，如船型、BGP 严重级别。 |
| `colorable` | `true / false` | 由 icon 类型推断 | canvas shape 和 SVG mask 通常可上色；图片默认不可上色。 |
| `opacity` | `{ normal, hover, locked, dimmed }` | 船只当前值 | 各状态透明度。 |
| `rotation` | `{ enabled, bins, getAngle }` | disabled | 是否按角度分桶，例如船只按 COG 分 32 桶。 |
| `animations` | `IconAnimationSpec[]` | `[]` | 补充动画列表，例如扩圈、雷达扇形、脉冲、轨迹尾迹。 |
| `picking.radiusPx` | `22` | `20` | 屏幕空间命中半径。 |
| `picking.throttleMs` | `100` | `80` | hover picking 节流。 |
| `picking.skipWhileDragging` | `true` | `true` | 拖动和惯性期间跳过 hover picking。 |
| `zIndexPolicy` | `"surface-icon"` | `"surface-icon"` | 预设层级策略，避免每个业务图层手写高度和 renderOrder。 |
| `avoidance.enabled` | `true / false` | `true` | 是否记录跨 Interactable 的同坐标关系。该配置只生成 overlap 元数据，不允许移动真实 marker 坐标。 |
| `avoidance.precision` | `number` | `4` | 经纬度归并精度，默认约等于只处理几乎完全重叠的图标。 |
| `cluster.enabled` | `true / false` | 跟随 avoidance | 是否参与跨 Interactable 的当前帧屏幕重叠合并。只影响显示，不改变业务坐标。 |
| `cluster.maxMarkersPerDot` | `number` | `14` | 单个聚合圆点的对象上限；超过后按屏幕局部邻近关系拆成多个较小圆点，避免一个点过大或跨区域串联。 |
| `legend` | `{ label, color, shape }[]` | `[]` | 可选图例声明，业务层也可以继续自己导出。 |
| `metadata` | object | `{}` | 业务扩展数据，不参与渲染但参与 tooltip / info-card / search。 |

## Icon 规格

图标输入建议分三类：

```js
{
  type: "canvas-shape",
  size: 128,
  draw(ctx, state) {
    // draw triangle / dot / custom shape
  },
}
```

```js
{
  type: "svg-mask",
  source: "/earth/assets/icons/bgp-event-dot.svg",
  colorable: true,
}
```

```js
{
  type: "image",
  source: "/earth/assets/icons/vendor-logo.png",
  colorable: false,
  stateSources: {
    hover: "/earth/assets/icons/vendor-logo-hover.png",
  },
}
```

颜色策略：

- `canvas-shape` 默认可上色，适合船只、事件点、雷达站这类符号。
- `svg-mask` 如果能作为 mask 使用，则可上色；如果是完整多色 SVG，则按图片处理。
- `image` 默认不可上色；需要状态变化时使用 `stateSources` 或额外 glow / ring。

## 默认 Glow 规范

默认 glow 以当前船只 overlay 为视觉基准：

- 普通态尽量不启用 glow，保持地图干净。
- hover / locked 态叠加同位置 overlay。
- glow 颜色默认跟随状态颜色或业务类型颜色。
- glow blur 应该稳定，不随 camera zoom 夸张膨胀。
- 允许通过 `glow.intensity` 控制强度，但不要让业务图层各自发明完全不同的光晕语言。

建议内部把 glow 拆成两个层次：

1. `textureGlow`：canvas texture 里的 `shadowBlur`，适合小图标 hover / locked。
2. `effectGlow`：额外 ring / halo / pulse，适合告警、BGP 事件和锁定强调。

## 状态模型

通用状态至少包含：

| 状态 | 触发 | 默认表现 |
| --- | --- | --- |
| `normal` | 普通显示 | 批量 Points，使用 normal 颜色和 opacity。 |
| `hover` | 指针悬停 | 默认放大并显示 glow；船只可配置为同尺寸 glow-only。 |
| `locked` | 点击锁定 / 详情打开 | 强 glow、更高 opacity，可选 ring 或 pulse。 |
| `dimmed` | 聚焦其它对象 | 降低 opacity，保留上下文。 |
| `hidden` | 图层关闭或过滤 | 不参与绘制和 picking。 |
| `alert` | 业务告警 | 可叠加动画，不替代 locked 状态。 |

状态更新需要增量化：只在 hover 目标、locked 目标、过滤条件、数据版本或相机距离阈值变化时更新，不在每帧遍历全部 icon 写材质属性。

## 动画扩展

动画不直接塞进 icon 基础参数，而是作为 `animations` 列表注册。每个动画声明自己的 geometry / material / update 策略：

```js
{
  type: "expanding-ring",
  when: ["alert", "locked"],
  color: "state",
  radiusPx: [10, 42],
  durationMs: 1400,
  opacity: [0.8, 0],
}
```

```js
{
  type: "radar-sweep",
  when: ["normal", "hover", "locked"],
  angleDeg: 72,
  rotationMs: 2600,
  opacity: 0.36,
}
```

首批建议内置动画：

| 动画 | 用例 | 说明 |
| --- | --- | --- |
| `pulse-ring` | locked、告警点 | 原地呼吸环，强调选中对象。 |
| `expanding-ring` | BGP 事件 | 向外扩散的事件波纹。 |
| `radar-sweep` | BGP 观测站 | 扇形扫描，可持续旋转。 |
| `orbiting-dot` | 数据流 / collector 活跃态 | 小点绕 icon 环绕，表达活动状态。 |
| `trail` | 移动目标 | 可选短尾迹，船只或飞机类目标使用。 |

动画必须支持批量或分组绘制，避免为每个对象创建独立的高频更新对象。只有 locked / hover / 少量 alert 对象可以使用单对象 overlay。

## 渲染策略

### 普通态

普通态优先使用分桶 `THREE.Points`：

- 按 icon 类型、可上色策略、旋转分桶、纹理 key 分组。
- 每组一个 `BufferGeometry`，存 `position`、`color`、必要的 `payloadIndex`。
- `PointsMaterial.sizeAttenuation = false`，保持屏幕尺寸稳定。
- `depthTest = true`，`depthWrite = false`，避免遮挡关系破坏地表。

### 交互态

hover / locked 使用少量 overlay：

- overlay 复用 `THREE.Points` 单点对象或小型 ring mesh。
- overlay texture 从统一 cache 获取。
- overlay 更新只写当前 hover / locked 的 position、texture、opacity、size。

### 高密度升级

当某类图标超过分桶 Points 的舒适区，才考虑升级：

- `InstancedBufferGeometry` billboard。
- 自定义 shader 支持 per-instance rotation / scale / opacity。
- 视口 bbox / LOD / cluster。

这个升级不应该改变业务接口，只替换底层 renderer。

## Picking 策略

沿用船只当前方向：

- 默认屏幕空间 picking，而不是 Three.js 对每个 Sprite / Points 做 raycast。
- 每个 icon 保留世界坐标和业务 payload。
- 每次 pointer move 将候选点投影到屏幕，按半径和深度判断命中。
- 拖动、惯性旋转、相机剧烈变化期间跳过 hover picking。
- click 时允许做一次更精确的 picking。

后续可以按图层或经纬度网格增加空间索引，减少候选点数量。

## 与现有图层的迁移路径

### Phase 1：抽出船只基准能力

- 从 `vessels.js` 提取 texture cache、canvas icon draw、overlay glow、分桶 Points 创建、状态增量更新。
- 保持 `vessels.js` 的公开 API 不变：`loadVessels()`、`toggleVessels()`、`getVesselMarkers()` 等继续可用。
- 新模块先只服务船只，确保视觉没有回退。

### Phase 2：迁移 BGP 事件和观测站

- BGP 事件使用 `canvas-shape`，已接入 `Interactable`。
- 严重级别映射到 `colors.byKind`，并通过通用 `getPointSizeMultiplier` 保留严重级别尺寸倍率。
- 当前扩圈效果保留在 BGP 业务动画中，并跟随 `Interactable` marker 位置更新。
- BGP 观测站主图标已接入 `Interactable`，活跃度映射到颜色和 `getPointSizeMultiplier`。
- BGP 观测站 halo / 覆盖扇形继续由 BGP 业务动画表达扫描，并跟随 `Interactable` marker 位置更新。

### Phase 3：迁移算力中心并评估登陆点

- 算力中心保留现有业务 icon，但接入统一 hover / locked / glow。（已完成）
- 登陆点曾接入同一套 `Points` 渲染，但 pin 类 SVG 在地球边缘会被深度测试裁切；当前保留专用 `THREE.Sprite`，并使用 canvas 生成黄色扁平球，贴到海缆层级。
- 登陆点暂不迁移到完整 Interactable。后续若要统一交互接口，优先考虑 Sprite-backed adapter，只对齐 `getMarkers()`、`getPointerIntersections()`、`setMarkerState()`、`updateVisualState()` 等外观协议，不强行复用 `THREE.Points`、atlas 和跨图层避让。
- 检查图例、搜索和 info-card 是否只依赖业务 payload，而不是依赖渲染对象类型。

### Phase 4：形成 Earth 图标层规范

- 在 `docs/technical/zh/earth-frontend-context.md` 记录当前实现入口。
- 在 `docs/technical/zh/earth-layer-style-reference.md` 记录默认 glow、状态颜色、默认高度和动画参数。
- 在 `docs/technical/zh/earth-render-layer-order.md` 记录 surface icon renderOrder 范围。

## 风险与约束

- 过早抽象可能让船只这种高质量基准被平均化，因此第一阶段必须以船只视觉不回退为验收标准。
- 图片 icon 不可上色，接口需要明确 `colorable = false` 的行为，避免业务层误以为颜色一定生效。
- 动画如果默认开启过多，会重新引入 overdraw 和每帧更新压力；默认只给 hover / locked 或少量 alert 使用。
- 地形开启时，贴地 icon 需要在高度、`depthTest`、`polygonOffset` 和 renderOrder 之间保持平衡。
- 统一 glow 不等于所有图标一模一样；业务可以调强度和颜色，但不应破坏整体视觉语言。

## 验收标准

1. 船只迁入通用接口后，普通态、hover、locked、航向、颜色、轨迹和 picking 行为保持一致。
2. 新增一个 BGP 事件示例图层配置，不需要复制船只渲染代码即可得到 icon、glow、hover 和扩圈动画。
3. 新增一个 BGP 观测站示例图层配置，不需要自写独立动画循环即可得到雷达扇形。
4. 关闭图层后对应 icon、overlay、动画和 picking 全部停止。
5. 高密度数据下普通态仍走批量绘制，hover / locked 只更新少量 overlay。
6. 文档同步说明默认高度、默认 glow、状态模型和动画扩展点。

## 相关文件

| 文件 | 当前角色 | 未来关系 |
| --- | --- | --- |
| `frontend/public/earth/js/vessels.js` | 船只基准实现，包含分桶 Points、hover / locked overlay、默认 glow 形态 | Phase 1 的抽象来源 |
| `frontend/public/earth/js/constants.js` | 保存船只高度、颜色、透明度、轨迹参数 | 后续可加入通用 surface icon 默认配置 |
| `frontend/public/earth/js/bgp.js` | BGP 事件和观测站视觉逻辑 | BGP 事件和观测站主图标已接入 Interactable；扩圈、halo 和覆盖扇形仍保留业务动画 |
| `frontend/public/earth/js/compute-centers.js` | 算力中心 icon 和交互 | 已通过 Interactable 接入统一 Points、overlay、glow 和 picking |
| `frontend/public/earth/js/cables.js` | 登陆点 icon 和海缆线 | 登陆点当前使用专用 `THREE.Sprite` 黄色球，不再走 Interactable；海缆线仍独立渲染 |
| `frontend/public/earth/js/main.js` | 当前集中处理 hover、click、locked 和 info-card 入口 | 后续需要接入通用 icon picking 结果 |
| `docs/technical/zh/earth-layer-style-reference.md` | 当前视觉参数参考 | 实现后同步默认 glow 和通用参数 |
| `docs/technical/zh/earth-render-layer-order.md` | 当前层级参考 | 实现后同步 surface icon 层级范围 |