release: bump version to 0.53.0

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

@@ -176,7 +176,7 @@ freshness:
 
 ## 聚合接口
 
-状态更新：开发期已直接切换到新船只快照接口。旧 `/api/v1/visualization/geo/vessels` 不再兼容返回数据，而是返回 `410 Gone`；新的 Earth 船只首屏应调用 `/api/v1/vessels/snapshot`，实时更新走 `/ws` 的 `vessels` 订阅。
+状态更新：开发期已直接切换到新船只快照接口。旧 `/api/v1/visualization/geo/vessels` 路由已移除；新的 Earth 船只首屏应调用 `/api/v1/vessels/snapshot`，实时更新走 `/ws` 的 `vessels` 订阅。
 
 现有展示接口应逐步改为消费聚合服务，而不是自己直接拼 `VesselPosition + VesselStatic`。
 
@@ -346,11 +346,11 @@ VesselFinder 等服务里的船只图片不属于 AIS 实时数据本身。图
 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` 全量返回。
 
-### v3.1 — 聚合完整性修复（已被新快照接口取代）
+### v3.1 — 聚合完整性修复（已被受控 fallback 取代）
 
-原目标是先保证“所有已采集到的船都能显示”，BarentsWatch 不因为接入 AISStream 而被 raw observation 聚合结果遮蔽。开发期产品尚未上线后，决策调整为直接淘汰 legacy 船只表兜底：船只快照只读取 `ais_raw_observations` 聚合结果，旧 `vessel_position + vessel_static` 不再合并进 `/api/v1/vessels/snapshot`。
+原目标是先保证“所有已采集到的船都能显示”，BarentsWatch 不因为接入 AISStream 而被 raw observation 聚合结果遮蔽。当前实现已经移除旧 `/geo/vessels` 路由，船只入口统一为 `/api/v1/vessels/snapshot`。snapshot 优先读取 `ais_raw_observations` 聚合结果；当当前 raw 窗口为空时，才受控回退到 `vessel_position + vessel_static` 最新点，并通过 `diagnostics.legacy_fallback_used` 标记。
 
-因此以下 legacy merge 要求作废，保留在文档中只作为历史决策记录：
+因此以下旧 `/geo/vessels` 全量 merge 要求作废，保留在文档中只作为历史决策记录：
 
 1. `/geo/vessels` 必须合并 raw observation 聚合结果和 legacy latest position 结果。
 2. raw 与 legacy 同一 MMSI 同时存在时只显示一艘，优先使用 raw 聚合结果及其 `field_sources` / `selected_reasons`。
@@ -462,8 +462,8 @@ REST collector 的自然状态是 `fetch -> transform -> save -> progress 0..100
 - 明显异常位置不会进入默认展示轨迹，并会留下 `quality_flags`。
 - 同一时间窗口内多来源相近轨迹点只展示一个点。
 - AISStream 重连或回放导致的重复消息不会重复进入聚合结果。
-- `/api/v1/vessels/snapshot` 只读取 AIS raw observation 聚合结果；legacy latest position 不再参与船只快照。
-- `/api/v1/visualization/geo/vessels` 返回 `410 Gone`，客户端必须迁移到新 snapshot API。
+- `/api/v1/vessels/snapshot` 优先读取 AIS raw observation 聚合结果；当当前 raw 窗口为空时，允许受控 fallback 到 legacy latest position。
+- `/api/v1/visualization/geo/vessels` 路由已移除，客户端必须迁移到新 snapshot API。
 - AISStream 长连接收到新船、位置变化和航向变化后，会通过内部 `/ws` 的 `vessels` channel 推送增量。
 - AISStream streaming 状态不会显示成固定百分比完成进度条，也不会在收到一批消息后误报采集完成。
 - `mmsi`、`imo`、`callsign` 等身份编号在前端不显示千分位符。

docs/plans/earth-vessel-rendering-performance-plan.md

@@ -216,7 +216,7 @@ hover、locked、dimmed 可通过更新少量 instance attribute 实现，不再
 
 ### 1. 请求视口范围
 
-前端请求 `/api/v1/vessels/snapshot` 时必须带上当前视口 `bbox`、`zoom` 和受控 `limit`，减少无关船只。旧 `/api/v1/visualization/geo/vessels` 已下线并返回 `410 Gone`。
+前端请求 `/api/v1/vessels/snapshot` 时必须带上当前视口 `bbox`、`zoom` 和受控 `limit`，减少无关船只。旧 `/api/v1/visualization/geo/vessels` 路由已移除。
 
 ### 2. 后端排序策略
 

docs/plans/earth-vessel-tracking-plan.md

@@ -120,11 +120,12 @@ CREATE UNIQUE INDEX ON vessel_latest(mmsi);
 
 #### 1.3 API 端点
 
-```
-GET /api/v1/visualization/geo/vessels
-    ?bbox=lon_min,lat_min,lon_max,lat_max   # 视口裁剪
+```http
+GET /api/v1/vessels/snapshot
+    ?bbox=lon_min,lat_min,lon_max,lat_max   # 必填，视口裁剪
+    ?zoom=12                                # 必填，当前缩放
     ?type=cargo,tanker,passenger             # 船型过滤
