release: bump version to 0.56.0

2026-05-13 18:21:03 +08:00
parent 39854b9983
commit f14ff6ec0f
46 changed files with 1589 additions and 684 deletions
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,6 +8,22 @@ This project follows the repository versioning rule:
 - `improvement` -> `+0.0.1`（bugfix + 小功能混合）
 - `bugfix` -> `+0.0.1`

+## [0.56.0] — 2026-05-13
+
+Released: 2026-05-13
+
+### Highlights
+- 修复 Earth 卫星 SGP4 坐标口径，当前点/短尾迹使用地固坐标，锁定预测轨道使用固定地球姿态下的闭合惯性轨道。
+- 优化真实高度压缩显示上限，将高轨显示控制在地球半径外约四分之一，保持 GEO/MEO/LEO 分层同时避免轨迹过远。
+- 统一 BGP 光晕与图标色调，并更新超算中心建筑图标和 Earth 新闻/HUD 面板体验。
+
+### Added / Fixed / Improved
+- 修正卫星详情卡近地点/远地点高度计算，避免把轨道半径误显示为离地高度。
+- 调整 BGP event / collector halo 的浅色派生规则，使红色事件、橙色活跃观测站和蓝色 idle 观测站保持各自色相。
+- 补充中英文用户手册、FAQ、Earth frontend context、render order、layer style reference 和相关计划文档。
+
+---
+
 ## [0.55.0] — 2026-05-13

 Released: 2026-05-13
--- a/docs/plans/README.md
+++ b/docs/plans/README.md
@@ -19,7 +19,7 @@
 - [earth-mobile-drawer-ui-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-mobile-drawer-ui-plan.md)
 - [earth-compute-center-bgp-style-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-compute-center-bgp-style-plan.md)
 - [earth-renderer-architecture-separation-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-renderer-architecture-separation-plan.md)
- [earth-country-boundary-overlay-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-country-boundary-overlay-plan.md)
+- [Earth 高精度国界静态瓦片计划](/home/ray/dev/linkong/planet/docs/plans/earth-high-precision-boundary-tiles-plan.md)
 - [earth-predicted-orbit-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-predicted-orbit-plan.md)
 - [earth-webgl-instancing-satellites-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-webgl-instancing-satellites-plan.md)
 - [earth-real-terrain-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-real-terrain-plan.md)
--- a/docs/plans/datasource-custom-api-mapping-plan.md
+++ b/docs/plans/datasource-custom-api-mapping-plan.md
@@ -13,7 +13,7 @@
 | 采集时是否调用 LLM | 不调用；采集链路必须确定性、可审计、可复现 |
 | 自定义数据如何进入 Earth | 必须映射到已支持的目标 schema，或先进入通用数据沉淀 |
 | 外部凭证放置位置 | Settings / 外部集成统一管理 provider token；DataSources 引用 provider profile |
-| TimescaleDB | 放入 TODO；高频时序数据稳定后再评估迁移 |
+| TimescaleDB | 高频时序数据稳定后再评估迁移 |

 ---

@@ -57,7 +57,7 @@ flowchart LR
 | schema | 用途 | Earth 可视化 |
 |-------|------|-------------|
 | `vessel_ais` | 船只 AIS 位置、航速、航向、MMSI 等 | 进入船舶图层 |
-| `geo_points` | 通用点位数据，包含经纬度、名称、类型、时间 | 进入通用 geo layer（TODO） |
+| `geo_points` | 通用点位数据，包含经纬度、名称、类型、时间 | 未来进入通用 geo layer |
 | `news_events` | 新闻/事件类数据，带时间、地点、摘要、来源 | 复用新闻/事件链路 |
 | `compute_centers` | 算力中心、机房、数据中心数据 | 复用算力中心图层 |
 | `generic_records` | 未知结构化数据沉淀 | 不直接展示 |
@@ -294,7 +294,7 @@ PostgreSQL 可以承载当前规模的采集、关系查询、JSONB 沉淀和基
 - 查询模式还没稳定。
 - 需要快速迭代 schema 与 mapping。

-### TODO：TimescaleDB
+### TimescaleDB 后续评估

 以下条件满足后，再评估 TimescaleDB：

@@ -324,7 +324,7 @@ PostgreSQL 可以承载当前规模的采集、关系查询、JSONB 沉淀和基
 - Settings 中保存 provider credentials。
 - API 返回配置时必须 mask secret。
 - LLM prompt 只能包含脱敏 sample 和 schema 说明。
- 后续 TODO：引入字段级加密或 KMS。
+- 后续可引入字段级加密或 KMS。

 ### Mapping 治理

