release: bump version to 0.46.0

2026-04-30 04:42:29 +08:00
parent ba54545ac7
commit b1a5934b80
29 changed files with 2351 additions and 1095 deletions
--- a/docs/technical/zh/README.md
+++ b/docs/technical/zh/README.md
@@ -24,6 +24,7 @@
 - [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)：从零启动 Planet 的最短路径
 - [manual.md](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)：控制台、`planet.sh`、Earth 和 Docs 的完整使用手册
 - [datasource-collector-settings-connectivity.md](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)：数据源目录、采集器设置、连接验证、BarentsWatch 凭证链路
+- [earth-interactable-usage.md](/home/ray/dev/linkong/planet/docs/technical/zh/earth-interactable-usage.md)：Earth 地表可交互图标 `Interactable` 的接口、生命周期和接入示例

 不适合放入这里的内容：

--- a/docs/technical/zh/earth-frontend-context.md
+++ b/docs/technical/zh/earth-frontend-context.md
@@ -249,11 +249,13 @@ Earth 图层按钮现在不应再只有“开/关”两态，而应支持：
 AIS 船只图层入口：

 - [vessels.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/vessels.js)
+- [interactable.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/interactable.js)

 船只图层当前负责：

 - 请求 `/api/v1/visualization/geo/vessels`
 - 将 BarentsWatch AIS GeoJSON 转为地球局部坐标 marker 数据
+- 通过 `createInteractableLayer()` 注册 Interactable 图标层
 - 用按航向分桶的 `THREE.Points` 批量渲染普通船只 marker
 - 按船型映射颜色
 - 根据航行/停泊状态绘制三角形或圆点纹理
@@ -271,7 +273,7 @@ AIS 船只图层入口：

 方向标准以 AIS `course / cog` 为准：从正北开始顺时针。普通态和交互态都通过同一套 canvas 旋转规则生成纹理，避免 hover 后箭头方向和原 marker 不一致。

-船只 hover / click 也不再对渲染对象做 `raycaster.intersectObjects()`。`main.js` 会：
+船只 hover / click 也不再对渲染对象做 `raycaster.intersectObjects()`。`main.js` 只负责传入当前 Earth、camera、pointer 和命中半径，实际命中计算由 `interactable.js` 的图标层接口完成：

 1. 拖动地球或惯性旋转时跳过 hover picking。
 2. 对 hover picking 做轻量节流。
@@ -293,6 +295,24 @@ AIS 船只图层入口：

 图例项颜色来自 `VESSEL_CONFIG.colors`，不要在 `legend.css` 里重新定义业务颜色。新增船型时，应优先改 `vessels.js` 和 `constants.js` 的船型映射，再同步图例项。

+`interactable.js` 是后续地表图标类图层的共用入口。它当前已经承载船只、BGP 事件、BGP 观测站和算力中心图层的批量 `Points`、texture cache、hover / locked overlay、默认 glow、状态增量更新和屏幕空间 picking；BGP 事件的向外扩散圈、BGP 观测站的 halo / 覆盖扇形仍由 `bgp.js` 保留业务动画，但图标本体和 pointer 命中已经接入通用层。新增小型、中心对齐、可以参与深度测试的图标类元素时，应优先复用这个接口，而不是再次复制船只渲染逻辑。
+
+登陆点是当前明确保留的例外：它曾接入 `Interactable`，但 pin 类 SVG 在地球边缘会被 `THREE.Points` 的深度测试裁切成碎片；关闭 depthTest 又会破坏背面遮挡语义。因此登陆点退回 `cables.js` 内的专用 `THREE.Sprite` 路径，并改为 canvas 生成的黄色扁平球纹理。它的 `altitudeOffset` 和 `renderOrder` 与海缆线一致，避免漂在海缆之上；Sprite 本体关闭 `depthTest` 保持球完整，背面可见性由 `isFacingCamera()` 的球体遮挡判断控制。
+
+图标资源可以继续用 canvas draw，也可以放到 `frontend/public/earth/assets/icons/` 后由 `Interactable` 预加载。asset 路径不会在每帧读取；图层加载阶段通过 `preloadAssets()` 只加载一次 SVG / 图片，之后按 `icon source + state + bucket + color` 生成 `CanvasTexture` 并复用。当前算力中心已经从 `assets/icons/compute-supercomputer.svg`、`assets/icons/compute-gpu-cluster.svg` 和备用 `assets/icons/compute-hdd-network.svg` 读取图标，再在 canvas 上叠加估算位置的 `?` badge。
+
+asset 图标大小由 `Interactable` 的 `icon.fitSize` 控制。SVG / 图片文件应尽量保持原始 viewBox 和路径，不要为了在地球上显示成 60x60 而手写 `transform`；`drawAssetIcon()` 会把资源等比 contain 到指定尺寸并居中绘制到 atlas canvas。
+
+`Interactable` 默认使用固定屏幕像素尺寸，适合船只、BGP 事件、BGP 观测站、算力中心这类需要稳定识别的图标。如果某类图标需要跟随相机距离缩放，可以把 `sizeMode` 设为非 `"fixed"`，并用 `sizeScale.min / max / referenceFov` 控制缩放范围；单个 marker 的业务尺寸差异可以通过 `getPointSizeMultiplier()` 表达，例如 BGP 事件按严重级别调整点大小，BGP 观测站按活跃度调整点大小。
+
+`Interactable` 不再把图标本体额外抬离业务高度。`altitudeOffset` 就是 marker、hover glow、locked glow 和 picking 共同使用的地表高度；这样船只图标会继续贴着船只轨迹线，不会因为单独抬高显示位置而显得漂浮。后续如果要解决边缘 glow 裁切，应优先考虑 glow 纹理、overlay 尺寸或图层专属特效，而不是把通用图标层整体抬高。
+
+跨 Interactable 的同坐标避让也在公共层处理。每个 marker 会保留 `icon_base_position` 作为业务原始位置；当多个 Interactable marker 归入同一个经纬度 key 时，公共层会把它们沿地表切平面排成小圈，并刷新已创建的 `THREE.Points` geometry。这样视觉位置和屏幕空间 picking 位置一致，不需要业务层再单独判断“算力中心和 BGP 事件重叠”这类场景。
+
+接口细节、生命周期和接入示例见：
+
+- [earth-interactable-usage.md](/home/ray/dev/linkong/planet/docs/technical/zh/earth-interactable-usage.md)
+
 ### 视角控制反馈

 [controls.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js) 统一维护 Earth 缩放状态。滚轮缩放、缩放按钮和触屏双指捏合最终都会更新 `zoomLevel`，并通过 `showZoomStatusCapsule()` 显示当前缩放比例：
