release: bump version to 0.70.0

2026-06-04 17:16:23 +08:00
parent acbbfdf9e2
commit 8c204717cd
78 changed files with 1762 additions and 703 deletions
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,6 +8,24 @@ This project follows the repository versioning rule:
 - `improvement` -> `+0.0.1`（bugfix + 小功能混合）
 - `bugfix` -> `+0.0.1`

+## [0.70.0] — 2026-06-04
+
+Released: 2026-06-04
+
+### Highlights
+- 新增后端枚举契约治理，将稳定协议状态集中到 `app/core/enums.py`，同时保持数据库和 API 的小写字符串兼容。
+- 改进 Earth 新闻分类、重要度与 Breaking 插队链路，并补齐中英文新闻源与枚举契约文档。
+- 将 Earth 船只展示改为 `vessel_current_state` 当前状态快照，保留 AIS 原始历史用于轨迹和态势分析。
+- 清理错误的船只视口刷新/订阅思路，恢复全球船只显示，并让性能优化集中到批量渲染、关闭动态聚类和减少 hover/rebuild 开销。
+
+### Added / Fixed / Improved
+- `earth_news_classification.py` 集中管理新闻类型、重要度和 Breaking 规则，避免抓取编排层重复判断。
+- `/api/v1/vessels/snapshot` 支持全球当前状态读取和小数 zoom，诊断信息明确返回 `vessel_current_state` 来源。
+- 船只前端使用全球 bbox + `limit=3000`，不再随相机视口重复请求或建立多视口 WebSocket 订阅。
+- 中英文技术文档同步更新船只、采集器、数据流、渲染层级、样式参数和历史计划状态。
+
+---
+
 ## [0.69.0] — 2026-06-03

 Released: 2026-06-03
--- a/docs/plans/earth-vessel-ais-aggregation-plan.md
+++ b/docs/plans/earth-vessel-ais-aggregation-plan.md
@@ -1,6 +1,6 @@
 # AIS 多源采集、冲突记录与聚合接口计划

-**状态**：v0-v3 已实现，v3.1-v3.4 为 v4/v5 前置稳定化任务，v4 / v5 已落最小可用子集
+**状态**：v0-v3 已实现，v3.1-v3.4 为 v4/v5 前置稳定化任务，v4 / v5 已落最小可用子集；`0.70.0` 起 Earth 展示路径已转向 `vessel_current_state` 当前状态表和全球快照，不再由 raw observation 聚合结果直接驱动首屏显示。
 **创建日期**：2026-04-30  
 **核心原则**：采集器只写原始观测；去重、合并、冲突解释放在聚合接口中完成

@@ -344,11 +344,11 @@ VesselFinder 等服务里的船只图片不属于 AIS 实时数据本身。图
 3. 聚合结果返回 `source_summary`，展示每艘船的来源、观测数量、最新观测时间、传输模式和消息类型。
 4. 保留 `field_sources` 和 `selected_reasons`，用于解释动态字段来自实时流、静态字段来自可用非空来源。
 5. 船名标准化会读取 AISStream `MetaData.ShipName`；船型展示会从 `vessel_type_name` 和 AIS 数字 `vessel_type` 共同归一化，保证 marker 颜色、详情卡、hover 和搜索结果一致。
-6. 当前实现已转向 `/api/v1/vessels/snapshot`：必须带 bbox / zoom，默认 `limit=1000`，最大 `limit=5000`，不再支持旧 `/geo/vessels` 全量返回。
+6. 当前实现已转向 `/api/v1/vessels/snapshot`：必须带 bbox / zoom，Earth 运行时使用全球 bbox 和 `limit=3000`，后端最大 `limit=5000`，不再支持旧 `/geo/vessels` 全量返回。

-### v3.1 — 聚合完整性修复（已被受控 fallback 取代）
+### v3.1 — 聚合完整性修复（已被当前状态表取代）

-原目标是先保证“所有已采集到的船都能显示”，BarentsWatch 不因为接入 AISStream 而被 raw observation 聚合结果遮蔽。当前实现已经移除旧 `/geo/vessels` 路由，船只入口统一为 `/api/v1/vessels/snapshot`。snapshot 优先读取 `ais_raw_observations` 聚合结果；当当前 raw 窗口为空时，才受控回退到 `vessel_position + vessel_static` 最新点，并通过 `diagnostics.legacy_fallback_used` 标记。
+原目标是先保证“所有已采集到的船都能显示”，BarentsWatch 不因为接入 AISStream 而被 raw observation 聚合结果遮蔽。当前实现已经移除旧 `/geo/vessels` 路由，船只入口统一为 `/api/v1/vessels/snapshot`。snapshot 现在读取 `vessel_current_state` 当前状态表；`ais_raw_observations` 继续保留给轨迹、审计和态势分析，不再由展示接口临时扫描聚合。

 因此以下旧 `/geo/vessels` 全量 merge 要求作废，保留在文档中只作为历史决策记录：

--- a/docs/plans/earth-vessel-rendering-performance-plan.md
+++ b/docs/plans/earth-vessel-rendering-performance-plan.md
@@ -9,8 +9,9 @@
 - hover / locked 不再放大成世界尺寸 Sprite，而是在原点位叠加同尺寸单点 glow overlay。
 - picking 改为屏幕空间命中，拖动和惯性期间跳过 hover picking。
 - 普通态关闭 glow，交互态才显示 glow，降低 overdraw 并让默认地图更干净。
+- `0.70.0` 起船只继续走全球当前状态快照：`vessel_current_state` + 全球 bbox + `limit=3000`。上一轮“按当前镜头 bbox 刷新/订阅”的方向已撤回，性能优化集中在批量渲染、关闭动态聚类和减少 picking / rebuild 开销。

-后续如果需要全球 AIS 或更高船只密度，再评估是否从分桶 `Points` 升级到真正 instanced quad 或视口 bbox / LOD。
+后续如果需要更高船只密度，再评估是否从分桶 `Points` 升级到真正 instanced quad 或服务端 LOD；不要把普通旋转/缩放重新接回视口驱动请求。

 ## 背景

@@ -214,9 +215,9 @@ hover、locked、dimmed 可通过更新少量 instance attribute 实现，不再

 当接入全球 AIS 或船只数量显著增加时，再做数据层优化。

-### 1. 请求视口范围
+### 1. 当前状态快照

-前端请求 `/api/v1/vessels/snapshot` 时必须带上当前视口 `bbox`、`zoom` 和受控 `limit`，减少无关船只。旧 `/api/v1/visualization/geo/vessels` 路由已移除。
+前端请求 `/api/v1/vessels/snapshot` 时仍必须带 `bbox`、`zoom` 和受控 `limit`，但 Earth 运行时传全球 bbox 和 `limit=3000`，不使用当前镜头视口驱动刷新。旧 `/api/v1/visualization/geo/vessels` 路由已移除。

 ### 2. 后端排序策略