--- a/docs/plans/earth-high-precision-boundary-tiles-plan.md
+++ b/docs/plans/earth-high-precision-boundary-tiles-plan.md
@@ -0,0 +1,132 @@
+# Earth High Precision Boundary Tiles Plan
+
+## Status
+
+Planning revised after visual review. The previous hand-authored China claim-line / point-buffer approach is rejected and must not be implemented.
+
+Implemented separately:
+
+- 地表 hover 三模式已实现。
+
+Still planned:
+
+- 权威 China POV 数据包。
+- OSM / coastline 高精度离线构建。
+- 版本化静态矢量瓦片输出。
+- 前端 bbox/tile/LRU 高精度加载器。
+
+## Summary
+
+Earth 国界线目标从“明显提升”升级为 **最高精度档按真实地图源一比一还原**：
+
+- 高缩放时不能使用当前 `countries-admin0.min.geojson` 这种低精度简化线。
+- 最高 tile zoom 必须忠实保留选定权威矢量源的原始折点，不做视觉平滑，不做人工凭感觉补线。
+- 藏南、阿克赛钦等争议陆地直接作为中国国家面的一部分表达；hover 只显示普通 `中国 / CHN`，不显示特殊区域名。
+- 九段线 / 十段线必须来自官方标准地图口径或经地理配准校核后的权威矢量数据；不能手工目测画线，不能把马来西亚、菲律宾等周边陆地或近岸底盘划入中国面。
+
+方案仍采用 **离线构建 + 静态矢量瓦片**。低缩放加载简化 base line；高缩放按当前视野 bbox 加载高精度 boundary tiles。第一版不使用 Redis，依靠 Nginx 静态服务、浏览器 HTTP cache 和前端 LRU。
+
+## Data Source and Policy
+
+- 基础陆地国界使用 OSM `boundary=administrative` + `admin_level=2`，并补充高精度 coastline，避免只靠粗糙国家面导致海岸线缺失。
+- China POV 覆盖数据必须独立成包，构建时优先级高于 OSM 原始归属：
+  - 藏南 union 到中国面，同时从印度面 subtract。
+  - 阿克赛钦 union 到中国面，同时从相关邻接面 subtract。
+  - 台湾、澎湖、钓鱼岛及附属岛屿、赤尾屿、东沙、西沙、中沙、南沙等作为中国国家面/岛礁面的一部分进入 hover index。
+  - 岛礁很小时可有最小可交互面，但 tooltip 仍是 `中国 / CHN`，不展示“某特殊区域归属”标签。
+- 九段线 / 十段线是独立 maritime claim line 图层：
+  - 只渲染 dashed line，不参与国家陆地面。
+  - 不用于吞并周边国家陆地或近岸水域。
+  - 坐标必须来自官方标准地图、权威矢量数据，或从官方示意图配准后人工复核，不接受手工猜测坐标。
+- 必须保留 OSM 数据归因：`© OpenStreetMap contributors, ODbL`。
+
+## Precision Requirements
+
+- 最高精度档的验收口径是 **source-faithful**，不是“看起来更细”：
+  - 对高精度源线，最高 zoom tile 不允许 Douglas-Peucker 简化。
+  - 坐标量化精度至少保留到 `1e-5` 度级别，构建时不得把经纬度粗暴四舍五入到低精度。
+  - 球面渲染只允许 densify 长边来贴合地球曲率；不允许 CatmullRom、Bezier 或任何会改变边界走向的平滑。
+  - 海岸/边界红框类区域必须与源地图折线逐点对齐；若有偏差，只能追溯并替换数据源，不能靠渲染平滑掩盖。
+- 低缩放允许简化，但必须有误差预算：
+  - base line 只服务远景识别。
+  - 中 zoom tile 可简化到屏幕误差低于 `0.5px`。
+  - 最高 zoom tile 使用无简化或近零误差版本。
+
+## Implementation Plan
+
+### 1. Data pipeline
+
+新增边界构建脚本，使用 `/home/ray/.local/bin/uv` 运行：
+
+1. 读取 OSM PBF 或预处理后的 admin-0 边界 / coastline GeoJSON。
+2. 读取 China POV override package。
+3. 使用可靠几何库做 union / difference / validity repair，禁止手写 polygon overlay。
+4. 生成中国国家面时直接合并藏南、阿克赛钦和相关岛礁；从相邻国家面扣除同一区域。
+5. 单独读取官方口径九段线 / 十段线矢量，生成 claim-line tiles。
+6. 输出：
+   - 低精度 global base line。
+   - 无简化 high-precision hover polygon index。
+   - 高精度静态瓦片：`frontend/public/earth/data/boundaries/v1/{z}/{x}/{y}.geojson`。
+   - 海上断续线瓦片：`frontend/public/earth/data/boundaries/v1/china-claims/{z}/{x}/{y}.geojson`。
+   - manifest，记录数据源、覆盖规则版本、构建时间、简化误差和 attribution。
+
+### 2. Tile levels and size budget
+
+- Earth zoom `< 1.6`：只显示 global base line 和低精度 claim line。
+- Earth zoom `1.6-2.8`：加载 tile zoom `4-5`。
+- Earth zoom `2.8-4.0`：加载 tile zoom `6-7`。
+- Earth zoom `> 4.0`：加载 tile zoom `8-10`，使用最高精度无简化折线。
+- 单 tile gzip 目标 `20-80KB`，但最高精度档优先保证几何真实性；若超限，优先提高 tile zoom 或拆 tile，而不是简化真实线。
+
+### 3. Frontend loading model
+
+`country-boundaries.js` 拆成 base layer、tile layer 和 China claim layer：
+
+- 首屏加载 base line + hover index，不阻塞 Earth 初始化。
+- 高缩放时根据 camera 可见范围计算经纬 bbox，再转换为 Web Mercator tile keys。
+- bbox 由屏幕中心、四角和边中点 raycast 得到，并扩张 `10-20%` 作为预取范围。
+- 处理反经线，必要时拆成两个 bbox。
+- 视野变化请求 debounce `150-250ms`。
+- 拖拽/惯性旋转中不每帧请求；缩放档或 tile key 集合没变时不刷新。
+- 加载当前视野 tile，并预取一圈邻接 tile。
+- base line 在高精度 tile 到达后降低 opacity，避免双线。
+
+### 4. Caching and memory control
+
+- 前端维护 `tileCache`、`inFlightTiles` 和 LRU 使用顺序。
+- tile cache 上限建议 `120-180` 个 tile；超过后释放最旧 tile 的 `BufferGeometry`。
+- Nginx 为 `/earth/data/boundaries/` 设置长缓存：
+  - `Cache-Control: public, max-age=31536000, immutable`
+  - gzip 包含 JSON。
+- tile URL 包含版本目录，例如 `v1`；数据更新时改版本目录破浏览器缓存。
+- 第一版不使用 Redis。只有改成动态裁剪 API、多 POV 同 URL、或压测证明静态服务成为瓶颈时再考虑 Redis。
+
+## Acceptance Criteria
+
+1. 最高 zoom 的海岸线和国界线与选定源地图逐点一致，不再只是“明显提升”。
+2. 红框类海岸/边界细节在最高 zoom 下不能出现肉眼可见的低精度折线、直线切边或圆滑失真。
+3. 藏南、阿克赛钦 hover 命中普通 `中国 / CHN`；印度或其他邻接国家不再包含这些区域。
+4. 钓鱼岛、赤尾屿、南海诸岛代表点 hover 命中普通 `中国 / CHN`。
+5. 九段线 / 十段线位置与权威来源一致，不压入马来西亚、菲律宾等周边陆地或错误包围近岸底盘。
+6. 首屏不加载全球超高精度整包。
+7. 高缩放只请求当前视野附近 tile，快速旋转不会出现请求风暴。
+8. 回到已访问区域命中前端 cache 或浏览器 cache。
+9. 国界图层开关、hover 高亮、移动端中心国家高亮、悬停提示三模式保持可用。
+
+## Verification
+
+- 构建阶段：
+  - 几何 validity check 全通过。
+  - China POV 代表点测试全部返回 `CHN`。
+  - 相邻国家代表点不得被 China override 误吞。
+  - 最高 zoom tile 抽样与源数据做坐标级 diff，确认未简化。
+- 前端阶段：
+  - 在 `frontend` 运行 `/home/ray/.bun/bin/bun run build`。
+  - 浏览器 DevTools 验证低缩放无高精度 tile 请求，高缩放请求数量受控，重复视野走 cache。
+  - 用截图中的红框区域、南海断续线、藏南、钓鱼岛、赤尾屿、南海诸岛做手动视觉验收。
+
+## Sources and Assumptions
+
+- 产品默认采用中国标准地图/公开地图合规口径；若后续支持多 POV，必须通过版本化数据目录隔离，不能让同一 URL 返回不同政治口径。
+- 当前仓库没有足够权威和足够精细的 China POV / 九段线矢量源，因此不能直接凭现有低精度 GeoJSON 完成“一比一还原”。
+- 实施前必须先引入或生成可审计的高精度源数据包；没有源数据时，只能实现加载框架，不能伪造边界。
--- a/docs/plans/earth-interactable-layer-plan.md
+++ b/docs/plans/earth-interactable-layer-plan.md
@@ -273,7 +273,7 @@ hover / locked 使用少量 overlay：

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

 ### Phase 4：形成 Earth 图标层规范
