release: bump version to 0.52.0

docs/technical/en/backend-collectors.md

@@ -309,17 +309,50 @@ 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 still reads vessel data from:
+Earth vessel rendering now consumes the bounded snapshot endpoint and realtime delta channel:
 
 ```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` merges raw observation aggregation with the legacy BarentsWatch latest-position tables so adding AISStream does not hide historical BarentsWatch-only vessels.
+`/api/v1/vessels/snapshot` requires `bbox` and `zoom`, defaults to `limit=1000`, and caps `limit` at `5000`. It reads only aggregated `ais_raw_observations`; it no longer merges legacy `vessel_position` / `vessel_static` rows. The old `/api/v1/visualization/geo/vessels` endpoint has been removed and returns `410 Gone`.
+
+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.
+
+### Layer APIs And Global Stats
+
+Earth is moving to two API families:
+
+```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/*` is for aggregate panels and keeps a global statistics scope independent of the map bbox. `/api/v1/layers/*` is for map rendering, requires `bbox` and `zoom`, defaults to `limit=1000`, and caps `limit` at `5000`; low zoom falls back to a smaller response cap and reports `degraded`, `truncated`, `limit_clamped`, and `stats_scope=viewport` in `diagnostics`. Non-vessel layers currently reuse the existing GeoJSON converters before the guard layer; future product-specific queries can push bbox filtering deeper.
 
 ## X. Collector Settings And Connectivity Validation
 
@@ -390,4 +423,12 @@ curl -X POST http://localhost:8000/api/v1/datasources/1/trigger \
   -H "Authorization: Bearer <token>"
 ```
 
+Batch collection uses:
+
+```http
+POST /api/v1/datasources/trigger-batch
+```
+
+The request body may pass `source_ids` for selected rows. Without `source_ids`, the backend filters by `product`, `module`, `is_active`, `run_status`, `collected`, `credential_status`, and `q`. The endpoint skips disabled sources, sources already running without `force`, and sources still inside their frequency window, then returns `triggered`, `skipped`, and `failed` groups.
+
 **Core file**: `backend/app/api/v1/datasources.py`