@@ -224,7 +225,7 @@ hover、locked、dimmed 可通过更新少量 instance attribute 实现，不再

 - 数据新鲜度
 - 船型优先级
- 当前视口相关性
+- 全球当前状态可读性
 - 是否正在航行

 ### 3. 远景聚合
--- a/docs/plans/earth-vessel-tracking-plan.md
+++ b/docs/plans/earth-vessel-tracking-plan.md
@@ -1,6 +1,7 @@
 # 实时船只监控系统 — 实施计划

 **状态**：历史计划；实时 AIS 与聚合接口已由 [AIS 多源采集、冲突记录与聚合接口计划](/home/ray/dev/linkong/planet/docs/plans/earth-vessel-ais-aggregation-plan.md) 接管
+**更新**：`0.70.0` 起 Earth 船只展示使用 `vessel_current_state` 全球当前状态快照；本文中按当前视口 bbox 驱动显示的 LOD 设想仅作为历史记录。
 **创建日期**：2026-04-27
 **优先数据源**：BarentsWatch AIS（免费但需要 OAuth client credentials）→ AISStream realtime；AISHub / MarineTraffic 保留为付费备选

@@ -194,9 +195,9 @@ GeoJSON Feature 格式：
 |---------|---------|
 | > 400 | 默认渲染当前接口返回的全部船只；如性能不足，再引入可配置 LOD 上限 |
 | 200–400 | 默认渲染当前接口返回的全部船只；如性能不足，再引入可配置 LOD 上限 |
-| < 200 | 渲染当前视口 bbox 内全部船只 |
+| < 200 | 历史设想：渲染当前视口 bbox 内全部船只；当前实现仍使用全球当前状态快照 |

-前端根据相机位置动态计算 bbox，附加到 API 请求中。
+该视口驱动方案已撤回。当前前端使用全球 bbox 请求 `/api/v1/vessels/snapshot`，旋转和缩放不触发船只重拉。

 #### 2.4 图层集成

--- a/docs/technical/en/README.md
+++ b/docs/technical/en/README.md
@@ -38,6 +38,7 @@ This is the current Intelligent Planet documentation entry point. Docs are organ
 - [Datasource Collector Settings and Connectivity](/home/ray/dev/linkong/planet/docs/technical/en/datasource-collector-settings-connectivity.md): datasource catalog, collector settings, connectivity validation, and credentials
 - [Datasource API Performance](/home/ray/dev/linkong/planet/docs/technical/en/backend-datasources-api-performance.md): DataSources list API performance and caching
 - [Data Jobs and Outbox Architecture](/home/ray/dev/linkong/planet/docs/technical/en/data-job-earth-sync-architecture.md): PostgreSQL job queue, outbox, listener, and Kafka / Spark evolution boundaries
+- [Backend Enum and String Compatibility Contract](/home/ray/dev/linkong/planet/docs/technical/en/backend-enum-contracts.md): stable protocol states, historical string compatibility, and Earth news decision boundaries
 - [Shared Location Resolution Pipeline Development Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-development.md): location resolver / pipeline interfaces, registries, and extension points
 - [News Live Streams Collector Format](/home/ray/dev/linkong/planet/docs/technical/en/earth-news-live-streams-collector-format.md): news, live stream, and media collection payload conventions
 - [Docs Gatekeeper Development Guide](/home/ray/dev/linkong/planet/docs/technical/en/docs-gatekeeper-development.md): backend Docs catalog, Markdown content loading, and Gatekeeper permission groups
--- a/docs/technical/en/backend-collectors.md
+++ b/docs/technical/en/backend-collectors.md
@@ -93,7 +93,9 @@ The CelesTrak TLE collector prefers the complete `active` catalog. If CelesTrak
 | BarentsWatch AIS | vessel | AIS vessel positions, speed, heading, MMSI, and related fields | Collector settings |
 | AISStream Vessels | vessel_ais | AIS WebSocket realtime stream, written to the raw observation layer and displayed through aggregation | Collector settings |

-AIS vessel collectors use a different persistence path from regular `CollectedData` collectors. BarentsWatch, AISStream, and custom `vessel_ais` sources write into the AIS raw observation layer first, then the aggregation service merges those observations into the GeoJSON and detail payloads used by the Earth vessel layer. This preserves source, transport, field conflicts, and observation time instead of letting one realtime source overwrite the final display table.
+AIS vessel collectors use a different persistence path from regular `CollectedData` collectors. BarentsWatch, AISStream, and custom `vessel_ais` sources write into the AIS raw observation layer and also upsert `vessel_current_state`: one row per MMSI with the latest position, speed, course, navigation state, vessel type, name, and source metadata. This preserves raw observation history for tracks, audit, and situational analysis while letting the Earth vessel layer read the current-state table instead of scanning historical AIS rows.
+
+`vessel_current_state` only lets newer observations overwrite dynamic position fields; static fields such as name and vessel type are merged by non-empty value and source priority. Earth snapshots return only vessels inside the freshness window, keeping high-frequency AIS history out of the display path.

 Earth boundaries are no longer data collectors. They are Earth static rendering assets: the Earth Assets settings panel owns source configuration, and `/api/v1/earth/boundaries/*` builds `frontend/public/earth/data/boundaries/earth-boundaries-china-pov-v1.pmtiles`. When no high-precision PMTiles artifact is available locally, the frontend uses the bundled low-precision GeoJSON fallback and does not write boundary records to `CollectedData`.

@@ -339,32 +341,18 @@ AIS observations do not directly replace final vessel records. They are first sa
 - Dynamic fields such as position, speed, and course are selected by freshness and source priority.
 - Static fields prefer non-empty values; conflicting candidates are recorded for detail and diagnostics views.

-Earth vessel rendering now consumes the bounded snapshot endpoint and realtime delta channel:
+Earth vessel rendering now consumes the current-state snapshot endpoint:

 ```http
-GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
+GET /api/v1/vessels/snapshot?bbox=-180,-85.05112878,180,85.05112878&zoom=12&limit=3000
 GET /api/v1/visualization/vessels/{mmsi}
 GET /api/v1/visualization/vessels/{mmsi}/track
 GET /api/v1/visualization/vessels/{mmsi}/conflicts
 ```

-`/api/v1/vessels/snapshot` requires `bbox` and `zoom`, defaults to `limit=1000`, and caps `limit` at `5000`. It prefers aggregated `ais_raw_observations`; when the current raw window is empty, it can fall back to the latest legacy `vessel_position` / `vessel_static` rows and marks that path with `diagnostics.legacy_fallback_used`. The old `/api/v1/visualization/geo/vessels` route has been removed.
+`/api/v1/vessels/snapshot` requires `bbox` and `zoom`, and caps `limit` at `5000`. The Earth frontend uses a global bbox for current state and does not refetch on camera viewport changes. The endpoint reads `vessel_current_state` and reports `diagnostics.source = "vessel_current_state"`. The old `/api/v1/visualization/geo/vessels` route has been removed.

