release: bump version to 0.52.0

docs/plans/earth-vessel-ais-aggregation-plan.md

@@ -176,10 +176,12 @@ freshness:
 
 ## 聚合接口
 
+状态更新：开发期已直接切换到新船只快照接口。旧 `/api/v1/visualization/geo/vessels` 不再兼容返回数据，而是返回 `410 Gone`；新的 Earth 船只首屏应调用 `/api/v1/vessels/snapshot`，实时更新走 `/ws` 的 `vessels` 订阅。
+
 现有展示接口应逐步改为消费聚合服务，而不是自己直接拼 `VesselPosition + VesselStatic`。
 
 ```text
-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
@@ -317,7 +319,7 @@ VesselFinder 等服务里的船只图片不属于 AIS 实时数据本身。图
 目标是让展示接口开始消费聚合结果，但前端形状保持兼容。
 
 1. 实现 AIS 聚合服务，先兼容读取现有表，再逐步切换到原始观测层。
-2. 将 `/geo/vessels` 和 `/vessels/{mmsi}` 改为走聚合服务。
+2. 将船只列表迁移到 `/api/v1/vessels/snapshot`，并让 `/vessels/{mmsi}` 走聚合服务。
 3. 将 `/vessels/{mmsi}/track` 改为走轨迹聚合逻辑。
 4. 返回 `field_sources`、`selected_reasons`、`quality_flags`、`conflict_count`。
 5. 加入 freshness fallback 和异常位置保护。
@@ -342,13 +344,13 @@ VesselFinder 等服务里的船只图片不属于 AIS 实时数据本身。图
 3. 聚合结果返回 `source_summary`，展示每艘船的来源、观测数量、最新观测时间、传输模式和消息类型。
 4. 保留 `field_sources` 和 `selected_reasons`，用于解释动态字段来自实时流、静态字段来自可用非空来源。
 5. 船名标准化会读取 AISStream `MetaData.ShipName`；船型展示会从 `vessel_type_name` 和 AIS 数字 `vessel_type` 共同归一化，保证 marker 颜色、详情卡、hover 和搜索结果一致。
-6. `/geo/vessels` 不再默认限制 5000 艘；不传 `limit` 或传 `limit=0` 表示全量返回，前端默认也不再二次裁剪到 5000。
+6. 当前实现已转向 `/api/v1/vessels/snapshot`：必须带 bbox / zoom，默认 `limit=1000`，最大 `limit=5000`，不再支持旧 `/geo/vessels` 全量返回。
 
-### v3.1 — 聚合完整性修复（v4 前置）
+### v3.1 — 聚合完整性修复（已被新快照接口取代）
 
-目标是先保证“所有已采集到的船都能显示”，BarentsWatch 不因为接入 AISStream 而被 raw observation 聚合结果遮蔽。
+原目标是先保证“所有已采集到的船都能显示”，BarentsWatch 不因为接入 AISStream 而被 raw observation 聚合结果遮蔽。开发期产品尚未上线后，决策调整为直接淘汰 legacy 船只表兜底：船只快照只读取 `ais_raw_observations` 聚合结果，旧 `vessel_position + vessel_static` 不再合并进 `/api/v1/vessels/snapshot`。
 
-当前风险是 `/geo/vessels` 只要 raw observation 聚合返回非空，就直接使用 raw 聚合结果，不再补读兼容层 `vessel_position + vessel_static`。如果 raw observation 中只存在 AISStream 的几百艘船，或 BarentsWatch 历史数据没有完整回填到 raw 层，最终 Earth 就会只显示 AISStream 子集。
+因此以下 legacy merge 要求作废，保留在文档中只作为历史决策记录：
 
 1. `/geo/vessels` 必须合并 raw observation 聚合结果和 legacy latest position 结果。
 2. raw 与 legacy 同一 MMSI 同时存在时只显示一艘，优先使用 raw 聚合结果及其 `field_sources` / `selected_reasons`。
@@ -416,7 +418,7 @@ REST collector 的自然状态是 `fetch -> transform -> save -> progress 0..100
    - `freshness.realtime_stream_seconds` / `polling_seconds` 必须为非负整数；
    - `mode=locked` 必须带非空 `locked_source`。
 4. 聚合服务 `vessel_ais_aggregation.py` 在 `_select_position_observation` 中按 `freshness` 把过期实时流降级到 stale 候选；在 `_select_static_field` 中按 `field_rules.mode = source_priority / locked / newest / non_empty` 选源。
-5. 聚合输出每条 vessel 携带 `aggregation_strategy_version`，并在 `/geo/vessels` GeoJSON properties + `/vessels/{mmsi}` 详情中暴露。
+5. 聚合输出每条 vessel 携带 `aggregation_strategy_version`，并在 `/api/v1/vessels/snapshot` GeoJSON properties + `/vessels/{mmsi}` 详情中暴露。
 6. API：
    - `GET /api/v1/vessel-aggregation/strategy`
    - `PUT /api/v1/vessel-aggregation/strategy`（校验失败 400）
@@ -460,8 +462,8 @@ REST collector 的自然状态是 `fetch -> transform -> save -> progress 0..100
 - 明显异常位置不会进入默认展示轨迹，并会留下 `quality_flags`。
 - 同一时间窗口内多来源相近轨迹点只展示一个点。
 - AISStream 重连或回放导致的重复消息不会重复进入聚合结果。
-- raw observation 聚合结果和 legacy latest position 结果会按 MMSI 合并，BarentsWatch-only 船只不会因为 AISStream 子集存在而消失。
-- 不传 `limit` 或传 `limit=0` 时，`/geo/vessels` 全量返回合并后的船只集合。
+- `/api/v1/vessels/snapshot` 只读取 AIS raw observation 聚合结果；legacy latest position 不再参与船只快照。
+- `/api/v1/visualization/geo/vessels` 返回 `410 Gone`，客户端必须迁移到新 snapshot API。
 - AISStream 长连接收到新船、位置变化和航向变化后，会通过内部 `/ws` 的 `vessels` channel 推送增量。
 - AISStream streaming 状态不会显示成固定百分比完成进度条，也不会在收到一批消息后误报采集完成。
 - `mmsi`、`imo`、`callsign` 等身份编号在前端不显示千分位符。