--- a/docs/technical/zh/earth-interactable-usage.md
+++ b/docs/technical/zh/earth-interactable-usage.md
@@ -0,0 +1,270 @@
+# Earth Interactable 使用说明
+
+`Interactable` 是 Earth 地表“图标类可交互元素”的通用渲染入口。它把船只图层验证过的模式抽成公共能力：普通态用批量 `THREE.Points`，hover / locked 用少量 overlay，拾取走屏幕空间命中，图标资源统一转进 canvas texture，并在公共层处理 glow、状态、尺寸、贴地渲染和同坐标避让。
+
+当前已接入：
+
+| 图层 | 业务文件 | 图标来源 | 补充动画 |
+| --- | --- | --- | --- |
+| AIS 船只 | `frontend/public/earth/js/vessels.js` | canvas draw，航行三角形 / 停泊圆点 | 船只轨迹仍由业务层维护 |
+| 算力中心 | `frontend/public/earth/js/compute-centers.js` | `assets/icons/compute-*.svg` | 估算位置 `?` badge 通过 `icon.afterDraw()` 叠加 |
+| BGP 事件 | `frontend/public/earth/js/bgp.js` | canvas draw，按事件类型绘制符号 | 向外扩散圈仍由 BGP 业务层维护 |
+| BGP 观测站 | `frontend/public/earth/js/bgp.js` | `assets/icons/bgp-broadcast-pin.svg` | halo、活跃度 core、覆盖扇形和雷达扫掠仍由 BGP 业务层维护 |
+
+登陆点曾尝试接入 Interactable，但 pin 类 SVG 在地球边缘会被 `THREE.Points` 深度测试裁切成碎片；当前退回 `THREE.Sprite` 专用路径，并改为由 canvas 生成黄色扁平球纹理。旧 SVG 资产保留在 `assets/icons/` 目录中，但登陆点运行时不再依赖 SVG。
+
+## 为什么需要 Interactable
+
+之前每个地表图标图层都容易各写一套：
+
+- icon texture 生成
+- hover / locked 状态
+- glow 样式
+- picking 命中半径
+- zoom 下的尺寸策略
+- 同经纬度对象重叠避让
+
+这些逻辑如果分散在业务文件里，视觉会漂移，后续调参也会变成逐图层修补。`Interactable` 的边界是：公共层负责“图标怎么在地球上稳定显示和被选中”，业务层负责“数据从哪里来、图标表达什么语义、详情卡展示什么、是否有额外动画”。
+
+## 入口
+
+```javascript
+import { createInteractableLayer } from "./interactable.js";
+```
+
+核心调用形态：
+
+```javascript
+const layer = createInteractableLayer({
+  id: "example",
+  objectType: "example_object",
+  renderOrder: 4.4,
+  altitudeOffset: 0.2,
+  pointSize: 34,
+  icon: {
+    draw(context, options) {
+      // draw canvas icon
+    },
+  },
+  getPosition: (item) => ({
+    latitude: item.latitude,
+    longitude: item.longitude,
+  }),
+  getKind: (item) => item.kind || "default",
+});
+```
+
+业务模块通常只暴露一层薄封装：
+
+```javascript
+export function getExampleMarkers() {
+  return layer.getMarkers();
+}
+
+export function getExamplePointerIntersections(options) {
+  return layer.getPointerIntersections(options);
+}
+
+export function setExampleMarkerState(marker, state = "normal") {
+  layer.setMarkerState(marker, state);
+}
+
+export function updateExampleVisualState(lockedObjectType, lockedObject, camera) {
+  layer.updateVisualState(lockedObjectType, lockedObject, camera);
+}
+```
+
+## 配置参数
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `id` | 必填 | 图层唯一标识，用于 group name、避让注册和 debug。 |
+| `objectType` | `id` | marker 写入 `userData.type` 的业务类型，主交互层用它判断 locked 对象。 |
+| `renderOrder` | `4` | 普通 points 和 hover / locked overlay 的基础渲染顺序。 |
+| `altitudeOffset` | `0.2` | 业务高度，按 `CONFIG.earthRadius + altitudeOffset` 计算原始地表位置。 |
+| `pointSize` | `32` | 基准屏幕像素尺寸。普通 points 和 overlay 都以它为基础。 |
+| `sizeMode` | `"fixed"` | 默认固定屏幕尺寸；非 `"fixed"` 时会按相机距离做比例缩放。 |
+| `sizeScale` | `{ referenceFov: 75, min: 0.12, max: 3 }` | `sizeMode !== "fixed"` 时的缩放范围。 |
+| `atlasCellSize` | `128` | icon canvas texture 尺寸。 |
+| `colors` | `{}` | 支持 `normal`、按 kind 的平铺 key，以及 `byKind`。 |
+| `opacity` | `{ normal: 0.88, dimmed: 0.26, hover: 0.98, locked: 1 }` | 各状态透明度。 |
+| `stateScale` | `{ hover: 1, locked: 1, dimmed: 1 }` | 各状态尺寸倍率。 |
+| `pulse` | `{}` | locked 态可选呼吸缩放，支持 `enabled`、`speed`、`amplitude`。 |
+| `avoidance` | `{ enabled: true, precision: 4, radius: 1.1, step: 0.35 }` | 跨 Interactable 的同坐标避让配置。 |
+| `icon` | 必填 | 图标来源，支持 canvas draw、SVG / 图片 asset、状态 asset、锚点和后处理。 |
+| `getPosition(item)` | 必填 | 返回 `{ latitude, longitude }` 或 `THREE.Vector3`。 |
+| `getKind(item)` | `item.type || "default"` | 返回业务类型，用于颜色和 texture 分桶。 |
+| `getRotationBin(marker)` | `0` | 返回旋转分桶，例如船只按航向分 32 桶。 |
+| `getBucketKey(marker)` | `String(getRotationBin(marker))` | 返回 texture / geometry 分桶 key。 |
+| `getPointSizeMultiplier(marker)` | `1` | 单 marker 尺寸倍率。BGP 事件按严重级别、观测站按活跃度使用它。 |
+| `getUserData(item)` | `item` | 写入 marker 的业务字段。 |
+
+## Icon 配置
+
+`icon.anchor` 可选，默认 `{ x: 0.5, y: 0.5 }`，表示纹理中心对齐 marker 坐标。它只适合小范围的视觉锚点偏移；如果图标主体很大、且需要在地球边缘完整显示，例如登陆点曾使用过的 pin 类图标，不应强行走 `THREE.Points + depthTest`，否则图标主体会被地球深度裁切。
+
+### Canvas 图标
+
+canvas 图标适合船只、BGP 事件这类需要按状态或旋转动态绘制的符号：
+
+```javascript
+const vesselIconLayer = createInteractableLayer({
+  id: "vessels",
+  objectType: "vessel",
+  pointSize: 34,
+  icon: {
+    draw(context, { marker, rotationBin = 0, glow = false, color = "#ffffff" }) {
+      if (!marker.userData.anchored) {
+        context.rotate((rotationBin / 32) * Math.PI * 2);
+      }
+      context.fillStyle = color;
+      context.shadowColor = color;
+      context.shadowBlur = glow ? 14 : 0;
+      context.beginPath();
+      context.moveTo(0, -37);
+      context.lineTo(28, 32);
+      context.lineTo(0, 17);
+      context.lineTo(-28, 32);
+      context.closePath();
+      context.fill();
+    },
+  },
+  getRotationBin: getCourseBin,
+  getBucketKey: (marker) => `${marker.userData.anchored ? "anchored" : "moving"}:${getCourseBin(marker)}`,
+});
+```
+
+当 `icon.coordinates !== "canvas"` 时，`Interactable` 会先把 context 平移到 atlas 中心；船只这类自己使用中心坐标绘制的图标不需要声明 `coordinates`。
+
+### SVG / 图片 Asset 图标
+
+asset 图标适合算力中心、BGP 观测站这类已有 SVG 的设施图标：
+
+```javascript
+const computeCenterIconLayer = createInteractableLayer({
+  id: "computeCenters",
+  objectType: "compute_center",
+  pointSize: 36,
+  atlasCellSize: 128,
+  icon: {
+    coordinates: "canvas",
+    colorable: false,
+    fitSize: 60,
+    glowBlur: 16,
+    getSource({ marker, item }) {
+      const siteType = marker?.userData?.site_type || item?.site_type || "gpu_cluster";
+      return COMPUTE_CENTER_ICON_SOURCES[siteType];
+    },
+    afterDraw(context, { marker, item }) {
+      if (marker?.userData?.is_estimated ?? item?.is_estimated) {
+        drawComputeCenterEstimatedBadge(context, true);
+      }
+    },
+  },
+});
+```
+
+使用 asset 时有几个约定：
+
+- SVG / 图片文件放在 `frontend/public/earth/assets/icons/`，以 `/earth/assets/icons/name.svg` 引用。
+- 原始 SVG 应尽量保留标准 `viewBox` 和路径，不要为了显示大小写死 transform。
+- 显示尺寸由 `icon.fitSize` 控制；它可以是数字、`{ width, height }`，也可以是函数。
+- `icon.colorable !== false` 且提供状态颜色时，公共层会先把 asset 画到临时 canvas，再用 `source-in` tint 成目标颜色。
+- 多色图片或不希望被 tint 的 SVG 应设置 `colorable: false`。
+
+## 生命周期
+
+常规加载流程：
+
+```javascript
+export async function loadExampleLayer(_scene, earth) {
+  clearExampleData(earth);
+
+  const markerData = await fetchExampleData();
+  await layer.preloadAssets(markerData);
+  layer.setData(markerData);
+  layer.attach(earth);
+  layer.setVisible(showExampleLayer);
+
+  return { totalCount: layer.getCount() };
+}
+```
+
+各方法职责：
+
+| 方法 | 说明 |
+| --- | --- |
+| `preloadAssets(items)` | 收集 normal / hover / locked 可能用到的 asset source，并用浏览器 `Image` 预加载。canvas draw 图标可跳过。 |
+| `setData(items)` | 清理旧 points，生成 marker，注册避让，按 bucket 重建 `THREE.Points`。 |
+| `attach(parent)` | 将图层 group 挂到 Earth root。 |
+| `setVisible(next)` | 控制 group、points 和 overlay 可见性。 |
+| `setMarkerState(marker, state)` | 设置 `normal` / `hover` 等状态并触发视觉状态失效。 |
+| `updateVisualState(focusType, focusObject, camera)` | 更新普通态 opacity / size，并刷新 hover / locked overlay。 |
+| `getPointerIntersections(options)` | 屏幕空间拾取，返回按像素距离排序的命中结果。 |
+| `clearData(parent)` | 注销避让、释放 geometry / material、清空 marker 并从 parent 移除 group。 |
+
+## Picking 接入
+
+`Interactable` 不依赖 Three.js 对 `Points` 的默认 raycast。主交互层只要把 Earth、camera、pointer 和命中半径传入：
+
+```javascript
+const intersects = getVesselPointerIntersections({
+  earth,
+  camera,
+  pointer,
+  radiusPx: 22,
+  width: window.innerWidth,
+  height: window.innerHeight,
+});
+```
+
+公共层会做这些事：
+
+1. 把相机位置转到 Earth local 坐标。
+2. 跳过背面 marker。
+3. 把 marker world position 投影到屏幕坐标。
+4. 用 `radiusPx` 做像素距离命中。
+5. 返回最近的候选对象。
+
+拖动地球、惯性旋转、hover 节流这些策略仍属于 `main.js`，因为它们和全局输入状态有关。
+
+## 同坐标避让
+
+避让默认开启，作用范围是所有通过 `createInteractableLayer()` 创建的图层。公共层会按经纬度或 `THREE.Vector3` 生成 `icon_avoidance_key`，同 key 的 marker 会沿地表切平面排成小圈。
+
+关键点：
+
+- `icon_base_position` 保留业务原始位置。
+- 避让只改渲染位置和 picking 位置，不改业务经纬度。
+- 单个 marker 回到原始位置时会直接使用 `altitudeOffset` 计算出的业务贴地位置。
+- 多个 marker 同坐标时，第一圈用 `avoidance.radius`，后续每圈加 `avoidance.step`。
+
+如果某个业务图层需要严格压在原始点位，可以显式关闭：
+
+```javascript
+createInteractableLayer({
+  id: "strict-layer",
+  avoidance: { enabled: false },
+});
+```
+
+## 业务动画边界
+
+`Interactable` 当前只负责图标本体和通用 hover / locked overlay。复杂动画仍放在业务模块里，但要跟随 Interactable marker 的位置：
+
+- BGP 事件扩散圈由 `bgp.js` 创建独立 ring sprite，并在每帧 `position.copy(marker.position)`。
+- BGP 观测站 halo、status core、coverage halo 和覆盖扇形由 `bgp.js` 管理，图标本体由 Interactable 管理。
+- 船只轨迹线仍由 `vessels.js` 管理，因为它依赖点击后额外加载的轨迹数据。
+
+这个边界能避免通用接口过早承载所有动画类型。后续如果多个图层复用同一类动画，再把它收进 Interactable 的 `animations` 扩展。
+
+## 新图层接入清单
+
+1. 在业务文件中准备 marker data，并保留必要的业务字段。
+2. 选择 icon 类型：canvas draw、SVG / 图片 asset，或 `getSource()` 动态选择。
+3. 配置 `pointSize`、`icon.fitSize`、`colors`、`opacity`、`stateScale`。
+4. 如果需要业务尺寸差异，提供 `getPointSizeMultiplier()`。
+5. 如果有旋转，提供 `getRotationBin()` 和稳定的 `getBucketKey()`。
+6. 加载时先 `preloadAssets()`，再 `setData()`、`attach()`、`setVisible()`。
+7. 在 `main.js` 接入 `getPointerIntersections()`，并复用现有 hover / locked 状态更新流程。
+8. 在图层样式索引和渲染顺序文档中记录 altitude、renderOrder、pointSize 和动画层级。
--- a/docs/technical/zh/earth-layer-style-reference.md
+++ b/docs/technical/zh/earth-layer-style-reference.md
@@ -146,21 +146,18 @@
 | 海缆线宽 | `CABLE_CONFIG.line.lineWidth` | `1` | `LineBasicMaterial.linewidth` |
 | 海缆透明度 | `CABLE_CONFIG.line.opacity` | `1.0` | 海缆线 opacity |
 | 海缆 renderOrder | `CABLE_CONFIG.line.renderOrder` | `1` | 海缆线层级 |