-Realtime deltas are sent through the `/ws` `vessels` channel. Clients must subscribe with the current viewport:
-
-```json
-{
-  "type": "subscribe",
-  "data": {
-    "channel": "vessels",
-    "bbox": [120.8, 30.7, 122.1, 31.8],
-    "zoom": 12,
-    "limit": 1000
-  }
-}
-```
-
-The backend stores lightweight subscription filters per connection and only sends vessel updates that match the subscriber bbox. Collector broadcasts enter a 1-second throttle queue; within each flush window, only the latest update per MMSI is retained.
+High-frequency AIS updates must not become per-delta full-layer rebuilds. If Earth uses the `/ws` `vessels` channel, it should send low-frequency reload/dirty hints and let the frontend merge snapshot refreshes. Tracks and conflicts still read historical facts through the single-vessel APIs.

 ### Layer APIs And Global Stats

--- a/docs/technical/en/backend-enum-contracts.md
+++ b/docs/technical/en/backend-enum-contracts.md
@@ -0,0 +1,50 @@
+# Backend Enum and String Compatibility Contract
+
+Planet keeps finite, stable protocol states in `backend/app/core/enums.py`. Databases and APIs continue to store and return lowercase strings. Enums provide internal type safety, validation, and deduplication without requiring a migration to database enum types.
+
+## Selection Rules
+
+A value should become an enum only when it is finite and stable, invalid outside the known set, and compared, sorted, or branched on by multiple modules. Typical examples are job states, AI Playground message roles and states, user roles, alert states, log levels, news importance, and Breaking states.
+
+The following must remain configurable strings:
+
+- news categories and tags;
+- provider, model, datasource, collector, news source, and Feed identifiers;
+- extensible incident and anomaly types; and
+- user-authored and free-form text.
+
+## Boundary Conversion
+
+Services should use `StrEnum` internally. Database writes and external responses use `.value`, preserving existing strings such as `JobStatus.RUNNING.value == "running"`.
+
+Use the compatibility parser when reading historical database values, JSON, or external input:
+
+```python
+status = parse_enum(JobStatus, raw_status, JobStatus.FAILED)
+```
+
+Known historical strings normalize to enum members. Empty values use the explicit default. Unknown values emit a warning and safely fall back instead of breaking historical reads. Pydantic request fields may use enums directly so invalid protocol values return `422`. Ordinary String and JSON database columns must not be converted to SQLAlchemy Enum.
+
+## Earth News Decisions
+
+Earth news decisions live in `backend/app/services/earth_news_classification.py`:
+
+- category answers what the story is and remains configurable;
+- importance answers whether it has long-term value; and
+- Breaking answers whether it must temporarily jump ahead.
+
+Importance levels are fixed:
+
+| Level | Score |
+|---|---:|
+| `low` | 0–34 |
+| `medium` | 35–59 |
+| `high` | 60–79 |
+| `critical` | 80–100 |
+
+Breaking rules use the typed `BreakingRule` structure. Levels, scopes, sources, and TTLs are managed by the public classification module. `earth_news.py` remains responsible for fetching, parsing, orchestration, and serialization.
+
+## Regression Prevention
+
+When adding or changing protocol states, check `app/core/enums.py` first and do not redefine duplicate `Literal` aliases, status sets, or normalization helpers in business modules. Add enum value and boundary contracts to `tests/test_enum_contracts.py`, and preserve API strings and database representation.
+
--- a/docs/technical/en/datasource-collector-settings-connectivity.md
+++ b/docs/technical/en/datasource-collector-settings-connectivity.md
@@ -318,10 +318,10 @@ Connectivity validation and actual collection are separate actions. A banner suc
 The new vessel list entry point is no longer the legacy `/api/v1/visualization/geo/vessels` route. Earth initial state should call:

 ```http
-GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
+GET /api/v1/vessels/snapshot?bbox=-180,-85.05112878,180,85.05112878&zoom=12&limit=3000
 ```

-That endpoint prefers local aggregated `ais_raw_observations`; when the current raw window is empty, it can fall back to the latest legacy `vessel_position` / `vessel_static` rows and exposes that through `diagnostics.legacy_fallback_used`. Realtime updates use the `/ws` `vessels` channel; subscriptions must include `bbox`, `zoom`, and `limit`. The server filters updates per connection and merges collector broadcasts every second, keeping only the latest position per MMSI.
+That endpoint reads `vessel_current_state`, returning the latest point per MMSI inside the freshness window. Raw `ais_raw_observations` remain available for tracks, audit, and situational analysis, but the display endpoint no longer scans and aggregates history on the fly. Earth sends a global bbox rather than the current camera viewport. If the `/ws` `vessels` channel is connected, it should act as a reload/dirty hint for merged refreshes, not as a per-AIS-delta full-layer rebuild path.

 ## Custom REST / WebSocket Mapping Runtime

--- a/docs/technical/en/earth-frontend-context.md
+++ b/docs/technical/en/earth-frontend-context.md
@@ -179,9 +179,15 @@ The `earth:compute-center-location-saved` reconciliation pipeline is deliberatel

 ### AIS Vessel Layer

-The vessel layer now uses `/api/v1/vessels/snapshot` for the initial viewport snapshot and the `/ws` `vessels` channel for realtime deltas. Snapshot requests must include `bbox`, `zoom`, and a bounded `limit`; the backend defaults to `limit=1000` and caps it at `5000`. WebSocket subscriptions must include the same viewport fields so the server can filter updates per connection.
+The vessel layer uses `/api/v1/vessels/snapshot` for a global current-state snapshot. Earth sends the global bbox `[-180,-85.05112878,180,85.05112878]`, the current `zoom`, and `limit=3000` when the layer opens. It does not repeatedly refetch by camera viewport, and globe rotation or zoom does not reconnect a vessel WebSocket subscription.

-The legacy `/api/v1/visualization/geo/vessels` route has been removed. Frontend code should fetch a snapshot for the current viewport when the layer opens, then subscribe to `vessels` deltas. After map pan or zoom, reload the snapshot and send a fresh vessels subscription. The backend only falls back to legacy `vessel_position` / `vessel_static` rows when the current raw window is empty; frontend code can detect that state through `diagnostics.legacy_fallback_used`.
+The backend snapshot endpoint still requires `bbox`, but the Earth runtime treats it as the global current-state entry point. It reads `vessel_current_state`, returning one latest point per MMSI within the freshness window, and no longer scans or aggregates historical `ais_raw_observations` for the display layer. Raw AIS history remains available for tracks, audit, and situational analysis.
+
+Vessel markers are rendered through `createInteractableLayer()` as batched `THREE.Points`, with `cluster` and `avoidance` explicitly disabled. Dense waterways may overlap. Dragging or inertial rotation skips hover picking; normal hover uses screen-space nearest-point picking. Do not reconnect vessels to dynamic screen clustering or per-frame Points rebuilds, because those interaction costs are what make a 3000-marker layer feel heavy.
+
+If the `/ws` `vessels` channel is used by Earth, it should be a low-frequency reload/dirty hint only. Do not create multiple viewport subscriptions, and do not turn every AIS delta into a full layer rebuild.
+
+The legacy `/api/v1/visualization/geo/vessels` route has been removed. Frontend code should keep using `PATHS.vesselsApi` and can verify the current-state path through `diagnostics.source == "vessel_current_state"`.

 The new layer API family is `/api/v1/layers/*`, which separates map rendering payloads from aggregate panel statistics. Layer requests must include `bbox`, `zoom`, and a bounded `limit`; responses include `visible_count`, `returned_count`, and `diagnostics`, where `degraded`, `truncated`, and `limit_clamped` are the frontend signals for fallback UI. Right-side aggregate panels should not sum the layer response. They should read `/api/v1/data-products` or `/api/v1/data-products/{product_id}/status`, because those statistics stay global and do not change with the viewport.

