release: bump version to 0.55.0

docs/technical/zh/earth-frontend-context.md

@@ -419,11 +419,14 @@ Earth 设置面板当前由 [controls.js](/home/ray/dev/linkong/planet/frontend/
 - 旋转模式
 - 地球默认大小（作为重置视角、缩放重置和巡航视图的默认 zoom 真源）
 - HUD 面板显示/隐藏
-- 图层控制开关：`地形 / 卫星 / 轨迹 / 海缆 / BGP`
+- 图层控制开关：`地形 / 卫星 / 海缆 / BGP`
+- 卫星显示偏好：`卫星显示风格 / 卫星呼吸闪烁 / 真实卫星高度 / 轨迹显示`
 - 地形透明度
 
 也就是说，Earth 设置不是一次性 UI 状态了，而是本地设备级偏好。后续如果再加入新的设置项，应优先接入同一条持久化链，而不是各自散着写 `localStorage`。
 
+卫星真实高度开关由 `controls.js` 持久化，实际渲染状态在 `satellites.js`。开启时，SGP4 得到的真实半径会按对数压缩到当前 Earth 视觉半径范围；关闭时，卫星点、轨迹和预测轨道都回到旧版同层球面。切换时必须刷新卫星位置并清理轨迹缓存，避免同一条轨迹混入两个高度模型。
+
 ## 当前地形链路
 
 真实地形首次启用会慢，原因不只是一个：

docs/technical/zh/earth-layer-style-reference.md

@@ -166,10 +166,13 @@
 
 | 正式名称 | 变量名 | 当前值 | 使用位置 / 说明 |
 | --- | --- | --- | --- |
-| 卫星显示半径偏移 | `SATELLITE_CONFIG.displayAltitudeOffset` | `8` | 卫星点位置 |
+| 卫星 fallback 半径偏移 | `SATELLITE_CONFIG.fallbackAltitudeOffset` | `8` | 关闭真实高度或 TLE 传播失败时的旧版同层球面位置 |
+| 卫星真实高度压缩尺度 | `SATELLITE_CONFIG.altitudeCompressionKm` | `1200` | TLE/SGP4 高度压缩映射，数值越大高轨差异越温和 |
+| 卫星真实高度上限 | `SATELLITE_CONFIG.maxDisplayAltitudeKm` | `40000` | 压缩映射的高度截断，覆盖 GEO 附近高度 |
+| 卫星真实高度显示偏移范围 | `minRealAltitudeOffset / maxRealAltitudeOffset` | `4 / 55` | 压缩后映射到 `CONFIG.earthRadius + offset` |
 | 卫星点基础像素大小 | `SATELLITE_CONFIG.dotBaseSize` | `2.8` | 点 shader size |
 | 卫星背景点缩放 | `SATELLITE_CONFIG.dotBackdropScale` | `1.28` | 背景点大小 |
-| 卫星点透明度范围 | `dotOpacityMin / dotOpacityMax` | `0.7 / 1.0` | 呼吸动画 |
+| 卫星点透明度范围 | `dotOpacityMin / dotOpacityMax` | `0.42 / 1.0` | 呼吸动画 |
 | 卫星点呼吸速度 | `SATELLITE_CONFIG.dotBreathingSpeed` | `0.12` | 点 opacity 动画 |
 | 卫星背景点颜色 | inline | `0x0b1626` | backdrop point baseColor |
 | 卫星背景点透明度 | inline | `0.42` | backdrop point opacity |

docs/technical/zh/earth-render-layer-order.md

@@ -7,7 +7,7 @@
 
 | 顺序类型 | 当前顺序 | 说明 |
 | --- | --- | --- |
-| 控制面板顺序 | 海缆 → 轨迹 → 卫星 → 算力中心 → 船只 → BGP → 地形 → 高清材质 → 大气云图 → 国界线 → 经纬线 | 由 `displayOrder` 控制，按操作关注度排列。 |
+| 控制面板顺序 | 海缆 → 卫星 → 算力中心 → 船只 → BGP → 地形 → 高清材质 → 大气云图 → 国界线 → 经纬线 | 由 `displayOrder` 控制，按操作关注度排列；卫星轨迹已迁到设置面板，不再作为图层列表项。 |
 | 注册 / 启动加载顺序 | 经纬线 → 国界线 / 海陆基座 → 高清材质 → 大气云图 → 海缆 → 算力中心 → 船只 → BGP → 卫星 | 由注册顺序和 `startupPriority` 控制，按地表到天空排列；启动队列会先读取保存的图层可见状态，明确关闭的普通图层不预加载，高清材质关闭时不下载贴图；国界线图层例外，海陆基座始终预加载，保存状态只控制可交互国界线和 hover；轨迹和地形是依赖/可选显示层，不参与常规启动数据加载。 |
 
 ## 地表图层栈
@@ -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 | 屏幕空间卫星拾取 | 位于卫星点下方。 |
-| 6 | 卫星点 | `satellites.js` | 固定 renderOrder | 屏幕空间卫星拾取 | 卫星点压过 footprint 和算力中心。 |
-| 12+ | 卫星锁定 ring、halo、预测轨道 | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` 及偏移 | 卫星覆盖层路径 | 用于选中 / 锁定卫星强调。 |
+| 5 | 卫星背景点 | `satellites.js` | 固定 renderOrder；默认按 TLE/SGP4 真实高度压缩到 `CONFIG.earthRadius + 4..55`，关闭真实高度或传播失败时回退到 `fallbackAltitudeOffset = 8` | 屏幕空间卫星拾取 | 位于卫星点下方。 |
+| 6 | 卫星点 | `satellites.js` | 与卫星背景点使用同一压缩高度 / fallback 高度 | 屏幕空间卫星拾取 | 卫星点压过 footprint 和算力中心。 |
+| 12+ | 卫星锁定 ring、halo、预测轨道 | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` 及偏移；预测轨道使用同一真实高度开关，关闭时回到同层球面 | 卫星覆盖层路径 | 用于选中 / 锁定卫星强调。 |
 | 98-100 | 太阳 / 月亮 halo 和 sprite | `celestial.js` | 固定 renderOrder | 天体拾取禁用 | 前景天体 sprite。 |
 
 ## 开关联动
@@ -46,6 +46,7 @@
 | 地形 on | 显示在高清材质之上，但低于国界 hover、footprint、卫星等强调层。 |
 | 大气云图 | 只控制云图 mesh 显隐。 |
 | 国界线 off | 只隐藏可交互国界线和 hover，高亮状态会清除；海陆基座填充仍作为 Earth 底图保留。 |
+| 真实卫星高度 off | 卫星点、轨迹和预测轨道都使用旧版同层球面；缺失 TLE 或传播失败的卫星也使用同一 fallback 高度。 |
 
 ## 交互规则
 

docs/technical/zh/faq.md

@@ -323,6 +323,12 @@ Docs 按 Gatekeeper 权限组控制可见性：
 
 算力中心候选保存后会写入 `compute_center_locations`。没有可用候选的记录会保留在待定位列表中，系统不会用国家中心点或硬编码 hint 伪造位置。
 
+### 为什么卫星看起来不在同一个球面上？
+
+Earth 默认开启“真实卫星高度”。卫星位置仍来自 TLE/SGP4，但高度会经过压缩映射：低轨卫星靠近地球，高轨卫星更远，同时保持在当前视图可读范围内。这个设置也会影响卫星轨迹和锁定后的预测轨道。
+
+如果需要旧版所有卫星位于同一显示球面的效果，在 Earth 设置里关闭“真实卫星高度”。缺失 TLE 或传播失败的卫星仍会回退到旧版固定高度，不会因为无法计算真实高度而消失。
+
 ### 动捕调试面板为什么看不到摄像头画面？
 
 如果输入源是 Browser Camera，调试面板会显示浏览器本机摄像头实时预览，并在画面上绘制骨架。如果勾选了 `只显示骨骼`，视频预览会被隐藏，只显示深色背景和红/绿骨架。

docs/technical/zh/manual.md

@@ -232,7 +232,7 @@ Earth `http://localhost:3000/earth` 是公开 3D 态势页面，不需要登录
 
 ### 图层控制
 
-右侧图层面板用于打开或关闭图层。常见图层：经纬线、国界线、高清材质、大气云图、海缆、算力中心、BGP 观测、卫星、AIS 船只、轨迹、地形。
+右侧图层面板用于打开或关闭图层。常见图层：经纬线、国界线、高清材质、大气云图、海缆、算力中心、BGP 观测、卫星、AIS 船只、地形。卫星轨迹不再作为单独图层出现在图层列表中，改在设置面板里控制。
 
 依赖关系：
 
@@ -258,7 +258,9 @@ AIS 船只图例按船型显示颜色：货轮、油轮、客船、渔船、军
 
 ### 设置
 
-设置面板包含：旋转模式 / 巡航模式 / 动捕模式、巡航模块（BGP/新闻/算力中心/船只/海缆/卫星）、视图设置（卫星显示风格、日夜模式、面板显示开关）、动捕调试模式 / 输入源 / 只显示骨骼、地球默认大小、地形透明度、重置设置。
+设置面板包含：旋转模式 / 巡航模式 / 动捕模式、巡航模块（BGP/新闻/算力中心/船只/海缆/卫星）、视图设置（卫星显示风格、卫星呼吸闪烁、真实卫星高度、轨迹显示、低缩放圆点、日夜模式、面板显示开关）、动捕调试模式 / 输入源 / 只显示骨骼、地球默认大小、地形透明度、重置设置。
+
+“真实卫星高度”默认开启：卫星会按 TLE/SGP4 算出的真实轨道高度做压缩分层显示，低轨仍靠近地球，高轨会更远但不会脱离当前视图；关闭后恢复旧版所有卫星位于同一显示球面的效果。“轨迹显示”控制卫星轨迹线显隐，卫星图层关闭时轨迹也不可见。
 
 这些设置保存在浏览器本地存储，换浏览器或清理站点数据后会恢复默认值。
 
@@ -313,6 +315,7 @@ Earth 预留了动作捕捉控制入口。实时链路两种输入源：
 - **Earth 打不开**：先确认前端服务是否在线；如果端口不是 `3000`，使用启动输出的实际端口
 - **图层没有数据**：进 `/datasources` 看数据源状态、是否已采集和最近执行结果，再到 `/data` 或 `/bgp` 看是否有记录
 - **卫星 / BGP / 海缆加载慢**：这些图层依赖后端接口和外部数据源，首次加载需要等启动任务完成
+- **卫星看起来不在同一层**：这是默认的真实高度压缩显示。想回到旧版同层球面，可在设置中关闭“真实卫星高度”
 
 ## Docs 文档站
 

docs/technical/zh/quickstart.md

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