-| 登陆点半径偏移 | `CABLE_CONFIG.landingPoint.altitudeOffset` | `0.48` | 对齐算力中心贴地表 marker 高度 |
-| 登陆点 icon 贴图尺寸 | `CABLE_CONFIG.landingPoint.textureSize` | `256` | canvas 渲染 EPS 参考图的实心 map-pin，中间圆孔透明镂空 |
-| 登陆点 icon 宽高比 | `CABLE_CONFIG.landingPoint.iconAspectRatio` | `0.82` | `Sprite.scale.x = height * aspect` |
-| 登陆点 icon 锚点 | `CABLE_CONFIG.landingPoint.anchorX / anchorY` | `0.52 / 0.276` | `Sprite.center`，将 pin 下端点对齐登陆点经纬度 |
-| 登陆点基础缩放 | `CABLE_CONFIG.landingPoint.baseScale` | `12` | 对齐算力中心等地表 icon 的 sprite 高度 |
+| 登陆点半径偏移 | `CABLE_CONFIG.landingPoint.altitudeOffset` | `0.2` | 与海缆线同层贴地，避免凌空 |
+| 登陆点 sprite 高度 | local `LANDING_POINT_SPRITE_HEIGHT` | `3` | `THREE.Sprite` 基准高度 |
+| 登陆点缩放参考 FOV | local `LANDING_POINT_SIZE_REFERENCE_FOV` | `75` | 与当前 Earth 相机 FOV 一致 |
+| 登陆点缩放下限 | local `LANDING_POINT_SIZE_SCALE_MIN` | `0.36` | 地球放到最大时的最小倍率；`3 * 0.36 = 1.08` |
+| 登陆点缩放上限 | local `LANDING_POINT_SIZE_SCALE_MAX` | `3` | 远距离时的最大倍率；当前最小缩放约只能到 `2.50` |
+| 登陆点 atlas 尺寸 | local `LANDING_POINT_ATLAS_CELL_SIZE` | `128` | canvas 扁平立体球纹理尺寸 |
 | 登陆点颜色 | `CABLE_CONFIG.landingPoint.color` | `0xffaa00` | `SpriteMaterial.color` |