--- a/docs/technical/en/earth-layer-style-reference.md
+++ b/docs/technical/en/earth-layer-style-reference.md
@@ -193,13 +193,13 @@ The land/ocean base is an Earth base-map asset and preloads at startup; the "Bor
 | Vessel renderOrder | local `VESSEL_RENDER_ORDER` | `4.4` | Normal marker and interactive overlay |
 | Vessel track renderOrder | `VESSEL_RENDER_ORDER - 0.1` | `4.3` | Below vessel markers |
 | Vessel point pixel size | local `VESSEL_POINT_SIZE` | `34` | Shared size for normal markers and hover / locked overlays |
-| Default vessel render cap | `VESSEL_CONFIG.maxRenderedMarkers` | `0` | `0` means the frontend does not clip by default; positive values send `limit` and clip markers |
+| Default vessel render cap | `VESSEL_CONFIG.maxRenderedMarkers` | `3000` | Default `limit` sent to `/api/v1/vessels/snapshot` for the global current-state snapshot; the backend cap remains `5000` |
 | Vessel texture canvas size | local `VESSEL_ATLAS_CELL_SIZE` | `128` | Canvas point texture |
 | Course bucket count | local `VESSEL_COURSE_BINS` | `32` | Moving vessels are bucketed by COG to reduce draw calls while preserving direction |
 | Vessel hover picking throttle | local `VESSEL_HOVER_PICK_INTERVAL_MS` | `100` | `main.js` hover picking |
 | Vessel screen hit radius | local `VESSEL_POINTER_RADIUS_PX` | `22` | `main.js` screen-space picking |

-AIS vessel markers use batched `THREE.Points`, not one `THREE.Sprite` per vessel. Moving vessels stay triangular, anchored or slow vessels stay circular, and hover / locked states add a same-size glow overlay. Vessel type color and info-card type text must come from the same normalized result: `vessels.js` reads both backend `vessel_type_name` and AIS numeric `vessel_type`, derives the color-driving `type`, then exposes `vessel_type_display` for the info card, hover summary, and search results.
+AIS vessel markers use batched `THREE.Points`, not one `THREE.Sprite` per vessel. Moving vessels stay triangular, anchored or slow vessels stay circular, and hover / locked states add a same-size glow overlay. Vessels explicitly disable `cluster` and `avoidance`; dense areas may overlap and must not be reattached to dynamic screen clustering. Vessel type color and info-card type text must come from the same normalized result: `vessels.js` reads both backend `vessel_type_name` and AIS numeric `vessel_type`, derives the color-driving `type`, then exposes `vessel_type_display` for the info card, hover summary, and search results.

 ## Compute Centers

--- a/docs/technical/en/earth-news-sources.md
+++ b/docs/technical/en/earth-news-sources.md
@@ -80,6 +80,8 @@ Each item includes:

 Official data, e-commerce metrics, major platforms, and numeric business signals increase importance. Press releases start with a lower baseline and rise only when they match stronger platform, amount, M&A, or regulatory signals.

+Importance levels are fixed: `low` 0–34, `medium` 35–59, `high` 60–79, and `critical` 80–100. Category, importance, and Breaking decisions are centralized in `earth_news_classification.py`. Category keys and tags remain configurable, while importance and Breaking protocol states use shared enums. Databases and APIs continue to store compatible lowercase strings.
+
 ## Configuration and Cache

 `GET /api/v1/earth/news-sources` returns the default or saved configuration. `PUT /api/v1/earth/news-sources` saves it, increments `cache_version`, and clears the process region cache. `POST /api/v1/earth/news-sources/reset` restores defaults. `POST /api/v1/earth/news-sources/test` tests one RSS/Atom/Aggregated source without writing news items.
@@ -107,6 +109,27 @@ The Web Earth category chips only store the current browser preference; changing

 Source testing only proves that a specific RSS/Atom/XML feed can be parsed. It does not mean those items have already been written to the news table or are visible in the current region/category view. Saving or resetting news sources increments the configuration version and clears cache; if an enabled feed has no recent stored items, the next `earth-feed` request supplements from RSS so newly enabled sources such as 36Kr and Ebrun are not masked by fresh Google News rows.

+## Breaking News Insertion
+
+The news system keeps three separate decisions:
+
+- **Category**: what the story is about, such as business, military, or disaster.
+- **Importance**: whether the story has long-term value, stored as `importance_score / importance_level`.
+- **Breaking**: whether the story must temporarily jump ahead, stored in `location_meta.news_meta.breaking_*`.
+
+Breaking metadata does not add physical columns. It remains in `location_meta.news_meta`:
+
+- `breaking_level`: `none / watch / breaking / critical`.
+- `breaking_scope`: `regional / global`.
+- `breaking_reasons`: rule or operator reasons.
+- `breaking_source`: `rules / ai / manual / multi_source`.
+- `breaking_confidence`: 0 to 1.
+- `breaking_expires_at`: expiration timestamp.
+
+The backend performs the ordering, so Web and UE clients do not need to reorder items. Active `critical`, `breaking`, and `watch` items appear before normal items in that order. Once expired, the item falls back to normal ordering without being deleted or changing its long-term importance score.
+
+`breaking_scope = global` bypasses the active region and can appear in every regional feed. `regional` breaking follows the normal active-region-plus-global rule. The response `filters` includes `has_breaking` and `highest_breaking_level`, which the Earth client uses to apply restrained panel and card styling.
+
 ## Connectivity Monitoring

 `POST /api/v1/earth/news-sources/test` tests one source and writes the result to `earth_news_sources.health[source_id]`. Normal RSS/Atom fetches update the same health map.
--- a/docs/technical/en/earth-render-layer-order.md
+++ b/docs/technical/en/earth-render-layer-order.md
@@ -27,8 +27,10 @@ Note: the layer control panel order and the registration / startup load order ar
 | 2.29 | Country border hover glow | `country-boundaries.js` | Hover radius + glow offset | `depthTest: false`, raycast disabled | Additive glow to reinforce border edge and terrain hover visibility. |
 | 2.3 | Country border hover line | `country-boundaries.js` | `hoverAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48` | `depthTest: false`, raycast disabled | Neon red-orange hover line; aligned with the normal borders and HD texture shell to avoid ghosting or floating; China and Taiwan share the same highlight group. |
 | 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. |
