release: bump version to 0.66.0

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

@@ -0,0 +1,160 @@
+# 业务架构与数据流转
+
+本文是 Planet 数据产品的业务入口。它解释每类 Earth 数据为什么存在、从哪里采集、落到哪些事实表或派生表、如何通过缓存和 WebSocket 反映到 Earth。前端、后端和 Earth 技术文档只记录实现细节；跨端理解数据链路时优先从这里开始。
+
+## 总览
+
+Planet 的核心数据链路分三段：
+
+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/...` 重拉数据。
+
+```mermaid
+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。
+
+## 数据产品清单
+
+```mermaid
+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 图层"]
+```
+
+| 数据产品 | 业务用途 | 事实来源 | 派生 / 维表 | Earth 图层 | 刷新策略 |
+| --- | --- | --- | --- | --- | --- |
+| 卫星 | 展示在轨目标、轨迹、覆盖和巡航目标 | `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 还在”的链路。
+
+```mermaid
+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 渲染使用位置快照和静态船舶信息，不应依赖原始 AIS 记录逐条渲染。
+
+- **采集入口**：AIS sources、BarentsWatch vessels。
+- **事实表**：`collected_data` 或 AIS 原始观测表。
+- **派生表**：`vessel_static`、`vessel_position`、`ais_raw_observations`、`ais_source_health`。
+- **接口**：vessels visualization API 返回当前船只 marker 和必要详情。
+- **删除语义**：删除任一船舶 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 技术文档记录实现细节。