release: bump version to 0.52.0

docs/technical/zh/backend-collectors.md

@@ -336,17 +336,50 @@ AIS 观测写入后不会直接替换最终船只记录，而是先保存为 raw
 - 位置、速度、航向等动态字段会按 freshness 和来源优先级选择。
 - 静态字段优先保留非空值；冲突候选会记录到详情接口，便于排查多源差异。
 
-Earth 使用的接口仍是：
+Earth 船只展示现在使用受控快照接口和实时增量通道：
 
 ```http
-GET /api/v1/visualization/geo/vessels
+GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
 GET /api/v1/visualization/vessels/{mmsi}
 GET /api/v1/visualization/vessels/{mmsi}/track
 GET /api/v1/visualization/vessels/{mmsi}/conflicts
-GET /api/v1/visualization/vessels/aggregation/diagnostics
 ```
 
-`/geo/vessels` 会合并 raw observation 聚合结果和 legacy BarentsWatch latest position 结果，避免只接入 AISStream 后把历史 BarentsWatch 船只遮蔽掉。
+`/api/v1/vessels/snapshot` 必须携带 `bbox` 和 `zoom`，默认 `limit=1000`，最大 `limit=5000`。它只消费 `ais_raw_observations` 聚合结果，不再读取 legacy `vessel_position` / `vessel_static` 作为兜底。旧 `/api/v1/visualization/geo/vessels` 已下线并返回 `410 Gone`。
+
+实时增量通过 `/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。
+
+### 图层接口与全量统计分离
+
+Earth 后续迁移到两类接口：
+
+```http
+GET /api/v1/data-products
+GET /api/v1/data-products/{product_id}/status
+GET /api/v1/layers/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
+GET /api/v1/layers/cables?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
+GET /api/v1/layers/landing-points?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
+GET /api/v1/layers/satellites?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
+GET /api/v1/layers/bgp/anomalies?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
+GET /api/v1/layers/bgp/incidents?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
+GET /api/v1/layers/bgp/collectors?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
+```
+
+`/api/v1/data-products/*` 面向聚合面板，统计口径是全量/全局，不受地图 bbox 影响。`/api/v1/layers/*` 面向地图渲染，必须携带 `bbox` 和 `zoom`，默认 `limit=1000`，最大 `limit=5000`；低 zoom 会降级到更小的返回上限，并在 `diagnostics` 中暴露 `degraded`、`truncated`、`limit_clamped` 和 `stats_scope=viewport`。当前版本的非船只图层先复用已有 GeoJSON 转换再做保护层，后续可继续把 bbox 下推到各产品专用查询。
 
 ## 十、采集器设置与连接验证
 
@@ -418,4 +451,12 @@ curl -X POST http://localhost:8000/api/v1/datasources/1/trigger \
   -H "Authorization: Bearer <token>"
 ```
 
+批量采集使用：
+
+```http
+POST /api/v1/datasources/trigger-batch
+```
+
+请求体可以传 `source_ids` 精确触发选中项；如果不传 `source_ids`，后端按 `product`、`module`、`is_active`、`run_status`、`collected`、`credential_status` 和 `q` 过滤后触发。接口会跳过禁用源、正在运行且未 `force` 的源，以及未到频率窗口的源，并返回 `triggered`、`skipped`、`failed` 三组结果。
+
 **核心文件**: `backend/app/api/v1/datasources.py`