+| 3-4.5 | BGP collectors, event rings, and event markers | `bgp.js`, `interactable.js` | Collector markers use `BGP_COLLECTOR_RENDER_ORDER = 4.4`; event markers use `BGP_EVENT_RENDER_ORDER = 4.5`; overlays remain in BGP-owned groups | Screen-space Interactable picking; BGP collectors/events may use collision avoidance where appropriate | BGP collectors share the surface-facility band with vessels; BGP events share the compute-center band. |
+| 4.3 | AIS vessel track lines | `vessels.js` | `VESSEL_RENDER_ORDER - 0.1`; `CONFIG.earthRadius + VESSEL_CONFIG.track.altitudeOffset` | Follows vessel selection, not independently picked | Recent track for the selected vessel, below vessel markers. |
+| 4.4 | AIS vessel markers | `vessels.js`, `interactable.js` | `VESSEL_RENDER_ORDER`; business radius `CONFIG.earthRadius + VESSEL_CONFIG.altitudeOffset`; normal markers are bucketed `THREE.Points`, hover / locked states are single-point overlays | `depthTest: true`; `main.js` uses screen-space picking for front-facing markers; `cluster: false` and `avoidance: false` | Moving vessels use triangular point textures, anchored / slow vessels use dots. Dense waterways may overlap and do not participate in dynamic screen clustering, avoiding Points rebuilds during rotation. |
+| 4.5 | Compute centers | `compute-centers.js`, `interactable.js` | `COMPUTE_CENTER_RENDER_ORDER` | Screen-space Interactable picking, with surface-icon collision handling | Surface facilities, below satellites. |
 | 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 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. |
--- a/docs/technical/en/platform-data-flows.md
+++ b/docs/technical/en/platform-data-flows.md
@@ -118,12 +118,12 @@ sequenceDiagram

 ## Vessels

-Vessel data shows AIS vessels, navigation state, vessel-type legend, and source health. Earth rendering uses position snapshots and static vessel information; it should not render every raw AIS observation.
+Vessel data shows AIS vessels, navigation state, vessel-type legend, and source health. Earth rendering uses the `vessel_current_state` current-state snapshot; it should not render every raw AIS observation.

 - **Collection entry**: AIS sources, BarentsWatch vessels.
 - **Fact table**: `collected_data` or AIS raw observation tables.
- **Derived tables**: `vessel_static`, `vessel_position`, `ais_raw_observations`, `ais_source_health`.
- **API**: vessel visualization API returns current vessel markers and detail fields.
+- **Derived tables**: `vessel_current_state`, `vessel_static`, `vessel_position`, `ais_raw_observations`, `ais_source_health`.
+- **API**: `/api/v1/vessels/snapshot` returns current vessel markers and detail fields; the Earth frontend uses a global bbox for the global current-state view.
 - **Delete semantics**: deleting any vessel source lets owned projections broadcast `vessels` with `clear_then_reload`.
 - **Common failure**: the count panel changes but vessels remain. Summary and layer data are separate; Earth should clear objects based on layer updates.

--- a/docs/technical/zh/README.md
+++ b/docs/technical/zh/README.md
@@ -38,6 +38,7 @@
 - [数据源、采集器设置与连接验证](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)：数据源目录、采集器设置、连接验证和凭证链路
 - [数据源 API 性能](/home/ray/dev/linkong/planet/docs/technical/zh/backend-datasources-api-performance.md)：DataSources 列表接口性能和缓存策略
 - [数据作业与 Outbox 技术架构](/home/ray/dev/linkong/planet/docs/technical/zh/data-job-earth-sync-architecture.md)：PostgreSQL 作业队列、outbox、listener 和 Kafka / Spark 演进边界
+- [后端枚举与字符串兼容契约](/home/ray/dev/linkong/planet/docs/technical/zh/backend-enum-contracts.md)：稳定协议状态、历史字符串兼容和 Earth 新闻判定边界
 - [通用位置估算管线开发说明](/home/ray/dev/linkong/planet/docs/technical/zh/location-pipeline-development.md)：location resolver / pipeline 的接口、注册表和扩展方式
 - [新闻直播采集格式](/home/ray/dev/linkong/planet/docs/technical/zh/earth-news-live-streams-collector-format.md)：新闻、直播和媒体采集 payload 约定
 - [Docs Gatekeeper 开发说明](/home/ray/dev/linkong/planet/docs/technical/zh/docs-gatekeeper-development.md)：后端文档目录、正文读取和 Gatekeeper 权限组实现
--- a/docs/technical/zh/backend-collectors.md
+++ b/docs/technical/zh/backend-collectors.md
@@ -94,7 +94,9 @@ CelesTrak TLE 采集优先拉取完整 `active` 目录。如果 CelesTrak 返回
 | BarentsWatch AIS | vessel | 船只位置、航速、航向、MMSI 等 AIS 数据 | 依采集器配置 |
 | AISStream Vessels | vessel_ais | AIS WebSocket 实时流，写入原始观测层并由聚合接口展示 | 依采集器配置 |

-AIS 船只类采集器和其它 `CollectedData` 采集器的落库路径不同。BarentsWatch、AISStream 和自定义 `vessel_ais` 源都会进入 AIS 原始观测层，随后由聚合服务合并成 Earth 船只图层使用的 GeoJSON 和详情数据。这样做可以保留来源、传输方式、字段冲突和观测时间，避免某个实时源直接覆盖最终展示表。
+AIS 船只类采集器和其它 `CollectedData` 采集器的落库路径不同。BarentsWatch、AISStream 和自定义 `vessel_ais` 源都会进入 AIS 原始观测层，同时 upsert `vessel_current_state` 当前状态表：每个 MMSI 只保留一行最新位置、航速、航向、状态、船型、名称和来源元数据。这样既保留原始观测历史用于轨迹、审计和态势分析，又让 Earth 船只图层读取当前状态表，不在展示接口里扫描历史 AIS 记录。
+
+`vessel_current_state` 的动态位置只允许被更新观测时间更晚的数据覆盖；名称、船型等静态字段按非空和来源优先策略合并。Earth snapshot 默认只返回有效窗口内的当前船只，避免高频 AIS 历史数据影响地球渲染性能。

 智能星球国界不再属于采集器体系。它是智能星球静态渲染资产，由控制台 `运维与配置 -> 智能星球内容 -> 国界精度` 维护源配置，并由 `/api/v1/earth/boundaries/*` 构建 `frontend/public/earth/data/boundaries/earth-boundaries-china-pov-v1.pmtiles`。本地没有高精 PMTiles 时，前端会使用仓库内置的低精度 GeoJSON 作为 fallback，不会向 `CollectedData` 写入国界记录。

