planet/docs/technical/zh/platform-data-flows.md

业务架构与数据流转

本文是智能星球数据产品的业务入口。它解释每类 Earth 数据为什么存在、从哪里采集、落到哪些事实表或派生表、如何通过缓存和 WebSocket 反映到 Earth。前端、后端和 Earth 技术文档只记录实现细节；跨端理解数据链路时优先从这里开始。

总览

智能星球的核心数据链路分三段：

1. 采集与整理：内置采集器、后台操作或定位管线写入 PostgreSQL。通用原始结果进入 collected_data，图层需要的二次结果进入派生表。
2. 投影与广播：数据库触发器把事实变化写入 earth_data_change_events outbox，并用 LISTEN/NOTIFY 唤醒后端 listener。listener 通过 layer adapter 找到 Earth 图层，失效缓存并广播 earth_updates。
3. Earth 重拉与呈现：Earth 前端收到 layer 级刷新提示后，按 clear_then_reload、reload 或 delta 策略清理本地图层对象，再从 /api/v1/visualization/... 重拉数据。

flowchart LR
  Source["外部数据源 / 后台操作"] --> Collector["采集器或数据作业"]
  Collector --> Facts["collected_data"]
  Collector --> Derived["派生表"]
  Facts --> Outbox["earth_data_change_events"]
  Derived --> Outbox
  Outbox --> Listener["DB change listener"]
  Listener --> Cache["Earth cache invalidation"]
  Listener --> WS["earth_updates"]
  WS --> Earth["Earth layer reload"]
  Earth --> API["Visualization APIs"]

LISTEN/NOTIFY 只负责低延迟唤醒，可靠来源是 outbox。真实 0 数据是正常状态，接口应返回 200 和空集合；只有接口异常才返回 5xx。

数据产品清单

flowchart TB
  Satellites["卫星 TLE"] --> SatelliteLayer["satellites 图层"]
  Cables["海缆 + 登陆点"] --> CableLayer["cables 图层"]
  Compute["TOP500 / AI GPU / HF"] --> ComputeLocations["compute_center_locations"]
  ComputeLocations --> ComputeLayer["computeCenters 图层"]
  BgpRaw["RIS Live / BGPStream / Prefix"] --> BgpDerived["bgp_observations / anomalies / incidents"]
  BgpDerived --> BgpLayer["bgp 图层"]
  VesselRaw["AIS / BarentsWatch"] --> VesselDerived["vessel_static / vessel_position"]
  VesselDerived --> VesselLayer["vessels 图层"]
  Interactables["earth_interactables"] --> InteractableLayer["interactables 图层"]
  NewsRaw["RSS / Live / News"] --> NewsItems["earth_news_items"]
  NewsItems --> NewsLayer["news / media 图层"]

数据产品	业务用途	事实来源	派生 / 维表	智能星球图层	刷新策略
卫星	展示在轨目标、轨迹、覆盖和巡航目标	celestrak_tle、spacetrack_tle	无稳定独立派生表，TLE 由接口实时转换	satellites	clear_then_reload
海缆与登陆点	展示跨洋连接、登陆点和 cable 详情	arcgis_cables、arcgis_landing_points、TeleGeography / FAO landing sources	海缆关系和登陆点聚合数据	cables	clear_then_reload
算力中心	展示 TOP500、AI GPU、HuggingFace 等算力节点	top500、epoch_ai_gpu、HuggingFace sources	compute_center_locations	computeCenters	reload
BGP 态势	展示观测站、异常事件、路由事件和区域态势	ris_live_bgp、bgpstream_bgp、prefix geography sources	bgp_observations、bgp_anomalies、bgp_incidents、bgp_collector_locations	bgp	clear_then_reload
船舶	展示 AIS 船只、位置、轨迹和源健康	AIS sources、barentswatch_vessels	vessel_static、vessel_position、ais_raw_observations、ais_source_health	vessels	clear_then_reload
可交互对象	支撑通用地表图标、人工点位和未来扩展对象	earth_interactables	无	interactables	delta
新闻与媒体	支撑 Earth 新闻、直播和巡航摘要	news sources	earth_news_items	news / media	reload

卫星链路

卫星数据用于 Earth 的在线卫星点、轨迹线、覆盖策略和巡航列表。采集器从 CelesTrak 或 Space-Track 拉取 TLE，写入 collected_data。可视化接口按请求把 TLE 转成当前时刻的位置和轨迹，不依赖长期派生表。

• 采集入口：CelesTrak TLE、Space-Track TLE。
• 事实表：collected_data.source IN ('celestrak_tle', 'spacetrack_tle')。
• 接口：卫星 visualization API 读取 TLE 并生成 Earth payload。
• 删除语义：删除对应 source 后，listener 广播 satellites 的 clear_then_reload，前端先清卫星点和轨迹，再重拉接口。接口若无 TLE，应返回空列表。
• 常见异常：summary 已变 0 但 Earth 仍显示，通常是 WS 未触发、adapter 未覆盖 source，或前端没有在 clear_then_reload 中清掉已有 Three.js 对象。

海缆与登陆点链路

海缆和登陆点用于展示跨海网络连接、登陆城市、线路详情和搜索对象。海缆线与登陆点都属于同一个业务图层；删除任一侧数据都必须刷新 cables，否则会出现线消失但点残留，或点消失但线残留。

• 采集入口：ArcGIS cables、ArcGIS landing points，以及 TeleGeography / FAO landing 相关 source。
• 事实表：collected_data 中的 cable 和 landing point source。
• 派生数据：海缆关系表、landing point 聚合结果、接口缓存。
• 接口：海缆 visualization API 返回 cables、landing points 和关系数据。
• 删除语义：删除海缆或登陆点 source 后，adapter 清理 owned 派生数据并广播 cables 的 clear_then_reload。接口没有数据时返回 200 空集合，不返回 404。
• 常见异常：海缆短暂变 0 又回来，多半是采集替换或缓存刷新窗口内旧缓存被重新命中，需要检查数据作业是否重复广播或 cache pattern 是否覆盖完整。