-| 登陆点 emissive | `CABLE_CONFIG.landingPoint.emissive` | `0x442200` | 兼容旧球体材质；sprite 不使用 |
-| 登陆点 emissive 强度 | `CABLE_CONFIG.landingPoint.emissiveIntensity` | `0.5` | 兼容旧球体材质；sprite 不使用 |
 | 登陆点透明度 | `CABLE_CONFIG.landingPoint.opacity` | `1.0` | `SpriteMaterial.opacity` |
-| 登陆点 renderOrder | `CABLE_CONFIG.landingPoint.renderOrder` | `4.5` | 对齐算力中心地表设施层级 |
+| 登陆点 renderOrder | `CABLE_CONFIG.landingPoint.renderOrder` | `1` | 与海缆线同层；`depthTest: false` 保持球体完整，背面通过相机到球心的球体遮挡判断隐藏 |
 | 登陆点 dim 亮度系数 | `landingPointVisual.dimBrightness` | `0.62` | dim 状态颜色乘数 |
 | 相关登陆点高亮 opacity | `landingPointVisual.related.opacityBase / opacityPulse` | `0.8 / 0.2` | 高亮脉冲 |
 | 非相关登陆点颜色 | `landingPointVisual.dimmed.colorRGB` | `{ r: 180, g: 116, b: 28 }` | dim 状态颜色，避免黑色基座透出成暗洞 |