@@ -369,32 +371,18 @@ AIS 观测写入后不会直接替换最终船只记录，而是先保存为 raw
 - 位置、速度、航向等动态字段会按 freshness 和来源优先级选择。
 - 静态字段优先保留非空值；冲突候选会记录到详情接口，便于排查多源差异。

-Earth 船只展示现在使用受控快照接口和实时增量通道：
+Earth 船只展示现在使用当前状态快照接口：

 ```http
-GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
+GET /api/v1/vessels/snapshot?bbox=-180,-85.05112878,180,85.05112878&zoom=12&limit=3000
 GET /api/v1/visualization/vessels/{mmsi}
 GET /api/v1/visualization/vessels/{mmsi}/track
 GET /api/v1/visualization/vessels/{mmsi}/conflicts
 ```

-`/api/v1/vessels/snapshot` 必须携带 `bbox` 和 `zoom`，默认 `limit=1000`，最大 `limit=5000`。它优先消费 `ais_raw_observations` 聚合结果；当当前 raw 窗口为空时，会受控回退到 legacy `vessel_position` / `vessel_static` 最新点，并在 `diagnostics.legacy_fallback_used` 中标明。旧 `/api/v1/visualization/geo/vessels` 路由已移除。
+`/api/v1/vessels/snapshot` 必须携带 `bbox` 和 `zoom`，后端最大 `limit=5000`。Earth 前端使用全球 bbox 读取当前状态，不随相机视口变化反复请求。接口消费 `vessel_current_state`，并在 `diagnostics.source` 返回 `vessel_current_state`；旧 `/api/v1/visualization/geo/vessels` 路由已移除。

-实时增量通过 `/ws` 的 `vessels` channel 推送。客户端订阅时必须带当前视口：
-
-```json
-{
-  "type": "subscribe",
-  "data": {
-    "channel": "vessels",
-    "bbox": [120.8, 30.7, 122.1, 31.8],
-    "zoom": 12,
-    "limit": 1000
-  }
-}
-```
-
-后端按连接保存轻量订阅条件，只向 bbox 命中的连接发送船只更新。collector 广播会先进入 1 秒节流队列，同一 MMSI 在一个 flush 周期内只保留最新位置，避免高频实时流拖垮 WebSocket。
+高频 AIS 更新不要直接推送成每条 delta 的整层重建。`/ws` 的 `vessels` channel 如用于 Earth，应广播低频 reload/dirty 提示，由前端合并刷新 snapshot；轨迹和冲突详情仍按单船接口读取历史事实。

 ### 图层接口与全量统计分离

--- a/docs/technical/zh/backend-enum-contracts.md
+++ b/docs/technical/zh/backend-enum-contracts.md
@@ -0,0 +1,50 @@
+# 后端枚举与字符串兼容契约
+
+Planet 后端使用 `backend/app/core/enums.py` 统一维护有限、稳定、会参与协议判断的状态值。数据库和 API 仍保存、输出小写字符串；枚举用于代码内部的类型安全、校验和去重，不要求数据库迁移为 SQL Enum。
+
+## 使用准则
+
+适合枚举的值必须有限且稳定，非法值应被拒绝或安全回退，并且多个模块会比较、排序或分支处理该值。典型示例包括任务状态、AI Playground 消息角色和状态、用户角色、告警状态、日志级别、新闻重要度和 Breaking 状态。
+
+以下值必须保持可配置字符串：
+
+- 新闻分类与标签。
+- Provider、模型、数据源、collector、新闻源和 Feed 标识。
+- 可扩展的 incident/anomaly 类型。
+- 用户输入和自由文本。
+
+## 边界转换
+
+服务内部优先使用 `StrEnum`。写入数据库或输出外部协议时使用 `.value`，继续得到现有字符串，例如 `JobStatus.RUNNING.value == "running"`。
+
+读取历史数据库、JSON 或外部输入时使用：
+
+```python
+status = parse_enum(JobStatus, raw_status, JobStatus.FAILED)
+```
+
+合法历史字符串会归一为枚举；空值使用明确默认值；未知值记录 warning 并安全回退，不阻断历史数据读取。Pydantic 请求字段可以直接使用枚举，让非法协议值返回 `422`。普通 String/JSON 数据库列不改成 SQLAlchemy Enum。
+
+## Earth 新闻判定
+
+Earth 新闻判定集中在 `backend/app/services/earth_news_classification.py`：
+
+- 分类回答“新闻是什么”，分类 key 仍是可配置字符串。
+- 重要度回答“长期是否值得关注”。
+- Breaking 回答“短时间内是否必须插队”。
+
+重要度等级固定为：
+
+| 等级 | 分数 |
+|---|---:|
+| `low` | 0–34 |
+| `medium` | 35–59 |
+| `high` | 60–79 |
+| `critical` | 80–100 |
+
+Breaking 规则使用带类型的 `BreakingRule`；等级、范围、来源和 TTL 由公开分类模块统一管理。`earth_news.py` 只负责抓取、解析、编排与序列化。
+
+## 防回退检查
+
+新增或修改协议状态时，先检查 `app/core/enums.py`，不要在业务模块重复定义 `Literal`、状态集合或 normalize helper。枚举值与边界行为应补充到 `tests/test_enum_contracts.py`，并保证 API 字符串和数据库表示不变。
+
--- a/docs/technical/zh/datasource-collector-settings-connectivity.md
+++ b/docs/technical/zh/datasource-collector-settings-connectivity.md
@@ -320,10 +320,10 @@ AISStream 使用 WebSocket 实时流，采集器只写入 `ais_raw_observations`
 新版本不再使用 legacy `/api/v1/visualization/geo/vessels` 作为船只列表入口。Earth 初始状态应调用：

 ```http
-GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
+GET /api/v1/vessels/snapshot?bbox=-180,-85.05112878,180,85.05112878&zoom=12&limit=3000
 ```

-该接口优先查询本地 `ais_raw_observations` 聚合结果；当当前 raw 窗口为空时，会受控回退到 legacy `vessel_position` / `vessel_static` 最新点，并通过 `diagnostics.legacy_fallback_used` 暴露。实时更新走 `/ws` 的 `vessels` channel，订阅时必须提供 `bbox`、`zoom` 和 `limit`。服务端按连接过滤 bbox，并对 collector 广播做 1 秒合并，同一 MMSI 只推送最新位置。
+该接口查询 `vessel_current_state` 当前状态表，只返回有效窗口内每个 MMSI 的最新点；原始 `ais_raw_observations` 继续保留给轨迹、审计和态势分析，但不再由展示接口临时扫描聚合。Earth 前端统一传全球 bbox，不随当前镜头视口反复请求。实时更新如接入 `/ws` 的 `vessels` channel，应作为 reload/dirty 提示触发合并刷新，不能把每条 AIS delta 直接变成整层重建。

 ## 自定义 REST / WebSocket 映射运行时