算力中心链路

算力中心用于展示超算、AI GPU、模型平台相关设施和位置补全状态。原始 source 通常只有机构、国家、站点名或模糊位置，Earth 渲染依赖 compute_center_locations 维表提供可用坐标。

• 采集入口：TOP500、Epoch AI GPU、HuggingFace 相关 source。
• 事实表：collected_data 中的算力 source。
• 维表：compute_center_locations 保存人工或自动采集到的坐标候选采用结果。
• 接口：算力中心 visualization API 合并原始记录和位置维表。
• 删除语义：删除 TOP500 等 source 后必须刷新 computeCenters；删除位置维表则也要刷新该图层。通常用 reload，因为位置更新不一定需要先清空。
• 常见异常：采集已完成但 Earth 数量不变，通常是接口使用缓存、位置维表未更新，或 source 删除没有触发 adapter。

BGP 链路

BGP 数据用于展示路由观测站、异常事件、事件扩散圈和态势摘要。Earth 不直接展示原始 BGP 行，而是展示聚合后的观测、异常和事件。因此 BGP 是最容易出现“原始数据删了但 Earth 还在”的链路。

sequenceDiagram
  participant UI as 后台删除按钮
  participant Job as clear_data 作业
  participant DB as PostgreSQL
  participant Outbox as earth_data_change_events
  participant Listener as DB change listener
  participant Earth as Earth 前端

  UI->>Job: 提交删除 ris_live_bgp / bgpstream_bgp
  Job->>DB: 删除 collected_data 原始记录
  Job->>DB: 删除 BGP owned 派生表
  DB->>Outbox: trigger 写入 bgp layer changed
  DB-->>Listener: LISTEN/NOTIFY 唤醒
  Listener->>Listener: 合并事件并清理 bgp cache
  Listener-->>Earth: broadcast earth_updates clear_then_reload
  Earth->>Earth: 清空 BGP 对象
  Earth->>DB: 通过 visualization API 重拉派生结果

• 采集入口：RIPE RIS Live BGP、CAIDA BGPStream Backfill、IPtoASN / OpenGeoFeed / NRO prefix geography。
• 事实表：collected_data 中的 BGP 和 prefix source。
• 派生表：bgp_observations、bgp_anomalies、bgp_incidents、bgp_collector_locations。
• 接口：BGP visualization API 读取派生表，并结合定位候选或已保存位置。
• 删除语义：删除 RIS Live 或 BGPStream 原始 source 时，必须同步清理 BGP owned 派生表并广播 bgp 的 clear_then_reload。直接删除派生表也要触发 outbox。
• 常见异常：观测站或异常事件没有消失，优先查派生表是否还保留旧记录，而不是只看 collected_data。

船舶链路

船舶数据用于展示 AIS 船只、航行状态、船型图例和源健康。Earth 渲染使用 vessel_current_state 当前状态快照，不应依赖原始 AIS 记录逐条渲染。

• 采集入口：AIS sources、BarentsWatch vessels。
• 事实表：collected_data 或 AIS 原始观测表。
• 派生表：vessel_current_state、vessel_static、vessel_position、ais_raw_observations、ais_source_health。
• 接口：/api/v1/vessels/snapshot 返回当前船只 marker 和必要详情；Earth 前端使用全球 bbox 请求全局当前状态。
• 删除语义：删除任一船舶 source 后，owned 派生表变化会广播 vessels 的 clear_then_reload。
• 常见异常：数量面板变化但船只仍在，多半是 summary 和图层数据分离，前端应以 layer update 为准清空对象。

可交互对象链路

earth_interactables 是通用地表图标能力，用于人工对象、扩展对象和未来小型图层。它和大多数图层不同，保留对象级 delta。

• 事实表：earth_interactables。
• 接口：interactable API 和 Earth 通用图标接口。
• 刷新策略：新增或更新用 upsert，删除用 removeItem，不重拉整个图层。
• 删除语义：删除一条 interactable 后，WS payload 必须包含稳定 id，让前端移除对应对象。
• 常见异常：对象删不掉，通常是缺少稳定 id、前端 delta handler 没有命中 object type，或旧图层还有重复渲染路径。

新闻与媒体链路

新闻与媒体数据用于 Earth 顶部新闻条、直播面板、新闻巡航和态势摘要。它们的视觉状态比地理对象更偏内容刷新，因此默认使用 reload。

• 采集入口：RSS、直播源、新闻 source。
• 事实表：新闻 source 的 collected_data。
• 派生表：earth_news_items。
• 接口：新闻、直播和媒体 visualization / content API。
• 删除语义：删除新闻 source 或 earth_news_items 后广播 news / media reload；前端重拉后列表为空即隐藏对应内容。
• 常见异常：直播面板仍显示旧内容，通常是媒体组件本地状态没有响应 layer update，或内容接口缓存未失效。

扩展新图层

新增 Earth 数据产品时，按这个顺序接入：

1. 定义业务用途和 Earth 图层名。
2. 明确事实 source、事实表和派生表。
3. 在后端 layer adapter 注册 source/table、cache pattern、owned derived cleanup 和默认刷新策略。
4. 确保 visualization API 对空数据返回 200 空集合。
5. 让 Earth 前端只按 layer 和 strategy 刷新，不理解数据库表名。
6. 在本文补充该数据产品的链路，再到对应前端、后端或 Earth 技术文档记录实现细节。