--- a/docs/plans/earth-surface-hover-info-plan.md
+++ b/docs/plans/earth-surface-hover-info-plan.md
@@ -0,0 +1,105 @@
+# 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` 增加：
+
+```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
+
+在桌面设置 `视图` 区和移动端设置 `视图` 区加入同一组按钮：
+
+```html
+<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。
--- a/docs/plans/earth-vessel-tracking-plan.md
+++ b/docs/plans/earth-vessel-tracking-plan.md
@@ -1,14 +1,14 @@
 # 实时船只监控系统 — 实施计划

-**状态**：规划中
+**状态**：历史计划；实时 AIS 与聚合接口已由 [AIS 多源采集、冲突记录与聚合接口计划](/home/ray/dev/linkong/planet/docs/plans/earth-vessel-ais-aggregation-plan.md) 接管
 **创建日期**：2026-04-27
-**优先数据源**：BarentsWatch AIS（免费但需要 OAuth client credentials）→ AISHub / MarineTraffic（TODO，付费）
+**优先数据源**：BarentsWatch AIS（免费但需要 OAuth client credentials）→ AISStream realtime；AISHub / MarineTraffic 保留为付费备选

 ## 已确认决策

 | 项目 | 决策 |
 |-----|------|
-| 数据源 | BarentsWatch 先行；AISHub / MarineTraffic TODO |
+| 数据源 | BarentsWatch 先行；AISStream realtime 已成为全球实时补充；AISHub / MarineTraffic 保留为付费备选 |
 | 船只规模 | BarentsWatch 阶段全部显示；全球数据接入后按需加船型过滤（默认 Cargo + Tanker + Passenger） |
 | 更新频率 | 准实时：前端 5 分钟轮询，后端 Collector 每分钟拉取写库 |
 | 历史轨迹 | 保留（`vessel_position` 表保留 24h，后期按需扩展） |
@@ -23,9 +23,9 @@
 | 来源类型 | 典型服务 | 覆盖范围 | 成本 | 状态 |
 |---------|---------|---------|------|------|
 | **BarentsWatch AIS API** | live.ais.barentswatch.no | 挪威海域实时 | 免费，需要 AIS API client credentials | **当前使用** |
-| **AISHub** | aishub.net | 全球实时 | 免费/小额 | TODO：付费接入 |
-| **MarineTraffic API** | marinetraffic.com | 全球实时 | $50–$500/月 | TODO：评估 tier |
-| **VesselFinder API** | vesselfinder.com | 全球实时 | $50–$300/月 | TODO：备选 |
+| **AISHub** | aishub.net | 全球实时 | 免费/小额 | 付费备选 |
+| **MarineTraffic API** | marinetraffic.com | 全球实时 | $50–$500/月 | 待评估 tier |
+| **VesselFinder API** | vesselfinder.com | 全球实时 | $50–$300/月 | 备选 |
 | **自建 SDR 接收** | RTL-SDR + AIS-catcher | 仅本地 30–50km | 硬件 $30 | 不考虑 |
 | **NOAA 历史数据** | Marine Cadastre | 美国近海历史 | 免费 | 可用于冷启动 |

@@ -36,16 +36,9 @@
 - 字段：mmsi, lat, lon, sog, cog, heading, nav_status, name, vessel_type, flag
 - 刷新频率：数据约 30–60s 更新一次，可随意轮询

-### TODO：多源 AIS 与实时流接入
+### 多源 AIS 与实时流接入历史

- [ ] 接入 AISStream WebSocket 采集器，作为 BarentsWatch 覆盖不足的实时补充
- [ ] 将 BarentsWatch、AISStream、自定义 `vessel_ais` 映射源统一写入原始观测层
- [ ] 通过聚合接口做去重、字段合并、冲突记录和默认来源选择
- [ ] 开放字段级聚合策略配置，让用户决定不同字段优先信任哪个来源
- [ ] 评估 AISHub 订阅（全球覆盖，约 $30/月），接入全球实时流
- [ ] 评估 MarineTraffic API tier，对比 AISHub 数据质量与成本
- [ ] 实现多数据源适配器，通过 `datasource_config` 切换
- [ ] 真实高频 AIS 稳定接入后，评估将 `vessel_position` 迁移为 TimescaleDB hypertable（保留 Postgres 原生分区作为备选）
+AISStream WebSocket collector、`/api/v1/vessels/snapshot` 和 `/ws` vessels channel 已在后续计划中落地。仍有价值的后续项集中维护在根目录 [TODO](/home/ray/dev/linkong/planet/TODO.md) 的 AIS / Vessels 小节。

 多源 AIS 的详细设计见 [AIS 多源采集、冲突记录与聚合接口计划](/home/ray/dev/linkong/planet/docs/plans/earth-vessel-ais-aggregation-plan.md)。