--- a/docs/technical/zh/earth-frontend-context.md
+++ b/docs/technical/zh/earth-frontend-context.md
@@ -312,9 +312,8 @@ AIS 船只图层入口：

 船只图层当前负责：

- 请求 `/api/v1/vessels/snapshot` 获取当前视口初始快照；请求必须携带 `bbox`、`zoom`，并传入受控 `limit`
- 通过 `/ws` 的 `vessels` channel 订阅后续增量；订阅 payload 同样必须携带当前视口 `bbox`、`zoom`、`limit`
- 将聚合后的 AIS GeoJSON 转为地球局部坐标 marker 数据；后端默认 `limit=1000`，最大 `limit=5000`
+- 请求 `/api/v1/vessels/snapshot` 获取全局当前状态快照；Earth 前端统一传全球 bbox、当前 `zoom` 和 `limit=3000`
+- 将 `vessel_current_state` 当前状态 GeoJSON 转为地球局部坐标 marker 数据；历史 AIS 原始观测只用于轨迹、审计和态势分析
 - 通过 `createInteractableLayer()` 注册 Interactable 图标层
 - 用按航向分桶的 `THREE.Points` 批量渲染普通船只 marker
 - 按船型映射颜色；`vessels.js` 会用 `vessel_type_name` 和 AIS `vessel_type` 数字共同归一化船型
@@ -330,6 +329,8 @@ AIS 船只图层入口：
 - moving 船只按 `VESSEL_COURSE_BINS` 做航向分桶。
 - 每个批次是一组 `THREE.PointsMaterial`，位置和颜色写入 `BufferGeometry` attribute。
 - 普通态不带 glow；hover / locked 时才在相同点位叠加带 glow 的单点 overlay。
+- `cluster: false` 且 `avoidance: false`，密集海域允许重叠，不参与动态屏幕聚类。
+- 地球旋转和缩放不会重新请求船只，也不会按当前镜头 bbox 重连 WebSocket。

 方向标准以 AIS `course / cog` 为准：从正北开始顺时针。普通态和交互态都通过同一套 canvas 旋转规则生成纹理，避免 hover 后箭头方向和原 marker 不一致。

@@ -337,7 +338,7 @@ AIS 船只图层入口：

 AISStream 的 `PositionReport` 常带实时位置和 `MetaData.ShipName`，但船型通常来自低频 `ShipStaticData.Type`。后端会把 `MetaData.ShipName` 补进船名，并将类型码映射为 Cargo / Tanker / Passenger / Fishing / Military；仍缺失的船型需要等待静态 AIS 消息或后续船舶资料 enrichment，不能在前端凭颜色之外的信息臆造细分类。

-旧 `/api/v1/visualization/geo/vessels` 路由已移除。前端打开船只图层时应先按当前视口拉一次 `/api/v1/vessels/snapshot`，再用 WebSocket 接收同一视口内的 upsert 增量；地图拖动或缩放后应重新拉取 snapshot 并重发 vessels 订阅。后端只在当前 raw 窗口为空时受控回退到 legacy `vessel_position` / `vessel_static`，前端可通过 `diagnostics.legacy_fallback_used` 识别该状态。
+旧 `/api/v1/visualization/geo/vessels` 路由已移除。前端打开船只图层时只应拉取一次全局 `/api/v1/vessels/snapshot`；API 参数里的 bbox 是后端接口约束，Earth 运行时传全球范围，不表示当前镜头视口。`/ws` 的 `vessels` channel 如启用，只作为低频 reload/dirty 提示，不能把每条 AIS delta 直接变成整层重建。后端通过 `diagnostics.source == "vessel_current_state"` 暴露当前状态链路。

 新的图层接口族是 `/api/v1/layers/*`，用于把地图渲染数据和聚合面板统计分开。地图层请求必须带 `bbox`、`zoom` 和受控 `limit`，响应会返回 `visible_count`、`returned_count` 和 `diagnostics`，其中 `degraded/truncated/limit_clamped` 用于前端提示降级。右侧聚合统计不要从图层响应累加，应读取 `/api/v1/data-products` 或 `/api/v1/data-products/{product_id}/status`，因为这些统计保持全量/全局口径，不随当前视口变化。

--- a/docs/technical/zh/earth-layer-style-reference.md
+++ b/docs/technical/zh/earth-layer-style-reference.md
@@ -205,7 +205,7 @@
 | 船只 renderOrder | local `VESSEL_RENDER_ORDER` | `4.4` | 普通 marker 和交互 overlay |
 | 船只轨迹 renderOrder | `VESSEL_RENDER_ORDER - 0.1` | `4.3` | 低于船只 marker |
 | 船只点像素尺寸 | local `VESSEL_POINT_SIZE` | `34` | 普通 marker 与 hover / locked overlay 共享尺寸 |
-| 船只默认渲染上限 | `VESSEL_CONFIG.maxRenderedMarkers` | `0` | `0` 表示不在前端默认裁剪；正数才会给接口传 `limit` 并裁剪 marker |
+| 船只默认渲染上限 | `VESSEL_CONFIG.maxRenderedMarkers` | `3000` | 前端请求全局当前状态快照时传给 `/api/v1/vessels/snapshot` 的默认 `limit`；后端上限仍为 `5000` |
 | 船只纹理画布尺寸 | local `VESSEL_ATLAS_CELL_SIZE` | `128` | canvas 点纹理 |
 | 航向分桶数 | local `VESSEL_COURSE_BINS` | `32` | moving 船只按 COG 分桶，降低 draw call 同时保留方向 |
 | 船只 hover 拾取节流 | local `VESSEL_HOVER_PICK_INTERVAL_MS` | `100` | `main.js` hover picking |
@@ -216,7 +216,7 @@
 | locked 船只透明度 | inline | `1` | locked overlay |
 | 船型颜色 | `VESSEL_CONFIG.colors.*` | cargo / tanker / passenger / fishing / military / other | `PointsMaterial.vertexColors` 和 overlay texture |

-AIS 船只普通态使用批量 `THREE.Points`，不是逐船 `THREE.Sprite`。航行船只保持三角形，停泊或低速船只保持圆点；普通态不带 glow，hover / locked 时在同一屏幕尺寸上叠加带 glow 的单点 overlay。AIS 航向按 `course / cog` 从正北顺时针解释，普通态和交互态必须使用同一套 canvas 旋转规则。
+AIS 船只普通态使用批量 `THREE.Points`，不是逐船 `THREE.Sprite`。航行船只保持三角形，停泊或低速船只保持圆点；普通态不带 glow，hover / locked 时在同一屏幕尺寸上叠加带 glow 的单点 overlay。AIS 航向按 `course / cog` 从正北顺时针解释，普通态和交互态必须使用同一套 canvas 旋转规则。船只显式关闭 `cluster` 和 `avoidance`，密集区域可以重叠，不能重新接入动态屏幕聚类。

 船型颜色和详情卡船型文本必须来自同一套归一化结果：`vessels.js` 同时读取后端 `vessel_type_name` 和 AIS 数字 `vessel_type`，先得到颜色用的 `type`，再生成 `vessel_type_display` 给详情卡、hover 和搜索使用。

