planet/docs/deprecated/earth-surface-hover-info-plan.md

Earth Surface Hover Info Plan

Status: Implemented.

Goal

为 Earth 桌面和 compact 鼠标地表 hover 增加可配置的提示内容，让用户可以选择只看国家信息、只看位置数据，或同时查看国家和经纬海拔。

当前地表 hover 已经具备两类信息：

• 命中国家时显示国家、ISO、大洲，并高亮国界。
• 未命中国家时显示纬度、经度、海拔。

新方案把这两类信息合并成一个清晰的设置项：悬停提示。

User-facing behavior

设置项放在桌面设置和移动端设置的 视图 区，使用分段控件：

• 国家：陆地命中国家时显示国家名、ISO、大洲；太平洋等海洋区域不显示地表 tooltip。
• 位置：陆地和海洋都显示纬度、经度、海拔；不触发国家 tooltip 和国家边界 hover 高亮。
• 完整：陆地命中国家时显示国家信息和纬度、经度、海拔；海洋区域显示纬度、经度、海拔。

默认值为 完整，因为它保留现有国家识别价值，同时满足 hover 时查看经纬海拔的需求。

海洋在 国家 模式下保持沉默，而不是显示大洋名称。原因是当前项目没有海域/大洋边界数据源；用经纬度粗判太平洋、大西洋等范围容易产生误导。如果用户需要海洋位置，使用 位置 或 完整。

Implementation plan

Settings state

在 frontend/public/earth/js/constants.js 增加：

export const SURFACE_HOVER_INFO_MODES = {
  COUNTRY: "country",
  POSITION: "position",
  FULL: "full",
};

export const DEFAULT_SURFACE_HOVER_INFO_MODE =
  SURFACE_HOVER_INFO_MODES.FULL;

在 frontend/public/earth/js/controls.js：

• 将 EARTH_SETTINGS_VERSION 从 10 升到 11。
• 在 shared settings 中新增 surfaceHoverInfoMode。
• 新增导出：
  • getSurfaceHoverInfoMode()
  • setSurfaceHoverInfoMode(mode, { persist, suppressStatus })
• normalize 时只接受 country | position | full，否则回退到 full。
• reset settings 后恢复为 full。

Settings UI

在桌面设置 视图 区和移动端设置 视图 区加入同一组按钮：

<button data-surface-hover-info-mode="country">国家</button>
<button data-surface-hover-info-mode="position">位置</button>
<button data-surface-hover-info-mode="full">完整</button>

控件同步规则沿用现有卫星显示风格和巡航模块的模式：

• 当前模式按钮添加 is-active。
• 当前模式按钮设置 aria-pressed="true"。
• 切换后保存到 Earth settings localStorage。

Hover tooltip logic

在 frontend/public/earth/js/main.js 的地表 hover 分支中读取 getSurfaceHoverInfoMode()，统一构造 tooltip。

行为规则：

• 如果没有命中地球：清除国家 hover 并隐藏 tooltip。
• position：
  • 调用 clearCountryBoundaryHover()。
  • 显示 纬度 / 经度 / 海拔。
• country：
  • 仅当国界图层开启并命中国家时显示国家 tooltip 和国界 hover。
  • 海洋、国界图层关闭、未加载国界数据时隐藏地表 tooltip。
• full：
  • 国界图层开启且命中国家时显示国家信息加位置信息。
  • 未命中国家或国界图层关闭时显示位置信息。

海拔继续使用 sampleElevationAt(lat, lon)。暂无采样时显示 —，不因 hover 主动加载地形瓦片。

Acceptance criteria

1. 完整 模式下，hover 陆地显示国家信息和经纬海拔，hover 海洋显示经纬海拔。
2. 国家 模式下，hover 陆地显示国家信息，hover 太平洋等海洋不显示地表 tooltip。
3. 位置 模式下，hover 陆地和海洋都显示经纬海拔，国家边界不高亮。
4. 关闭国界图层后，完整 模式回退为只显示位置。
5. 船只、BGP、算力中心、海缆等对象 hover tooltip 优先级不变。
6. 移动端中心国家高亮不受这个鼠标 hover 设置影响。
7. 设置刷新后保持，重置后恢复为 完整。

Verification

• 在 frontend 下运行 /home/ray/.bun/bin/bun run build。
• 手动验证三种模式的陆地和海洋 hover 行为。
• 验证设置持久化和重置。
• 验证对象 hover 仍优先于地表 hover。