-| 非相关登陆点 emissive | `landingPointVisual.dimmed.emissive` | `0x3a2200` | dim 状态弱琥珀自发光 |
-| 非相关登陆点 emissive 强度 | `landingPointVisual.dimmed.emissiveIntensity` | `0.18` | dim 状态弱发光强度 |
 | 非相关登陆点 opacity | `landingPointVisual.dimmed.opacity` | `0.78` | dim 状态透明度，不再用低 alpha 混黑底 |

 ## 卫星、轨迹和 footprint
@@ -212,11 +209,13 @@ AIS 船只普通态使用批量 `THREE.Points`，不是逐船 `THREE.Sprite`。
 | 正式名称 | 变量名 | 当前值 | 使用位置 / 说明 |
 | --- | --- | --- | --- |
 | 算力中心半径偏移 | `COMPUTE_CENTER_CONFIG.altitudeOffset` | `0.48` | marker 位置 |
-| 算力中心基础透明度 | `COMPUTE_CENTER_CONFIG.marker.baseOpacity` | `0.88` | `SpriteMaterial.opacity` |
-| 超算 marker 缩放 | `COMPUTE_CENTER_CONFIG.marker.supercomputerScale` | `12` | 超算 marker |
-| GPU 集群 marker 缩放 | `COMPUTE_CENTER_CONFIG.marker.gpuClusterScale` | `12` | GPU marker |
-| hover 缩放 | `COMPUTE_CENTER_CONFIG.marker.hoverScale` | `1.16` | hover 状态 |
-| locked 缩放 | `COMPUTE_CENTER_CONFIG.marker.lockedScale` | `1.22` | locked 状态 |
+| 算力中心点像素尺寸 | local `COMPUTE_CENTER_POINT_SIZE` | `36` | `Interactable` 普通 marker 与 hover / locked overlay 共享基准尺寸 |
+| 算力中心 asset fit size | local `COMPUTE_CENTER_ICON_FIT_SIZE` | `60` | SVG asset 在 `128x128` atlas canvas 内的最大绘制尺寸，由 `icon.fitSize` 控制 |
+| 算力中心基础透明度 | `COMPUTE_CENTER_CONFIG.marker.baseOpacity` | `0.88` | 普通 `PointsMaterial.opacity` |
+| 超算 marker 缩放 | `COMPUTE_CENTER_CONFIG.marker.supercomputerScale` | `12` | 旧 Sprite 缩放参数；当前 Interactable 路径不再直接使用 |
+| GPU 集群 marker 缩放 | `COMPUTE_CENTER_CONFIG.marker.gpuClusterScale` | `12` | 旧 Sprite 缩放参数；当前 Interactable 路径不再直接使用 |
+| hover 缩放 | `COMPUTE_CENTER_CONFIG.marker.hoverScale` | `1.16` | hover overlay 尺寸倍率 |
+| locked 缩放 | `COMPUTE_CENTER_CONFIG.marker.lockedScale` | `1.22` | locked overlay 尺寸倍率，并叠加 pulse |
 | dimmed 缩放 / 透明度 | `dimmedScale / dimmedOpacity` | `0.82 / 0.34` | dim 状态 |
 | 超算颜色 | `COMPUTE_CENTER_CONFIG.colors.supercomputer` | `"#38bdf8"` | marker texture |
 | GPU 集群颜色 | `COMPUTE_CENTER_CONFIG.colors.gpu_cluster` | `"#2dd4bf"` | marker texture |