@@ -252,7 +245,7 @@ IMO         9811000
 ### Phase 4 — 性能与生产化（2–3 天）

 - `vessel_position` 按天分区，7 天自动清理
- TODO：真实数据量达到百万级/日后，将 `vessel_position` 升级为 TimescaleDB hypertable，配置 retention policy 与压缩策略
+- 真实数据量达到百万级/日后，再评估是否将船只时序数据升级为 TimescaleDB hypertable，并配置 retention policy 与压缩策略
 - GeoJSON endpoint 用 Redis 缓存 15s
 - 若需 bbox 精确查询，引入 PostGIS `geography` + `ST_DWithin`
 - InstancedMesh + frustum culling，目标 5 万船只 60fps
--- a/docs/technical/en/earth-bgp-context.md
+++ b/docs/technical/en/earth-bgp-context.md
@@ -157,6 +157,7 @@ Current design:
   - symbol-driven event cores
   - outward ring pulses
   - reduced diffuse glow compared with older Earth builds
+   - event region halos, collector coverage halos, and radar pulses derive a lighter tint from their own icon color instead of using a fixed teal; red high-severity events, orange active collectors, and blue idle collectors keep their hue family while broad halos stay softer than the icon
 5. The right-side stats now show:
   - BGP events
   - collector count
--- a/docs/technical/en/earth-frontend-context.md
+++ b/docs/technical/en/earth-frontend-context.md
@@ -205,9 +205,13 @@ Terrain should not block startup when it is not the restored visible layer. Afte

 Earth settings are stored in `localStorage`. The key is typically a namespaced string defined in `constants.js`. `controls.js` handles read, write, and reset.

-Settings that affect visual layers (terrain opacity, day/night mode, satellite display style, satellite idle breathing, real satellite altitude, track display, etc.) are read during initialization and applied immediately.
+Settings that affect visual layers and surface interaction (terrain opacity, day/night mode, satellite display style, satellite idle breathing, real satellite altitude, track display, hover tooltip mode, etc.) are read during initialization and applied immediately.

-The real satellite altitude preference is persisted by `controls.js`, while the rendering state lives in `satellites.js`. When enabled, the real radius from SGP4 is compressed logarithmically into the current Earth visual radius range. When disabled, satellite dots, trails, and predicted orbits all return to the legacy same-sphere display. Toggling this setting must refresh satellite positions and clear trail buffers so a trail never mixes both height models.
+The surface hover tooltip preference is persisted by `controls.js` as `shared.surfaceHoverInfoMode`, while `main.js` composes the actual tooltip in the globe-surface hover branch. `Country` shows country details only when a country polygon is hit and stays silent over ocean; `Position` shows latitude, longitude, and sampled terrain elevation and clears country-boundary hover; `Full` shows country + position on land and position over ocean.
+
+The real satellite altitude preference is persisted by `controls.js`, while the rendering state lives in `satellites.js`. When enabled, the real radius from SGP4 is compressed logarithmically into the current Earth visual radius range. When disabled, satellite dots, trails, and predicted orbits all return to the legacy same-sphere display. Toggling this setting must refresh satellite positions and clear trail buffers so a trail never mixes both height models. `maxRealAltitudeOffset = 25` is a visual cap tuned for the current camera and `earthRadius = 100`: GEO / MEO remain clearly higher than LEO, but the highest orbits stay within about 25% beyond the globe radius so selection targets, red trails, and the globe do not feel disconnected.
+
+SGP4 propagation returns an inertial-frame position, so it must not be drawn directly as Earth-fixed longitude / latitude. `satellites.js` uses `gstime` to convert ECI/TEME positions to ECF, then maps that result into the same Three.js axes as `latLonToVector3()`. Satellite dots and short trails use Earth-fixed coordinates for each sample time, representing the object's current position relative to the globe surface. The locked predicted orbit uses the `gstime` from the lock moment for the whole future orbit, projecting the inertial orbit plane onto the current globe pose; that keeps the line closed and keeps the visual orbit inclination aligned with the details card. Fallback predicted orbits must also use a real RAAN + inclination orbital-plane formula, not treat inclination as a constant latitude.

 ## Current Terrain Pipeline

--- a/docs/technical/en/earth-layer-style-reference.md
+++ b/docs/technical/en/earth-layer-style-reference.md
@@ -163,7 +163,7 @@ The land/ocean base is an Earth base-map asset and preloads at startup; the "Bor
 | Satellite fallback radius offset | `SATELLITE_CONFIG.fallbackAltitudeOffset` | `8` | Legacy same-sphere position when real altitude is disabled or TLE propagation fails |
 | Satellite altitude compression scale | `SATELLITE_CONFIG.altitudeCompressionKm` | `1200` | TLE/SGP4 altitude compression; larger values soften high-orbit separation |
 | Satellite real-altitude cap | `SATELLITE_CONFIG.maxDisplayAltitudeKm` | `40000` | Altitude clamp for the compressed display mapping, covering GEO-range altitude |
-| Satellite real-altitude display offset range | `minRealAltitudeOffset / maxRealAltitudeOffset` | `4 / 55` | Compressed offset added to `CONFIG.earthRadius` |
+| Satellite real-altitude display offset range | `minRealAltitudeOffset / maxRealAltitudeOffset` | `4 / 25` | Compressed offset added to `CONFIG.earthRadius`; `25` is about one quarter of the current globe radius `100`, keeping high-orbit separation visible without pushing GEO/MEO trails too far away |
 | Satellite dot base pixel size | `SATELLITE_CONFIG.dotBaseSize` | `2.8` | Point shader size |
 | Satellite backdrop dot scale | `SATELLITE_CONFIG.dotBackdropScale` | `1.28` | Backdrop dot size |
 | Satellite dot opacity range | `dotOpacityMin / dotOpacityMax` | `0.42 / 1.0` | Breathing animation |
