planet/docs/technical/zh/earth-satellite-footprint-policy.md

Earth 卫星覆盖策略

本文件记录 Earth 卫星图层当前关于 footprint 的产品边界、资料依据和已落地实现，目标是避免把 Starlink 这套专用地表覆盖模型误用到其它星座上。

相关上下文：

• Earth 前端结构
• 数据采集系统
• backend/app/services/collectors/celestrak.py
• frontend/public/earth/js/satellites.js

当前目标

• 明确哪些非 Starlink 卫星不该显示贴地 footprint
• 明确哪些星座未来可以有独立 footprint，但不能复用 Starlink bowtie / GSO-gap 模型
• 把这条策略沉淀成可执行实现边界，而不是继续散落在视觉参数里

本地实际类别

当前 CelesTrak 采集器从 GROUP=active&FORMAT=json 拉取完整活跃卫星目录，而不是逐个小分组拉取后合并。这样可以避免某个 CelesTrak 分组请求失败时仍把不完整结果保存为成功批次。采集器只在完整 JSON 数组可解析、且记录含 NORAD_CAT_ID 时进入转换和保存；网络、续传或解析失败会重试，最终失败时保留上一批 current 数据。

采集结果仍会给前端提供 metadata.constellation_group，但该字段现在来自可执行推断：

• OBJECT_NAME 以 STARLINK 开头时标记为 starlink
• OBJECT_NAME 以 IRIDIUM 开头时标记为 iridium-next
• 其它活跃卫星不强行归入旧 CelesTrak 小分组，避免把泛化类别当成精确星座

因此，非 Starlink 类别在产品策略中仍包括 GNSS/RNSS、GEO、generic LEO 和 Iridium NEXT 等语义，但不能再假设采集器保存了旧的 gps-ops、galileo、glonass、beidou、leo、geo 分组标签。

资料结论

1. GNSS / RNSS: gps-ops, galileo, glonass, beidou

默认不要画局部地表 footprint。

原因：

• 公开资料强调的是 Earth-pointing、Earth coverage、continuous global coverage
• 这类系统的公开语义是全球导航 / 授时覆盖，不是 Starlink 那种面向终端业务的局部 spot footprint

更合适的表示：

• 默认只显示卫星本体和轨道
• 如果后续要强调“服务可达性”，只能做很弱的 global coverage 语义，不应画贴地局部光斑

资料：

• GPS III EC Antenna Patterns
• ESA Galileo satellites
• Navipedia Galileo General Introduction
• BeiDou official overview
• GPS.gov GNSS overview

2. iridium-next

可以有 footprint，但不能复用 Starlink 的单一 bowtie footprint。

原因：

• Iridium NEXT 公开资料强调的是固定多 spot beam 体系
• 公开示例里常见的是 48 fixed spot beams in 4 tiers
• 这和 Starlink 当前这套“单星、单主 footprint、带 GSO 缺口”的业务可视化不是同一个问题

更合适的表示：

• 默认：仍然不画 Starlink 式地表 footprint
• 后续如果要做：单独接入 Iridium 多波束适配层
• 在视觉上更接近多束 cluster / 蜂窝 / 分层束，而不是单个 bowtie 光斑

资料：

• Iridium Satellite Spot Beam Coverage on the US

3. geo

默认不要画统一 footprint。

原因：

• GEO 通信星公开上可能是 global beam、zone beam、spot beam、steerable spot beam
• 没有 operator / payload / beam contour 元数据时，统一画一个 footprint 很容易错

更合适的表示：

• 默认只显示 GEO belt 和卫星驻点语义
• 只有拿到 beam contour / operator metadata 时才允许画 footprint

资料：

• ITU Handbook on Satellite

4. leo（generic）

默认不要画 footprint。

原因：

• leo 组过于混杂，可能同时包含通信、遥感、试验、观测等不同任务
• 没有 mission / payload / antenna pattern 元数据时，无法判断是否存在可视化意义上的服务覆盖面

更合适的表示：

• 默认只显示卫星和轨道
• 后续如果按 operator / mission subtype 细分，再决定是否引入独立 coverage mode

产品策略

当前统一策略如下：

• Starlink
  • 保留当前专用 ground_footprint 逻辑
• Iridium NEXT
  • 预留独立适配层
  • 当前不复用 Starlink footprint
• GPS / Galileo / GLONASS / BeiDou
  • 不显示贴地 footprint
• GEO
  • 无 beam metadata 不显示 footprint
• generic LEO
  • 无 mission metadata 不显示 footprint

已落地实现

本次实现只做最小可执行版本，不改现有 Starlink 视觉参数：

1. 后端把星座分组和 footprint 策略提示透给前端

• CelesTrak collector 会把原始查询来源记入 metadata.celestrak_query_group = active
• metadata.constellation_group 只保存可推断的业务星座，例如 starlink 和 iridium-next
• Visualization API 会输出：
  • properties.constellation_group
  • properties.footprint_policy

当前策略值：

• starlink_ground_footprint
• iridium_coverage_ring
• none

对应代码：

• backend/app/services/collectors/celestrak.py
• backend/app/api/v1/visualization.py

2. 前端把 footprint 变成 capability-gated renderer

• ground_footprint 只有在 footprint_policy === starlink_ground_footprint 时才真正启用
• iridium-next 不再回退成占位分支，而是走独立的 Iridium coverage ring adapter
• 其它非 Starlink 即使用户全局选择了 ground_footprint，也会自动回退到 self_glow

对应代码：

• frontend/public/earth/js/satellites.js
• frontend/public/earth/js/iridium-footprint-adapter.js

3. 卫星信息卡显示 capability，而不是只显示轨道参数

• 卫星详情现在会明确显示：
  • 星座/分组
  • 覆盖能力
  • 当前显示
  • 覆盖模型
• 这样用户能直接看到：
  • 当前卫星是否支持 footprint
  • 当前显示是不是因为 capability gating 被回退
  • Iridium 和 Starlink 使用的不是同一种模型

对应代码：

• frontend/public/earth/js/main.js
• frontend/public/earth/js/info-card.js

当前实现边界

这条边界需要继续保持：

• Starlink 的 footprint 参数和 shader 逻辑只服务于 Starlink
• 非 Starlink 的能力判断属于“策略层 / 适配层”
• 不要把不同星座的覆盖模型再混写进同一套参数里
• iridium-next 已经切成独立 adapter，应继续沿这条边界演进，而不是给现有 Starlink bowtie 增加更多 if/else