@@ -227,12 +226,16 @@ AIS 船只普通态使用批量 `THREE.Points`，不是逐船 `THREE.Sprite`。

 | 正式名称 | 变量名 | 当前值 | 使用位置 / 说明 |
 | --- | --- | --- | --- |
-| BGP 事件半径偏移 | `BGP_CONFIG.altitudeOffset` | `2.1` | anomaly marker |
-| BGP collector 半径偏移 | `BGP_CONFIG.collectorAltitudeOffset` | `1.6` | collector marker |
-| 事件基础缩放 | `BGP_CONFIG.marker.eventBaseScale` | `6.2` | anomaly sprite |
-| collector 基础缩放 | `BGP_CONFIG.marker.collectorBaseScale` | `7.4` | collector plane |
+| BGP 事件半径偏移 | `BGP_CONFIG.altitudeOffset` | `0.48` | BGP 事件 Interactable marker |
+| BGP collector 半径偏移 | `BGP_CONFIG.collectorAltitudeOffset` | `0.2` | BGP 观测站 Interactable marker，与船只同层贴地 |
+| BGP 事件点像素尺寸 | local `BGP_EVENT_POINT_SIZE` | `34` | 事件 icon 的 Interactable 基准尺寸，按严重级别通过 `getPointSizeMultiplier()` 调整 |
+| BGP 事件符号绘制尺寸 | local `BGP_EVENT_SYMBOL_SIZE` | `60` | 事件 canvas 符号在 `128x128` atlas 中的绘制尺寸 |
+| BGP collector 点像素尺寸 | local `BGP_COLLECTOR_POINT_SIZE` | `36` | 观测站 Interactable 基准尺寸，按活跃度通过 `getPointSizeMultiplier()` 调整 |
+| BGP collector asset fit size | local `BGP_COLLECTOR_ICON_FIT_SIZE` | `60` | `bgp-broadcast-pin.svg` 在 atlas canvas 内的最大绘制尺寸 |
+| 事件基础缩放 | `BGP_CONFIG.marker.eventBaseScale` | `6.2` | 事件扩散圈锚点 |
+| collector 基础缩放 | `BGP_CONFIG.marker.collectorBaseScale` | `7.4` | 观测站 halo / 覆盖动画锚点 |
 | hover / dim 缩放 | `hoverScale / dimmedScale` | `1.16 / 0.92` | 交互状态 |