@@ -233,7 +233,9 @@ AIS vessel markers use batched `THREE.Points`, not one `THREE.Sprite` per vessel
 | Medium color | `BGP_CONFIG.severityColors.medium` | `0xffd166` | Medium-severity event |
 | Low color | `BGP_CONFIG.severityColors.low` | `0x4dabf7` | Low-severity event |
 | Collector base color | `BGP_CONFIG.collectorColor` | `0x6db7ff` | Default collector color |
-| Region color | `BGP_CONFIG.regionColor` | `0x2dd4bf` | Region overlay |
+| BGP halo neutral tint | `BGP_CONFIG.halo.tintNeutralColor` | `0xffffff` | Broad halos derive from the matching event / collector icon color and blend toward this neutral, keeping the same hue family without becoming identical |
+| BGP halo icon-color blend | `BGP_CONFIG.halo.tintBlend` | `0.72` | Higher values stay closer to the icon color; currently used by event region halos, collector coverage halos, and collector radar pulse |
+| Region color | `BGP_CONFIG.regionColor` | `0x2dd4bf` | Legacy region baseline; broad BGP halos now prefer colors derived from the event or collector icon |

 ## Celestial and Starfield

--- a/docs/technical/en/earth-render-layer-order.md
+++ b/docs/technical/en/earth-render-layer-order.md
@@ -29,9 +29,9 @@ Note: the layer control panel order and the registration / startup load order ar
 | 3 | Satellite footprint fill / Iridium coverage ring | `satellites.js`, `iridium-footprint-adapter.js` | `GROUND_FOOTPRINT_RENDER_ORDER` | depth-tested; Iridium adapter fill / ring use the same renderOrder | Footprint above land / texture / terrain and country borders, below compute centers and satellites. |
 | 3-5 | BGP markers and overlays | `bgp.js` | Each marker's own renderOrder | BGP picking path | Preserves existing BGP visual level. |
 | 4.5 | Compute centers | `compute-centers.js` | `COMPUTE_CENTER_RENDER_ORDER` | Compute center picking path | Surface facilities, below satellites. |
-| 5 | Satellite background dot | `satellites.js` | Fixed renderOrder; by default TLE/SGP4 altitude is compressed to `CONFIG.earthRadius + 4..55`; with real altitude disabled or propagation failed, uses `fallbackAltitudeOffset = 8` | Screen-space satellite picking | Below satellite dots. |
+| 5 | Satellite background dot | `satellites.js` | Fixed renderOrder; by default TLE/SGP4 altitude is compressed to `CONFIG.earthRadius + 4..25`; with real altitude disabled or propagation failed, uses `fallbackAltitudeOffset = 8` | Screen-space satellite picking | Below satellite dots. |
 | 6 | Satellite dots | `satellites.js` | Same compressed / fallback height as satellite backdrop dots | Screen-space satellite picking | Satellite dots above footprints and compute centers. |
-| 12+ | Satellite locked ring, halo, predicted orbit | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` and offsets; predicted orbit follows the same real-altitude toggle and returns to same-sphere mode when disabled | Satellite overlay path | Used for selected/locked satellite emphasis. |
+| 12+ | Satellite locked ring, halo, predicted orbit | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` and offsets; predicted orbit follows the same real-altitude toggle and fixes the lock-time globe pose to draw a closed inertial orbit; returns to same-sphere mode when real altitude is disabled | Satellite overlay path | Used for selected/locked satellite emphasis. |
 | 98-100 | Sun / moon halo and sprite | `celestial.js` | Fixed renderOrder | Celestial picking disabled | Foreground celestial sprites. |

 ## Toggle Behavior
--- a/docs/technical/en/faq.md
+++ b/docs/technical/en/faq.md
@@ -323,10 +323,12 @@ Compute-center saves write to `compute_center_locations` and refresh the layer.

 ### Why are satellites no longer on one sphere?

-Earth enables "Real Satellite Altitude" by default. Satellite positions still come from TLE/SGP4, but altitude is compressed for display: LEO satellites stay close to the globe, while higher-orbit satellites render farther out without leaving the normal view. This setting also affects satellite trails and the predicted orbit shown after locking a satellite.
+Earth enables "Real Satellite Altitude" by default. Satellite positions still come from TLE/SGP4, but altitude is compressed for display: LEO satellites stay close to the globe, while higher-orbit satellites render farther out without leaving the normal view. The maximum display offset is `25`, about one quarter of the current globe radius; this is a readability compromise that separates GEO / MEO / LEO without drawing real kilometers to scale. This setting also affects satellite trails and the predicted orbit shown after locking a satellite.

 Turn off "Real Satellite Altitude" in Earth Settings to restore the legacy same-sphere satellite display. Satellites with missing TLE data or failed propagation still fall back to the legacy fixed height, so they do not disappear just because a real altitude cannot be computed.

+Low-inclination high-orbit satellites should stay near the equator or a fixed longitude band, not form a near north-south ring. Earth converts the SGP4 inertial position to Earth-fixed coordinates for the current dot; the locked predicted orbit fixes the current globe pose and draws one inertial orbit, so it should close and preserve the correct inclination. If a future details card shows inclination near `0°` but the predicted orbit looks polar, check the ECI/TEME-to-ECF conversion and whether the predicted orbit accidentally uses per-sample `gstime`.
+
 ### Why does Motion Debug not show camera video?

 With the Browser Camera source, the debug panel shows the local browser camera preview and draws the skeleton over it. If `Skeleton Only` is enabled, the video preview is hidden and the panel keeps only the dark canvas plus red/green skeleton.
--- a/docs/technical/en/manual.md
+++ b/docs/technical/en/manual.md
@@ -255,9 +255,11 @@ Candidates preview on Earth directly. Saving a compute-center candidate writes t

 ### Settings