--- a/docs/technical/zh/earth-news-sources.md
+++ b/docs/technical/zh/earth-news-sources.md
@@ -80,6 +80,8 @@ Earth 态势新闻使用 `/api/v1/news/earth-feed` 输出给前端。新闻源

 官方数据源、电商指标、平台型公司、量化指标会提高重要度；企业公告基础权重较低，只有命中大平台、金额、并购、监管等信号时提升。

+重要度等级固定为：`low` 0–34、`medium` 35–59、`high` 60–79、`critical` 80–100。分类、重要度和 Breaking 的计算集中在 `earth_news_classification.py`；分类 key 和标签仍可配置，重要度与 Breaking 协议状态使用统一枚举，数据库和 API 继续保存兼容的小写字符串。
+
 ## 配置与缓存

 `GET /api/v1/earth/news-sources` 返回默认或已保存配置。`PUT /api/v1/earth/news-sources` 保存配置并递增 `cache_version`，同时清理进程内 region cache。`POST /api/v1/earth/news-sources/reset` 恢复默认源。`POST /api/v1/earth/news-sources/test` 只测试单个 RSS/Atom/Aggregated 源，不写入新闻表。
@@ -107,6 +109,27 @@ Web 星球端的新闻类型按钮只保存当前浏览器的显示偏好；偏

 源测试只证明当前 RSS/Atom/XML 能解析到条目，不等于这些条目已经入库展示。展示链路还会检查区域、类型过滤和数据库新鲜度。保存或重置新闻源会递增配置版本并清理缓存；如果当前启用的 Feed 子项在库里没有近期条目，下一次 `earth-feed` 请求会补抓，避免新启用的 36氪、亿邦被旧 Google News 缓存挡住。

+## Breaking News 插队
+
+新闻体系里有三套互不替代的判断：
+
+- **分类**：新闻是什么，例如商业、军事、灾害。
+- **重要度**：长期是否值得关注，写入 `importance_score / importance_level`。
+- **Breaking**：短时间内是否必须插队，写入 `location_meta.news_meta.breaking_*`。
+
+Breaking 不新增表字段，继续保存在 `location_meta.news_meta`：
+
+- `breaking_level`：`none / watch / breaking / critical`。
+- `breaking_scope`：`regional / global`。
+- `breaking_reasons`：触发原因。
+- `breaking_source`：`rules / ai / manual / multi_source`。
+- `breaking_confidence`：0 到 1。
+- `breaking_expires_at`：过期时间。
+
+排序由服务端完成，客户端和 UE 不需要自己重排。未过期的 `critical`、`breaking`、`watch` 会依次排在普通新闻前面；过期后只回到普通排序，不删除新闻，也不改变长期重要度。
+
+`breaking_scope = global` 的新闻会无视当前区域，进入所有区域的 feed；`regional` 只遵守当前区域加 `global` 的普通区域规则。接口响应的 `filters` 会返回 `has_breaking` 和 `highest_breaking_level`，星球端据此给新闻面板和卡片加克制的背景/边框状态。
+
 ## 连通性监测

 `POST /api/v1/earth/news-sources/test` 会测试单个源并把结果写入 `earth_news_sources.health[source_id]`。实际 RSS/Atom 抓取也会更新同一份健康状态。
--- a/docs/technical/zh/earth-render-layer-order.md
+++ b/docs/technical/zh/earth-render-layer-order.md
@@ -30,7 +30,7 @@
 | 3 | 卫星 footprint 填充 / Iridium coverage ring | `satellites.js`, `iridium-footprint-adapter.js` | `GROUND_FOOTPRINT_RENDER_ORDER` | depth-tested；Iridium adapter 的 fill / ring 也使用同一 renderOrder | Footprint 在 land / texture / terrain 和国界线之上，但在算力中心和卫星之下。 |
 | 3-4.5 | BGP 观测站、事件扩散圈和事件 marker | `bgp.js`, `interactable.js` | BGP 观测站和事件 marker 均使用 `Interactable` 批量 `THREE.Points`；事件 marker 使用 `BGP_EVENT_RENDER_ORDER = 4.5`；观测站主图标使用 `BGP_COLLECTOR_RENDER_ORDER = 4.4` 和 `BGP_CONFIG.collectorAltitudeOffset = 0.2`；事件 overlay 进入 `bgp-event-overlay-layer`；观测站 halo 和覆盖扇形进入 `bgp-collector-radar-layer` | BGP 事件和观测站都通过 `Interactable` 屏幕空间 picking，并参与同坐标避让 | BGP 观测站主图标与船只同层；BGP 事件与算力中心同层；向外扩散圈、观测站雷达/覆盖动画继续由 BGP 业务逻辑驱动。 |
 | 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.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；`cluster: false` 且 `avoidance: false` | 航行船只用三角点纹理，停泊/低速用圆点；密集海域允许重叠，不参与动态屏幕聚类，避免旋转时重建 Points；低于算力中心 `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..25`，关闭真实高度或传播失败时回退到 `fallbackAltitudeOffset = 8` | 屏幕空间卫星拾取 | 位于卫星点下方。 |
 | 6 | 卫星点 | `satellites.js` | 与卫星背景点使用同一压缩高度 / fallback 高度 | 屏幕空间卫星拾取 | 卫星点压过 footprint 和算力中心。 |
--- a/docs/technical/zh/platform-data-flows.md
+++ b/docs/technical/zh/platform-data-flows.md
@@ -118,12 +118,12 @@ sequenceDiagram

 ## 船舶链路

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

 - **采集入口**：AIS sources、BarentsWatch vessels。
 - **事实表**：`collected_data` 或 AIS 原始观测表。
- **派生表**：`vessel_static`、`vessel_position`、`ais_raw_observations`、`ais_source_health`。
- **接口**：vessels visualization API 返回当前船只 marker 和必要详情。
+- **派生表**：`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 为准清空对象。

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

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

 ## Timeline

 | Version | Type | Branch | Commit | Summary |
 | --- | --- | --- | --- | --- |
+| `0.70.0` | feature | `dev` | `pending` | 新增后端枚举契约治理、Earth 新闻分类/Breaking 链路和船只当前状态快照，清理错误视口刷新逻辑并同步双语文档 |
 | `0.69.0` | feature | `dev` | `pending` | 新增 Earth 新闻源治理、新闻类型服务端过滤、观测日志 fingerprint 聚合和 TV/HLS 播放恢复改进 |
 | `0.68.1` | bugfix | `dev` | `pending` | 修复 CelesTrak fallback group/cache 恢复链路，并让数据源任务日志可按 task_id / datasource_id 搜索 |
 | `0.68.0` | feature | `dev` | `pending` | 新增数据源任务队列实时指标、AIS 大表分批删除和智能星球可插拔聚类策略，并让新设备启动前同步前端依赖 |