-| 普通事件透明度 | `BGP_CONFIG.opacity.normal` | `0.78` | anomaly sprite |
+| 普通事件透明度 | `BGP_CONFIG.opacity.normal` | `0.78` | BGP 事件 Interactable 普通态 |
 | hover 透明度 | `BGP_CONFIG.opacity.hover` | `1.0` | hover 状态 |
 | dimmed 透明度 | `BGP_CONFIG.opacity.dimmed` | `0.24` | dim 状态 |
 | collector 透明度 | `BGP_CONFIG.opacity.collector` | `0.62` | collector 状态 |
@@ -244,8 +247,8 @@ AIS 船只普通态使用批量 `THREE.Points`，不是逐船 `THREE.Sprite`。
 | region 色 | `BGP_CONFIG.regionColor` | `0x2dd4bf` | 区域覆盖 |
 | BGP ring 缩放 | `BGP_CONFIG.ring.scaleA / scaleB` | `2.5 / 3.4` | anomaly ring |
 | BGP ring 透明度 | `BGP_CONFIG.ring.opacity` | `0.5` | anomaly ring |
-| collector marker renderOrder | inline | `3` | `marker.renderOrder` |
-| anomaly marker renderOrder | inline | `5` normal, `7` active | `marker.renderOrder` |
+| collector marker renderOrder | local `BGP_COLLECTOR_RENDER_ORDER` | `4.4` | 观测站主图标，与船只同层 |
+| anomaly marker renderOrder | local `BGP_EVENT_RENDER_ORDER` | `4.5` | BGP 事件主图标，与算力中心同层 |

 ## 天体与星空

--- a/docs/technical/zh/earth-render-layer-order.md
+++ b/docs/technical/zh/earth-render-layer-order.md
@@ -21,17 +21,17 @@
 | 0.86 | 海陆基座填充 | `country-boundaries.js` | `landAltitudeOffset`; 海洋 `#010609`，陆地 `#080f1b` | 禁用 raycast | 即使国界线关闭，基座地图仍保持可用。 |
 | 0.96 | 高清 Earth 材质 | `earth.js` | `textureOverlayAltitudeOffset` | 可见时作为地表拾取目标 | 高清材质始终压过海陆基座填充。 |
 | 1 | 大气辉光和云图 | `earth.js` | 大气 / 云层球 | 不走普通对象选择路径 | 云图由“大气云图”图层开关控制。 |