-    ?limit=0                                 # 可选；不传或 0 表示不裁剪数量
+    ?limit=1000                              # 默认 1000，最大 5000
 → GeoJSON FeatureCollection（Point）
 
 GET /api/v1/visualization/vessels/{mmsi}           # 单船详情
@@ -163,7 +164,7 @@ GeoJSON Feature 格式：
 - 后端 BarentsWatch collector 继续以 HTTP polling 方式采集
 - AISStream 等实时源以独立 WebSocket collector 写入原始观测层
 - 展示接口从聚合服务读取当前船只视图，而不是由单个 collector 决定最终展示值
-- 前端默认不再给 `/geo/vessels` 传 `limit=5000`，`VESSEL_CONFIG.maxRenderedMarkers = 0` 表示不做前端数量裁剪；后续如性能不足再引入显式 LOD 上限
+- 旧 `/api/v1/visualization/geo/vessels` 路由已移除，前端必须使用受控 snapshot 接口。
 - marker 颜色、详情卡、hover 和搜索结果必须共享 `vessel_type_display` 船型归一化结果，避免 AIS 数字类型码已驱动颜色但卡片仍显示 `Other`
 - 前端是否升级为 WebSocket delta push 是独立优化，不影响后端采集器可以使用 WebSocket 接上游实时源
 

docs/plans/production-delivery-cicd-stabilization-plan.md

@@ -0,0 +1,55 @@
+# Planet 正式交付与 CI/CD 稳定化计划
+
+## Summary
+
+- CI/CD 平台采用 Gitea Actions，由自托管 `act_runner` 执行。
+- 正式交付目标采用 Kubernetes，端口、健康检查、重启和滚动发布交给 Service、Ingress、readiness/liveness probe。
+- Vite 继续保留，但只作为开发服务器和生产构建工具；生产运行 nginx 托管 `vite build` 产物。
+- 不新增 Webpack 双构建链。Electron 仅在离线桌面交付成为明确目标后再评估。
+
+## Key Changes
+
+- 生产镜像：
+  - frontend 多阶段构建，`bun install` + `bun run build`，最终 nginx 托管 `dist`。
+  - backend/aiprovider 移除 `--reload`，加入容器健康检查。
+  - 镜像标签使用 `<registry>/<namespace>/<service>:<git-sha>`，发布 tag 额外推 `vX.Y.Z`。
+- Kubernetes：
+  - 新增 Helm chart：`deploy/helm/planet`。
+  - frontend 暴露 Ingress；backend/aiprovider 默认 ClusterIP。
+  - PostgreSQL/Redis 默认外部依赖，`values.single-node.yaml` 提供演示/测试内置依赖。
+- Gitea Actions：
+  - `ci.yaml`：后端测试、前端构建、Docker build smoke、Helm render。
+  - `release.yaml`：构建并推送三类镜像。
+  - `deploy-staging.yaml`：部署 staging、等待 rollout、执行 smoke tests。
+- 开发脚本边界：
+  - `planet.sh` 保留为本地开发便利脚本。
+  - CI/CD 与正式部署不调用 `planet.sh start`。
+
+## Vite / Webpack / Electron Decision
+
+中肯结论：不要因为“企业生产环境”这件事去做 Webpack 版本；继续用 Vite，但把“开发服务器”和“生产构建/部署”分清楚。Electron 也不要现在做，除非正式版目标明确是离线桌面软件。
+
+Vite 可以用于生产构建。生产环境运行的是 `vite build` 产出的静态资源，不是 Vite dev server。当前项目已经使用 React + Vite + Bun、`import.meta.env`、`public/earth` 静态资产路径和大量 Three.js/ES module 资源引用。维护 Webpack 双构建链会显著增加路径、资源、环境变量和回归测试成本。
+
+如果未来客户环境确实要求更接近 Webpack 生态，优先做 Rsbuild/Rspack 技术 spike，而不是直接维护 Webpack 并行构建。Electron 适合离线运行、本地硬件/文件访问、系统托盘、自动更新和安装包分发；但 Planet 目前还包含 backend、database、Redis、AI Provider、Motion Agent 等服务编排，桌面壳不能解决正式交付的核心问题。
+
+## Test Plan
+
+- CI gates：
+  - `uv sync --group dev`
+  - `uv run pytest backend/tests/test_api.py backend/tests/test_realtime_sources.py -q`
+  - `cd frontend && bun install --frozen-lockfile && bun run build`
+  - Docker build frontend/backend/aiprovider
+  - `helm lint deploy/helm/planet`
+  - `helm template planet-staging deploy/helm/planet -f deploy/helm/planet/values.single-node.yaml`
+- Staging deployment:
+  - `helm upgrade --install planet-staging deploy/helm/planet --namespace planet-staging`
+  - 等待 frontend/backend/aiprovider rollout。
+  - smoke test frontend `/`、frontend `/health`、backend `/health`、aiprovider `/health`。
+
+## Acceptance Criteria
+
+- main/dev 提交能通过 CI。
+- 发布 workflow 能生成可追踪镜像。
+- staging 可从零部署并完成滚动升级。
+- 正式部署不依赖本机端口清理，也不运行 Vite dev server。