release: bump version to 0.49.0

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/technical/zh/datasource-collector-settings-connectivity.md

@@ -62,7 +62,7 @@
 当前行为：
 
 - `collector_credentials` tab 展示为“采集器设置”。
-- 下拉框列出所有内置采集器。
+- 下拉框列出内置采集器，并支持维护合并到内置数据的自定义补充源。
 - 下拉框右侧只有一个插头图标按钮，用于健康检查。
 - 下拉框下方用状态标签展示：
   - `需要凭证` / `无需凭证`
@@ -72,6 +72,8 @@
   - 是否覆盖 endpoint
 - 需要凭证的采集器把凭证卡片放在基础配置上方。
 - 不需要凭证的采集器只显示基础配置。
+- AISStream 采集器使用 WebSocket 语义，状态会显示为连接中、实时接收、重连或停止，不使用固定百分比表达完成度。
+- 自定义源入口放在采集器设置内，不在数据源目录里重复提供编辑入口；数据源目录只保留总览、运行和只读抽屉。
 
 连接按钮使用内联 Tabler 风格插头图标，来源语义对应 `plug-connected`，避免继续使用刷新图标表达连接动作。
 
@@ -286,6 +288,100 @@ AISStream 使用 WebSocket 实时流，采集器只写入 `ais_raw_observations`
 - 船型通常来自低频 `ShipStaticData.Type`；后端会把 AIS 数字类型码映射为 Cargo / Tanker / Passenger / Fishing / Military。
 - 如果某艘船尚未收到静态消息，聚合结果的船型仍可能是 `Other`，后续由 v5 船舶资料 enrichment 补齐。
 
+连接验证会读取保存配置、环境变量和 `~/.zshrc` 中的 `AISSTREAM_API_KEY`。正式采集时，推荐把 API Key 保存到采集器设置；如果只写在 `~/.zshrc`，需要确认后端进程实际继承了该变量，否则连接验证可能可用但 collector 运行时拿不到 key。
+
+## 自定义 REST / WebSocket 映射运行时
+
+文件：
+
+- [custom_datasource_runtime.py](/home/ray/dev/linkong/planet/backend/app/services/custom_datasource_runtime.py)
+- [datasource_mapping.py](/home/ray/dev/linkong/planet/backend/app/services/datasource_mapping.py)
+
+自定义源现在不是独立的新数据孤岛，而是作为内置数据源的补充源写入目标 schema。当前最完整的目标是 `vessel_ais`：自定义 REST 或 WebSocket 源经过确定性 mapping 后写入 AIS raw observations，再通过 `vessels` WebSocket channel 推送给 Earth。
+
+### 配置语义
+
+关键字段：
+
+- `source_type`：`rest` / `http` / `websocket` / `ws`。
+- `endpoint`：REST 使用 `http(s)://`，WebSocket 使用 `ws(s)://`。
+- `auth_type`：`none`、`bearer`、`api_key`、`basic`。
+- `headers`：静态请求头。
+- `auth_config`：token、API key、basic 用户名密码，API key 支持 header 或 query。
+- `config.target_schema`：例如 `vessel_ais`。
+- `config.delivery_mode`：REST 默认 `polling`，WebSocket 默认 `realtime_stream`。
+- `config.merge_target_source`：记录该自定义源补充哪个内置数据，例如 `barentswatch_vessels`。
+
+REST runner 支持：
+
+- `GET` / `POST`
+- query params
+- JSON body
+- headers 和 auth 注入
+- active mapping 写入目标 schema
+
+WebSocket runner 支持：
+
+- endpoint 格式校验
+- headers 和 auth 注入
+- 可选 `ws_subscribe_message`
+- `ws_message_path` / `ws_items_path` 提取消息主体或数组
+- 断线重连
+- `debug_max_messages` 调试上限
+- 后台 stream start / stop / status
+
+相关 API：
+
+```http
+POST /api/v1/datasources/custom/sample
+GET  /api/v1/datasources/target-schemas
+POST /api/v1/datasources/{config_id}/run-mapped
+POST /api/v1/datasources/{config_id}/stop-mapped
+GET  /api/v1/datasources/{config_id}/mapped-status
+DELETE /api/v1/datasources/configs/{config_id}?delete_mappings=true&delete_source_data=true
+```
+
+`run-mapped?background=true` 只对 WebSocket 源有意义，会启动后台 stream。REST 源仍是一次性采集。
+
+### 删除与数据清理
+
+删除自定义源时有三种层级：
+
+- 只删除配置：保留 mapping 和历史数据。
+- 删除配置和 mapping：同时删除该配置的 mapping 模板。
+- 删除配置、mapping 和该源数据：删除该源写入的 `collected_data`、`ais_raw_observations` 和 `ais_source_health`。
+
+如果删除的是 `vessel_ais` 自定义源数据，后端会向 `vessels` channel 广播 `reload_required`，提示 Earth 重新拉取船只聚合结果。legacy `vessel_position` 不按自定义源直接删除，因为它没有可靠的 source 归因。
+
+### 本地 AIS mock WebSocket
+
+文件：
+
+- [mock-ais-ws-server.ts](/home/ray/dev/linkong/planet/scripts/mock-ais-ws-server.ts)
+
+运行方式：
+
+```bash
+bun run mock:ais-ws
+```
+
+mock 服务持续发送 AIS-like JSON，用于验证“WebSocket 自定义源 -> mapping -> AIS raw observation -> `vessels` channel -> Earth 船只 upsert”链路。典型配置：
+
+```json
+{
+  "source_type": "websocket",
+  "endpoint": "ws://localhost:8787",
+  "config": {
+    "target_schema": "vessel_ais",
+    "delivery_mode": "realtime_stream",
+    "merge_target_source": "barentswatch_vessels",
+    "ws_message_path": "$.data",
+    "ws_items_path": "$.vessels[*]",
+    "ws_reconnect": true
+  }
+}
+```
+
 ## 凭证教程
 
 文件：
@@ -347,6 +443,7 @@ BarentsWatch `client_secret` 保存时有特殊处理：
 当前已经支持的凭证 provider：
 
 - `barentswatch`
+- `aisstream`
 - `spacetrack`
 
 其他 `requires_credentials=true` 的采集器如果还没有 provider，会返回“凭证链路尚未接入”，前端显示 `不可用`。