-The settings panel covers: rotate / cruise / motion mode, cruise modules (BGP/news/compute centers/vessels/cables/satellites), view (satellite display style, satellite idle breathing, real satellite altitude, track display, compact dots, day-night mode, panel toggles), motion debug mode / input source / skeleton-only, default globe size, terrain opacity, reset.
+The settings panel covers: rotate / cruise / motion mode, cruise modules (BGP/news/compute centers/vessels/cables/satellites), view (satellite display style, hover tooltip, satellite idle breathing, real satellite altitude, track display, compact dots, day-night mode, panel toggles), motion debug mode / input source / skeleton-only, default globe size, terrain opacity, reset.

-"Real Satellite Altitude" is enabled by default: satellite positions use a compressed display height based on TLE/SGP4 orbital altitude. LEO satellites remain close to the globe, while high-orbit satellites render farther out without leaving the normal view. Turning it off restores the legacy same-sphere satellite display. "Track Display" controls satellite trail visibility; trails are unavailable while the satellite layer is hidden.
+"Real Satellite Altitude" is enabled by default: satellite positions use a compressed display height based on TLE/SGP4 orbital altitude. LEO satellites remain close to the globe, while high-orbit satellites render farther out without leaving the normal view. The high-orbit display height is capped at about one quarter of the globe radius, so GEO / MEO objects remain visually separated from LEO without spreading trails and selection targets too far apart. Turning it off restores the legacy same-sphere satellite display. "Track Display" controls satellite trail visibility; trails are unavailable while the satellite layer is hidden.
+
+"Hover Tooltip" controls the tooltip shown when the pointer hovers over the globe surface: `Country` shows country details only when land matches a country, and stays silent over oceans such as the Pacific; `Position` shows latitude, longitude, and elevation over land and ocean; `Full` is the default and shows country + position over land and position over ocean.

 These settings live in browser local storage; switching browsers or clearing site data resets them.

--- a/docs/technical/en/quickstart.md
+++ b/docs/technical/en/quickstart.md
@@ -48,7 +48,7 @@ Once in, verify:
 - Search finds cables, satellites, compute centers, BGP events
 - Compute-center and BGP collector detail cards can collect coordinate candidates and preview them on Earth
 - Mouse drag, wheel zoom, and the zoom percentage indicator work
- The settings panel can switch rotate / cruise / motion modes; satellite settings can toggle real-altitude layering and track display
+- The settings panel can switch rotate / cruise / motion modes; view settings can switch hover tooltip content, and satellite settings can toggle real-altitude layering and track display

 ## 5. Recover a Lost Password

--- a/docs/technical/zh/earth-bgp-context.md
+++ b/docs/technical/zh/earth-bgp-context.md
@@ -157,6 +157,7 @@ BGP 模块正在从一个只展示异常的演示功能，演进为分层观测
   - 由符号驱动的事件核心
   - 向外扩散的环形脉冲
   - 相比旧版 Earth 更少的弥散 glow
+   - 事件区域 halo、collector coverage halo 和雷达 pulse 从各自图标色派生浅色调，而不是使用固定青绿色；红色高危事件、橙色活跃 collector 和蓝色 idle collector 保持各自色相一致，面状光晕则比图标更轻
 7. 右侧统计现在显示：
   - BGP events
   - collector count