-| 1 | 海缆 | `cables.js` | `CABLE_CONFIG.line.renderOrder` | 海缆拾取路径 | 保持现有海缆层级。 |
+| 1 | 海缆 / 登陆点 | `cables.js` | 海缆线和登陆点都使用 `renderOrder = 1`；半径偏移都为 `0.2`；登陆点是专用 `THREE.Sprite` 黄色扁平球 | 海缆走海缆拾取路径；登陆点 `depthTest: false` 保持球体完整，并用相机到球心的球体遮挡判断避免背面穿透 | 登陆点和海缆同层贴地，避免地表设施层的凌空感。 |
 | 1.2 | 真实地形 | `earth.js`, `terrain.js` | `TERRAIN_CONFIG.baseRadiusOffset` 加地形位移 | 禁用 raycast | 地形压过高清材质；高清材质关闭时临时隐藏，重新开启后恢复原状态。 |
 | 2.05 | 经纬线 | `earth.js` | `CONFIG.earthRadius + 0.14` | 禁用 raycast | 低透明度显示在高清材质上。 |
 | 2.2 | 国界线 | `country-boundaries.js` | `lineAltitudeOffset = 0.115` | `depthTest: true`，禁用 raycast | 略高于高清材质 `0.10`，低于地形基准 `0.16`，减少悬浮感；地形 `depthWrite: false`，所以地形开启时仍可见。 |
 | 2.29 | 国界 hover 光晕 | `country-boundaries.js` | hover 半径加 glow 偏移 | `depthTest: false`，禁用 raycast | 用 additive 光晕增强交界边和地形开启时的 hover 可见性。 |
 | 2.3 | 国界 hover 实线 | `country-boundaries.js` | `hoverAltitudeOffset = 0.14` | `depthTest: false`，禁用 raycast | 霓虹红橘 hover 线；中国和中国（台湾）共享高亮组。 |
 | 3 | 卫星 footprint 填充 | `satellites.js` | `GROUND_FOOTPRINT_RENDER_ORDER` | depth-tested，Group renderOrder 保持 0 | Footprint 在国界线之上，但在算力中心和卫星之下。 |
-| 3-5 | BGP 标记和覆盖层 | `bgp.js` | 各 marker 自身 renderOrder | BGP 拾取路径 | 保持现有 BGP 视觉层级。 |
+| 3-4.5 | BGP 观测站、事件扩散圈和事件 marker | `bgp.js`, `interactable.js` | BGP 观测站和事件 marker 均使用 `Interactable` 批量 `THREE.Points`；事件 marker 使用 `BGP_EVENT_RENDER_ORDER = 4.5`；观测站主图标使用 `BGP_COLLECTOR_RENDER_ORDER = 4.4` 和 `BGP_CONFIG.collectorAltitudeOffset = 0.2`；事件 overlay 进入 `bgp-event-overlay-layer`；观测站 halo 和覆盖扇形进入 `bgp-collector-radar-layer` | BGP 事件和观测站都通过 `Interactable` 屏幕空间 picking，并参与同坐标避让 | BGP 观测站主图标与船只同层；BGP 事件与算力中心同层；向外扩散圈、观测站雷达/覆盖动画继续由 BGP 业务逻辑驱动。 |
 | 4.3 | AIS 船只轨迹线 | `vessels.js` | `VESSEL_RENDER_ORDER - 0.1`；`CONFIG.earthRadius + VESSEL_CONFIG.track.altitudeOffset` | 跟随船只显隐，不单独参与拾取 | 选中船只后显示最近轨迹，低于船只 marker。 |
-| 4.4 | AIS 船只 marker | `vessels.js` | `VESSEL_RENDER_ORDER`；`CONFIG.earthRadius + VESSEL_CONFIG.altitudeOffset`；普通 marker 为分桶 `THREE.Points`，hover / locked 为单点 `THREE.Points` overlay | `depthTest: true`；`main.js` 使用屏幕空间 picking，只取正面 marker | 航行船只用三角点纹理，停泊/低速用圆点；普通态无 glow，交互态叠加同尺寸 glow；低于算力中心 `4.5`。 |
-| 4.5 | 算力中心 | `compute-centers.js` | `COMPUTE_CENTER_RENDER_ORDER` | 算力中心拾取路径 | 地表设施，保持在卫星下方。 |
+| 4.4 | AIS 船只 marker | `vessels.js`, `interactable.js` | `VESSEL_RENDER_ORDER`；业务高度为 `CONFIG.earthRadius + VESSEL_CONFIG.altitudeOffset`；普通 marker 为分桶 `THREE.Points`，hover / locked 为单点 `THREE.Points` overlay | `depthTest: true`；`main.js` 使用屏幕空间 picking，只取正面 marker；参与 Interactable 同坐标避让 | 航行船只用三角点纹理，停泊/低速用圆点；普通态无 glow，交互态叠加同尺寸 glow；低于算力中心 `4.5`。 |
+| 4.5 | 算力中心 | `compute-centers.js`, `interactable.js` | 使用 `COMPUTE_CENTER_RENDER_ORDER` 并由 `Interactable` 绘制 | 通过 `Interactable` 屏幕空间 picking，参与同坐标避让 | 地表设施层，保持在卫星下方。登陆点已下沉到海缆层。 |
 | 5 | 卫星背景点 | `satellites.js` | 固定 renderOrder | 屏幕空间卫星拾取 | 位于卫星点下方。 |
 | 6 | 卫星点 | `satellites.js` | 固定 renderOrder | 屏幕空间卫星拾取 | 卫星点压过 footprint 和算力中心。 |
 | 12+ | 卫星锁定 ring、halo、预测轨道 | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` 及偏移 | 卫星覆盖层路径 | 用于选中 / 锁定卫星强调。 |