--- a/docs/technical/zh/earth-frontend-context.md
+++ b/docs/technical/zh/earth-frontend-context.md
@@ -421,11 +421,16 @@ Earth 设置面板当前由 [controls.js](/home/ray/dev/linkong/planet/frontend/
 - HUD 面板显示/隐藏
 - 图层控制开关：`地形 / 卫星 / 海缆 / BGP`
 - 卫星显示偏好：`卫星显示风格 / 卫星呼吸闪烁 / 真实卫星高度 / 轨迹显示`
+- 地表 hover 提示偏好：`国家 / 位置 / 完整`
 - 地形透明度

 也就是说，Earth 设置不是一次性 UI 状态了，而是本地设备级偏好。后续如果再加入新的设置项，应优先接入同一条持久化链，而不是各自散着写 `localStorage`。

-卫星真实高度开关由 `controls.js` 持久化，实际渲染状态在 `satellites.js`。开启时，SGP4 得到的真实半径会按对数压缩到当前 Earth 视觉半径范围；关闭时，卫星点、轨迹和预测轨道都回到旧版同层球面。切换时必须刷新卫星位置并清理轨迹缓存，避免同一条轨迹混入两个高度模型。
+地表 hover 提示由 `controls.js` 持久化为 `shared.surfaceHoverInfoMode`，实际 tooltip 在 `main.js` 的地表 hover 分支组合。`国家` 模式只在命中国家时显示国家信息，海洋区域不显示地表 tooltip；`位置` 模式只显示纬度、经度和地形采样海拔，并清除国家边界 hover；`完整` 模式在陆地显示国家 + 位置，在海洋显示位置。
+
+卫星真实高度开关由 `controls.js` 持久化，实际渲染状态在 `satellites.js`。开启时，SGP4 得到的真实半径会按对数压缩到当前 Earth 视觉半径范围；关闭时，卫星点、轨迹和预测轨道都回到旧版同层球面。切换时必须刷新卫星位置并清理轨迹缓存，避免同一条轨迹混入两个高度模型。`maxRealAltitudeOffset = 25` 是当前相机和 `earthRadius = 100` 下的视觉上限：它让 GEO / MEO 比 LEO 明显更高，但把最高轨道控制在地球半径外约 25%，避免选择点、红色轨迹和主体地球之间出现过大的空场。
+
+SGP4 传播输出是惯性系位置，不能直接当成 Earth 的经纬度固定坐标使用。`satellites.js` 会用当前时间的 `gstime` 把 ECI/TEME 位置转换到 ECF，再映射到 `latLonToVector3()` 使用的 Three.js 坐标轴。卫星点和短尾迹使用随采样时间变化的地固坐标，表示相对当前地球表面的实际位置；锁定后的预测轨道线使用锁定时刻固定的 `gstime`，把未来一圈惯性轨道投到当前地球姿态上显示，因此会闭合，并且轨道面倾角应与详情卡一致。fallback 预测轨道也必须使用真正的 RAAN + inclination 轨道平面公式，不能把 inclination 当成恒定纬度。

 ## 当前地形链路

--- a/docs/technical/zh/earth-layer-style-reference.md
+++ b/docs/technical/zh/earth-layer-style-reference.md
@@ -169,7 +169,7 @@
 | 卫星 fallback 半径偏移 | `SATELLITE_CONFIG.fallbackAltitudeOffset` | `8` | 关闭真实高度或 TLE 传播失败时的旧版同层球面位置 |
 | 卫星真实高度压缩尺度 | `SATELLITE_CONFIG.altitudeCompressionKm` | `1200` | TLE/SGP4 高度压缩映射，数值越大高轨差异越温和 |
 | 卫星真实高度上限 | `SATELLITE_CONFIG.maxDisplayAltitudeKm` | `40000` | 压缩映射的高度截断，覆盖 GEO 附近高度 |
-| 卫星真实高度显示偏移范围 | `minRealAltitudeOffset / maxRealAltitudeOffset` | `4 / 55` | 压缩后映射到 `CONFIG.earthRadius + offset` |
+| 卫星真实高度显示偏移范围 | `minRealAltitudeOffset / maxRealAltitudeOffset` | `4 / 25` | 压缩后映射到 `CONFIG.earthRadius + offset`；`25` 约为当前地球半径 `100` 的四分之一，用于保留高轨分层同时避免 GEO/MEO 轨迹离主体过远 |
 | 卫星点基础像素大小 | `SATELLITE_CONFIG.dotBaseSize` | `2.8` | 点 shader size |
 | 卫星背景点缩放 | `SATELLITE_CONFIG.dotBackdropScale` | `1.28` | 背景点大小 |
 | 卫星点透明度范围 | `dotOpacityMin / dotOpacityMax` | `0.42 / 1.0` | 呼吸动画 |
@@ -252,7 +252,9 @@ AIS 船只普通态使用批量 `THREE.Points`，不是逐船 `THREE.Sprite`。
 | medium 颜色 | `BGP_CONFIG.severityColors.medium` | `0xffd166` | 中危事件 |
 | low 颜色 | `BGP_CONFIG.severityColors.low` | `0x4dabf7` | 低危事件 |
 | collector 基础色 | `BGP_CONFIG.collectorColor` | `0x6db7ff` | collector 默认色 |
-| region 色 | `BGP_CONFIG.regionColor` | `0x2dd4bf` | 区域覆盖 |
+| BGP 光晕浅色基准 | `BGP_CONFIG.halo.tintNeutralColor` | `0xffffff` | 面状 halo 先取对应事件/collector 图标色，再向该中性色混合，保持同色调但不完全同色 |
+| BGP 光晕图标色混合比例 | `BGP_CONFIG.halo.tintBlend` | `0.72` | 值越高越接近图标色；当前用于事件区域 halo、collector coverage halo 和 collector radar pulse |
+| region 色 | `BGP_CONFIG.regionColor` | `0x2dd4bf` | 区域覆盖旧基准；新的面状 BGP halo 优先从事件或 collector 图标色派生 |
 | 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 | local `BGP_COLLECTOR_RENDER_ORDER` | `4.4` | 观测站主图标，与船只同层 |
--- a/docs/technical/zh/earth-render-layer-order.md
+++ b/docs/technical/zh/earth-render-layer-order.md
@@ -32,9 +32,9 @@
 | 4.3 | AIS 船只轨迹线 | `vessels.js` | `VESSEL_RENDER_ORDER - 0.1`；`CONFIG.earthRadius + VESSEL_CONFIG.track.altitudeOffset` | 跟随船只显隐，不单独参与拾取 | 选中船只后显示最近轨迹，低于船只 marker。 |
 | 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；默认按 TLE/SGP4 真实高度压缩到 `CONFIG.earthRadius + 4..55`，关闭真实高度或传播失败时回退到 `fallbackAltitudeOffset = 8` | 屏幕空间卫星拾取 | 位于卫星点下方。 |
+| 5 | 卫星背景点 | `satellites.js` | 固定 renderOrder；默认按 TLE/SGP4 真实高度压缩到 `CONFIG.earthRadius + 4..25`，关闭真实高度或传播失败时回退到 `fallbackAltitudeOffset = 8` | 屏幕空间卫星拾取 | 位于卫星点下方。 |
 | 6 | 卫星点 | `satellites.js` | 与卫星背景点使用同一压缩高度 / fallback 高度 | 屏幕空间卫星拾取 | 卫星点压过 footprint 和算力中心。 |
-| 12+ | 卫星锁定 ring、halo、预测轨道 | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` 及偏移；预测轨道使用同一真实高度开关，关闭时回到同层球面 | 卫星覆盖层路径 | 用于选中 / 锁定卫星强调。 |
+| 12+ | 卫星锁定 ring、halo、预测轨道 | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` 及偏移；预测轨道使用同一真实高度开关，并固定锁定时刻的地球姿态来绘制闭合惯性轨道；关闭真实高度时回到同层球面 | 卫星覆盖层路径 | 用于选中 / 锁定卫星强调。 |
 | 98-100 | 太阳 / 月亮 halo 和 sprite | `celestial.js` | 固定 renderOrder | 天体拾取禁用 | 前景天体 sprite。 |

 ## 开关联动
--- a/docs/technical/zh/faq.md
+++ b/docs/technical/zh/faq.md
@@ -325,10 +325,12 @@ Docs 按 Gatekeeper 权限组控制可见性：

 ### 为什么卫星看起来不在同一个球面上？

-Earth 默认开启“真实卫星高度”。卫星位置仍来自 TLE/SGP4，但高度会经过压缩映射：低轨卫星靠近地球，高轨卫星更远，同时保持在当前视图可读范围内。这个设置也会影响卫星轨迹和锁定后的预测轨道。
+Earth 默认开启“真实卫星高度”。卫星位置仍来自 TLE/SGP4，但高度会经过压缩映射：低轨卫星靠近地球，高轨卫星更远，同时保持在当前视图可读范围内。最高显示偏移使用 `25`，约等于当前地球显示半径的四分之一；这是视觉上区分 GEO / MEO / LEO 和保持镜头可读性的折中，不是把真实公里数按比例直接画出来。这个设置也会影响卫星轨迹和锁定后的预测轨道。

 如果需要旧版所有卫星位于同一显示球面的效果，在 Earth 设置里关闭“真实卫星高度”。缺失 TLE 或传播失败的卫星仍会回退到旧版固定高度，不会因为无法计算真实高度而消失。

+低倾角高轨卫星应该沿赤道附近或固定经度附近分布，而不是绕出接近南北向的大圈。Earth 会先把 SGP4 的惯性系位置转换成地固坐标再绘制当前点；锁定后的预测轨道则固定当前地球姿态来画一圈惯性轨道，所以应该闭合并保留正确倾角。如果以后看到详情卡倾角接近 `0°`，但预测轨道像极轨一样竖着绕，优先检查 ECI/TEME 到 ECF 的转换和预测轨道是否错误使用了逐采样 `gstime`。
+
 ### 动捕调试面板为什么看不到摄像头画面？

 如果输入源是 Browser Camera，调试面板会显示浏览器本机摄像头实时预览，并在画面上绘制骨架。如果勾选了 `只显示骨骼`，视频预览会被隐藏，只显示深色背景和红/绿骨架。
--- a/docs/technical/zh/manual.md
+++ b/docs/technical/zh/manual.md
@@ -258,9 +258,11 @@ AIS 船只图例按船型显示颜色：货轮、油轮、客船、渔船、军

 ### 设置

-设置面板包含：旋转模式 / 巡航模式 / 动捕模式、巡航模块（BGP/新闻/算力中心/船只/海缆/卫星）、视图设置（卫星显示风格、卫星呼吸闪烁、真实卫星高度、轨迹显示、低缩放圆点、日夜模式、面板显示开关）、动捕调试模式 / 输入源 / 只显示骨骼、地球默认大小、地形透明度、重置设置。
+设置面板包含：旋转模式 / 巡航模式 / 动捕模式、巡航模块（BGP/新闻/算力中心/船只/海缆/卫星）、视图设置（卫星显示风格、悬停提示、卫星呼吸闪烁、真实卫星高度、轨迹显示、低缩放圆点、日夜模式、面板显示开关）、动捕调试模式 / 输入源 / 只显示骨骼、地球默认大小、地形透明度、重置设置。

-“真实卫星高度”默认开启：卫星会按 TLE/SGP4 算出的真实轨道高度做压缩分层显示，低轨仍靠近地球，高轨会更远但不会脱离当前视图；关闭后恢复旧版所有卫星位于同一显示球面的效果。“轨迹显示”控制卫星轨迹线显隐，卫星图层关闭时轨迹也不可见。
+“真实卫星高度”默认开启：卫星会按 TLE/SGP4 算出的真实轨道高度做压缩分层显示，低轨仍靠近地球，高轨会更远但不会脱离当前视图。高轨显示高度会被压到地球半径外约四分之一以内，这样 GEO / MEO 仍能和 LEO 分层，但不会把视线、轨迹和选择操作拉得过散；关闭后恢复旧版所有卫星位于同一显示球面的效果。“轨迹显示”控制卫星轨迹线显隐，卫星图层关闭时轨迹也不可见。
+
+“悬停提示”控制鼠标悬停地表时的 tooltip 内容：`国家` 只在陆地命中国家时显示国家信息，太平洋等海洋区域不弹出地表提示；`位置` 在陆地和海洋都显示纬度、经度和海拔；`完整` 是默认模式，陆地显示国家 + 位置，海洋显示位置。

 这些设置保存在浏览器本地存储，换浏览器或清理站点数据后会恢复默认值。

--- a/docs/technical/zh/quickstart.md
+++ b/docs/technical/zh/quickstart.md
@@ -48,7 +48,7 @@
 - 搜索可以查找海缆、卫星、算力中心、BGP 事件
 - 算力中心和 BGP 观测站详情卡可以自动采集坐标候选，并能在 Earth 上预览
 - 鼠标拖动、滚轮缩放、缩放百分比提示工作正常
- 设置面板的旋转 / 巡航 / 动捕模式可以切换；卫星相关设置里可以打开或关闭真实高度分层和轨迹显示
+- 设置面板的旋转 / 巡航 / 动捕模式可以切换；视图设置里可以切换悬停提示，卫星相关设置里可以打开或关闭真实高度分层和轨迹显示

 ## 5. 找回密码

--- a/docs/version-history.md
+++ b/docs/version-history.md
@@ -16,12 +16,13 @@
 ## Current Version

 - `main` 当前主线历史推导到：`0.16.5`
- `dev` 当前开发分支历史推导到：`0.55.0`
+- `dev` 当前开发分支历史推导到：`0.56.0`

 ## Timeline

 | Version | Type | Branch | Commit | Summary |
 | --- | --- | --- | --- | --- |
+| `0.56.0` | feature | `dev` | `pending` | 修复 Earth 卫星 ECI/TEME 到 ECF 坐标转换和闭合预测轨道，调校真实高度压缩上限，统一 BGP 光晕色调，并更新超算图标与 Earth HUD/新闻体验 |
 | `0.55.0` | feature | `dev` | `pending` | Earth 卫星新增真实高度压缩显示开关，轨迹和预测轨道跟随高度模式切换，并补齐设置面板、FAQ、用户手册和开发者文档 |
 | `0.54.0` | feature | `dev` | `pending` | 新增 Earth 轨迹显示设置并迁移到桌面/移动设置面板，持久化轨迹偏好，同时优化卫星呼吸闪烁参数和算力中心图标资产 |
 | `0.53.0` | feature | `dev` | `pending` | 新增 Gitea Actions CI/CD、生产镜像、Kubernetes Helm chart 与 staging 部署 smoke test，明确 Vite 生产构建和 planet.sh 开发入口边界 |