release: bump version to 0.56.0

docs/plans/README.md

@@ -19,7 +19,7 @@
 - [earth-mobile-drawer-ui-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-mobile-drawer-ui-plan.md)
 - [earth-compute-center-bgp-style-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-compute-center-bgp-style-plan.md)
 - [earth-renderer-architecture-separation-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-renderer-architecture-separation-plan.md)
-- [earth-country-boundary-overlay-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-country-boundary-overlay-plan.md)
+- [Earth 高精度国界静态瓦片计划](/home/ray/dev/linkong/planet/docs/plans/earth-high-precision-boundary-tiles-plan.md)
 - [earth-predicted-orbit-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-predicted-orbit-plan.md)
 - [earth-webgl-instancing-satellites-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-webgl-instancing-satellites-plan.md)
 - [earth-real-terrain-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-real-terrain-plan.md)

docs/plans/datasource-custom-api-mapping-plan.md

@@ -13,7 +13,7 @@
 | 采集时是否调用 LLM | 不调用；采集链路必须确定性、可审计、可复现 |
 | 自定义数据如何进入 Earth | 必须映射到已支持的目标 schema，或先进入通用数据沉淀 |
 | 外部凭证放置位置 | Settings / 外部集成统一管理 provider token；DataSources 引用 provider profile |
-| TimescaleDB | 放入 TODO；高频时序数据稳定后再评估迁移 |
+| TimescaleDB | 高频时序数据稳定后再评估迁移 |
 
 ---
 
@@ -57,7 +57,7 @@ flowchart LR
 | schema | 用途 | Earth 可视化 |
 |-------|------|-------------|
 | `vessel_ais` | 船只 AIS 位置、航速、航向、MMSI 等 | 进入船舶图层 |
-| `geo_points` | 通用点位数据，包含经纬度、名称、类型、时间 | 进入通用 geo layer（TODO） |
+| `geo_points` | 通用点位数据，包含经纬度、名称、类型、时间 | 未来进入通用 geo layer |
 | `news_events` | 新闻/事件类数据，带时间、地点、摘要、来源 | 复用新闻/事件链路 |
 | `compute_centers` | 算力中心、机房、数据中心数据 | 复用算力中心图层 |
 | `generic_records` | 未知结构化数据沉淀 | 不直接展示 |
@@ -294,7 +294,7 @@ PostgreSQL 可以承载当前规模的采集、关系查询、JSONB 沉淀和基
 - 查询模式还没稳定。
 - 需要快速迭代 schema 与 mapping。
 
-### TODO：TimescaleDB
+### TimescaleDB 后续评估
 
 以下条件满足后，再评估 TimescaleDB：
 
@@ -324,7 +324,7 @@ PostgreSQL 可以承载当前规模的采集、关系查询、JSONB 沉淀和基
 - Settings 中保存 provider credentials。
 - API 返回配置时必须 mask secret。
 - LLM prompt 只能包含脱敏 sample 和 schema 说明。
-- 后续 TODO：引入字段级加密或 KMS。
+- 后续可引入字段级加密或 KMS。
 
 ### Mapping 治理
 

docs/plans/earth-high-precision-boundary-tiles-plan.md

@@ -0,0 +1,132 @@
+# Earth High Precision Boundary Tiles Plan
+
+## Status
+
+Planning revised after visual review. The previous hand-authored China claim-line / point-buffer approach is rejected and must not be implemented.
+
+Implemented separately:
+
+- 地表 hover 三模式已实现。
+
+Still planned:
+
+- 权威 China POV 数据包。
+- OSM / coastline 高精度离线构建。
+- 版本化静态矢量瓦片输出。
+- 前端 bbox/tile/LRU 高精度加载器。
+
+## Summary
+
+Earth 国界线目标从“明显提升”升级为 **最高精度档按真实地图源一比一还原**：
+
+- 高缩放时不能使用当前 `countries-admin0.min.geojson` 这种低精度简化线。
+- 最高 tile zoom 必须忠实保留选定权威矢量源的原始折点，不做视觉平滑，不做人工凭感觉补线。
+- 藏南、阿克赛钦等争议陆地直接作为中国国家面的一部分表达；hover 只显示普通 `中国 / CHN`，不显示特殊区域名。
+- 九段线 / 十段线必须来自官方标准地图口径或经地理配准校核后的权威矢量数据；不能手工目测画线，不能把马来西亚、菲律宾等周边陆地或近岸底盘划入中国面。
+
+方案仍采用 **离线构建 + 静态矢量瓦片**。低缩放加载简化 base line；高缩放按当前视野 bbox 加载高精度 boundary tiles。第一版不使用 Redis，依靠 Nginx 静态服务、浏览器 HTTP cache 和前端 LRU。
+
+## Data Source and Policy
+
+- 基础陆地国界使用 OSM `boundary=administrative` + `admin_level=2`，并补充高精度 coastline，避免只靠粗糙国家面导致海岸线缺失。
+- China POV 覆盖数据必须独立成包，构建时优先级高于 OSM 原始归属：
+  - 藏南 union 到中国面，同时从印度面 subtract。
+  - 阿克赛钦 union 到中国面，同时从相关邻接面 subtract。
+  - 台湾、澎湖、钓鱼岛及附属岛屿、赤尾屿、东沙、西沙、中沙、南沙等作为中国国家面/岛礁面的一部分进入 hover index。
+  - 岛礁很小时可有最小可交互面，但 tooltip 仍是 `中国 / CHN`，不展示“某特殊区域归属”标签。
+- 九段线 / 十段线是独立 maritime claim line 图层：
+  - 只渲染 dashed line，不参与国家陆地面。
+  - 不用于吞并周边国家陆地或近岸水域。
+  - 坐标必须来自官方标准地图、权威矢量数据，或从官方示意图配准后人工复核，不接受手工猜测坐标。
+- 必须保留 OSM 数据归因：`© OpenStreetMap contributors, ODbL`。
+
+## Precision Requirements
+
+- 最高精度档的验收口径是 **source-faithful**，不是“看起来更细”：
+  - 对高精度源线，最高 zoom tile 不允许 Douglas-Peucker 简化。
+  - 坐标量化精度至少保留到 `1e-5` 度级别，构建时不得把经纬度粗暴四舍五入到低精度。
+  - 球面渲染只允许 densify 长边来贴合地球曲率；不允许 CatmullRom、Bezier 或任何会改变边界走向的平滑。
+  - 海岸/边界红框类区域必须与源地图折线逐点对齐；若有偏差，只能追溯并替换数据源，不能靠渲染平滑掩盖。
+- 低缩放允许简化，但必须有误差预算：
+  - base line 只服务远景识别。
+  - 中 zoom tile 可简化到屏幕误差低于 `0.5px`。
+  - 最高 zoom tile 使用无简化或近零误差版本。
+
+## Implementation Plan
+
+### 1. Data pipeline
+
+新增边界构建脚本，使用 `/home/ray/.local/bin/uv` 运行：
+
+1. 读取 OSM PBF 或预处理后的 admin-0 边界 / coastline GeoJSON。
+2. 读取 China POV override package。
+3. 使用可靠几何库做 union / difference / validity repair，禁止手写 polygon overlay。
+4. 生成中国国家面时直接合并藏南、阿克赛钦和相关岛礁；从相邻国家面扣除同一区域。
+5. 单独读取官方口径九段线 / 十段线矢量，生成 claim-line tiles。
+6. 输出：
+   - 低精度 global base line。
+   - 无简化 high-precision hover polygon index。
+   - 高精度静态瓦片：`frontend/public/earth/data/boundaries/v1/{z}/{x}/{y}.geojson`。
+   - 海上断续线瓦片：`frontend/public/earth/data/boundaries/v1/china-claims/{z}/{x}/{y}.geojson`。
+   - manifest，记录数据源、覆盖规则版本、构建时间、简化误差和 attribution。
+
+### 2. Tile levels and size budget
+
+- Earth zoom `< 1.6`：只显示 global base line 和低精度 claim line。
+- Earth zoom `1.6-2.8`：加载 tile zoom `4-5`。
+- Earth zoom `2.8-4.0`：加载 tile zoom `6-7`。
+- Earth zoom `> 4.0`：加载 tile zoom `8-10`，使用最高精度无简化折线。
+- 单 tile gzip 目标 `20-80KB`，但最高精度档优先保证几何真实性；若超限，优先提高 tile zoom 或拆 tile，而不是简化真实线。
+
+### 3. Frontend loading model
+
+`country-boundaries.js` 拆成 base layer、tile layer 和 China claim layer：
+
+- 首屏加载 base line + hover index，不阻塞 Earth 初始化。
+- 高缩放时根据 camera 可见范围计算经纬 bbox，再转换为 Web Mercator tile keys。
+- bbox 由屏幕中心、四角和边中点 raycast 得到，并扩张 `10-20%` 作为预取范围。
+- 处理反经线，必要时拆成两个 bbox。
+- 视野变化请求 debounce `150-250ms`。
+- 拖拽/惯性旋转中不每帧请求；缩放档或 tile key 集合没变时不刷新。
+- 加载当前视野 tile，并预取一圈邻接 tile。
+- base line 在高精度 tile 到达后降低 opacity，避免双线。
+
+### 4. Caching and memory control
+
+- 前端维护 `tileCache`、`inFlightTiles` 和 LRU 使用顺序。
+- tile cache 上限建议 `120-180` 个 tile；超过后释放最旧 tile 的 `BufferGeometry`。
+- Nginx 为 `/earth/data/boundaries/` 设置长缓存：
+  - `Cache-Control: public, max-age=31536000, immutable`
+  - gzip 包含 JSON。
+- tile URL 包含版本目录，例如 `v1`；数据更新时改版本目录破浏览器缓存。
+- 第一版不使用 Redis。只有改成动态裁剪 API、多 POV 同 URL、或压测证明静态服务成为瓶颈时再考虑 Redis。
+
+## Acceptance Criteria
+
+1. 最高 zoom 的海岸线和国界线与选定源地图逐点一致，不再只是“明显提升”。
+2. 红框类海岸/边界细节在最高 zoom 下不能出现肉眼可见的低精度折线、直线切边或圆滑失真。
+3. 藏南、阿克赛钦 hover 命中普通 `中国 / CHN`；印度或其他邻接国家不再包含这些区域。
+4. 钓鱼岛、赤尾屿、南海诸岛代表点 hover 命中普通 `中国 / CHN`。
+5. 九段线 / 十段线位置与权威来源一致，不压入马来西亚、菲律宾等周边陆地或错误包围近岸底盘。
+6. 首屏不加载全球超高精度整包。
+7. 高缩放只请求当前视野附近 tile，快速旋转不会出现请求风暴。
+8. 回到已访问区域命中前端 cache 或浏览器 cache。
+9. 国界图层开关、hover 高亮、移动端中心国家高亮、悬停提示三模式保持可用。
+
+## Verification
+
+- 构建阶段：
+  - 几何 validity check 全通过。
+  - China POV 代表点测试全部返回 `CHN`。
+  - 相邻国家代表点不得被 China override 误吞。
+  - 最高 zoom tile 抽样与源数据做坐标级 diff，确认未简化。
+- 前端阶段：
+  - 在 `frontend` 运行 `/home/ray/.bun/bin/bun run build`。
+  - 浏览器 DevTools 验证低缩放无高精度 tile 请求，高缩放请求数量受控，重复视野走 cache。
+  - 用截图中的红框区域、南海断续线、藏南、钓鱼岛、赤尾屿、南海诸岛做手动视觉验收。
+
+## Sources and Assumptions
+
+- 产品默认采用中国标准地图/公开地图合规口径；若后续支持多 POV，必须通过版本化数据目录隔离，不能让同一 URL 返回不同政治口径。
+- 当前仓库没有足够权威和足够精细的 China POV / 九段线矢量源，因此不能直接凭现有低精度 GeoJSON 完成“一比一还原”。
+- 实施前必须先引入或生成可审计的高精度源数据包；没有源数据时，只能实现加载框架，不能伪造边界。

docs/plans/earth-interactable-layer-plan.md

@@ -273,7 +273,7 @@ hover / locked 使用少量 overlay：
 
 - 算力中心保留现有业务 icon，但接入统一 hover / locked / glow。（已完成）
 - 登陆点曾接入同一套 `Points` 渲染，但 pin 类 SVG 在地球边缘会被深度测试裁切；当前保留专用 `THREE.Sprite`，并使用 canvas 生成黄色扁平球，贴到海缆层级。
-- TODO：登陆点暂不迁移到完整 Interactable。后续若要统一交互接口，优先考虑 Sprite-backed adapter，只对齐 `getMarkers()`、`getPointerIntersections()`、`setMarkerState()`、`updateVisualState()` 等外观协议，不强行复用 `THREE.Points`、atlas 和跨图层避让。
+- 登陆点暂不迁移到完整 Interactable。后续若要统一交互接口，优先考虑 Sprite-backed adapter，只对齐 `getMarkers()`、`getPointerIntersections()`、`setMarkerState()`、`updateVisualState()` 等外观协议，不强行复用 `THREE.Points`、atlas 和跨图层避让。
 - 检查图例、搜索和 info-card 是否只依赖业务 payload，而不是依赖渲染对象类型。
 
 ### Phase 4：形成 Earth 图标层规范

docs/plans/earth-surface-hover-info-plan.md

@@ -0,0 +1,105 @@
+# Earth Surface Hover Info Plan
+
+Status: Implemented.
+
+## Goal
+
+为 Earth 桌面和 compact 鼠标地表 hover 增加可配置的提示内容，让用户可以选择只看国家信息、只看位置数据，或同时查看国家和经纬海拔。
+
+当前地表 hover 已经具备两类信息：
+
+- 命中国家时显示国家、ISO、大洲，并高亮国界。
+- 未命中国家时显示纬度、经度、海拔。
+
+新方案把这两类信息合并成一个清晰的设置项：`悬停提示`。
+
+## User-facing behavior
+
+设置项放在桌面设置和移动端设置的 `视图` 区，使用分段控件：
+
+- `国家`：陆地命中国家时显示国家名、ISO、大洲；太平洋等海洋区域不显示地表 tooltip。
+- `位置`：陆地和海洋都显示纬度、经度、海拔；不触发国家 tooltip 和国家边界 hover 高亮。
+- `完整`：陆地命中国家时显示国家信息和纬度、经度、海拔；海洋区域显示纬度、经度、海拔。
+
+默认值为 `完整`，因为它保留现有国家识别价值，同时满足 hover 时查看经纬海拔的需求。
+
+海洋在 `国家` 模式下保持沉默，而不是显示大洋名称。原因是当前项目没有海域/大洋边界数据源；用经纬度粗判太平洋、大西洋等范围容易产生误导。如果用户需要海洋位置，使用 `位置` 或 `完整`。
+
+## Implementation plan
+
+### Settings state
+
+在 `frontend/public/earth/js/constants.js` 增加：
+
+```js
+export const SURFACE_HOVER_INFO_MODES = {
+  COUNTRY: "country",
+  POSITION: "position",
+  FULL: "full",
+};
+
+export const DEFAULT_SURFACE_HOVER_INFO_MODE =
+  SURFACE_HOVER_INFO_MODES.FULL;
+```
+
+在 `frontend/public/earth/js/controls.js`：
+
+- 将 `EARTH_SETTINGS_VERSION` 从 `10` 升到 `11`。
+- 在 shared settings 中新增 `surfaceHoverInfoMode`。
+- 新增导出：
+  - `getSurfaceHoverInfoMode()`
+  - `setSurfaceHoverInfoMode(mode, { persist, suppressStatus })`
+- normalize 时只接受 `country | position | full`，否则回退到 `full`。
+- reset settings 后恢复为 `full`。
+
+### Settings UI
+
+在桌面设置 `视图` 区和移动端设置 `视图` 区加入同一组按钮：
+
+```html
+<button data-surface-hover-info-mode="country">国家</button>
+<button data-surface-hover-info-mode="position">位置</button>
+<button data-surface-hover-info-mode="full">完整</button>
+```
+
+控件同步规则沿用现有卫星显示风格和巡航模块的模式：
+
+- 当前模式按钮添加 `is-active`。
+- 当前模式按钮设置 `aria-pressed="true"`。
+- 切换后保存到 Earth settings localStorage。
+
+### Hover tooltip logic
+
+在 `frontend/public/earth/js/main.js` 的地表 hover 分支中读取 `getSurfaceHoverInfoMode()`，统一构造 tooltip。
+
+行为规则：
+
+- 如果没有命中地球：清除国家 hover 并隐藏 tooltip。
+- `position`：
+  - 调用 `clearCountryBoundaryHover()`。
+  - 显示 `纬度 / 经度 / 海拔`。
+- `country`：
+  - 仅当国界图层开启并命中国家时显示国家 tooltip 和国界 hover。
+  - 海洋、国界图层关闭、未加载国界数据时隐藏地表 tooltip。
+- `full`：
+  - 国界图层开启且命中国家时显示国家信息加位置信息。
+  - 未命中国家或国界图层关闭时显示位置信息。
+
+海拔继续使用 `sampleElevationAt(lat, lon)`。暂无采样时显示 `—`，不因 hover 主动加载地形瓦片。
+
+## Acceptance criteria
+
+1. `完整` 模式下，hover 陆地显示国家信息和经纬海拔，hover 海洋显示经纬海拔。
+2. `国家` 模式下，hover 陆地显示国家信息，hover 太平洋等海洋不显示地表 tooltip。
+3. `位置` 模式下，hover 陆地和海洋都显示经纬海拔，国家边界不高亮。
+4. 关闭国界图层后，`完整` 模式回退为只显示位置。
+5. 船只、BGP、算力中心、海缆等对象 hover tooltip 优先级不变。
+6. 移动端中心国家高亮不受这个鼠标 hover 设置影响。
+7. 设置刷新后保持，重置后恢复为 `完整`。
+
+## Verification
+
+- 在 `frontend` 下运行 `/home/ray/.bun/bin/bun run build`。
+- 手动验证三种模式的陆地和海洋 hover 行为。
+- 验证设置持久化和重置。
+- 验证对象 hover 仍优先于地表 hover。

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

@@ -1,14 +1,14 @@
 # 实时船只监控系统 — 实施计划
 
-**状态**：规划中
+**状态**：历史计划；实时 AIS 与聚合接口已由 [AIS 多源采集、冲突记录与聚合接口计划](/home/ray/dev/linkong/planet/docs/plans/earth-vessel-ais-aggregation-plan.md) 接管
 **创建日期**：2026-04-27
-**优先数据源**：BarentsWatch AIS（免费但需要 OAuth client credentials）→ AISHub / MarineTraffic（TODO，付费）
+**优先数据源**：BarentsWatch AIS（免费但需要 OAuth client credentials）→ AISStream realtime；AISHub / MarineTraffic 保留为付费备选
 
 ## 已确认决策
 
 | 项目 | 决策 |
 |-----|------|
-| 数据源 | BarentsWatch 先行；AISHub / MarineTraffic TODO |
+| 数据源 | BarentsWatch 先行；AISStream realtime 已成为全球实时补充；AISHub / MarineTraffic 保留为付费备选 |
 | 船只规模 | BarentsWatch 阶段全部显示；全球数据接入后按需加船型过滤（默认 Cargo + Tanker + Passenger） |
 | 更新频率 | 准实时：前端 5 分钟轮询，后端 Collector 每分钟拉取写库 |
 | 历史轨迹 | 保留（`vessel_position` 表保留 24h，后期按需扩展） |
@@ -23,9 +23,9 @@
 | 来源类型 | 典型服务 | 覆盖范围 | 成本 | 状态 |
 |---------|---------|---------|------|------|
 | **BarentsWatch AIS API** | live.ais.barentswatch.no | 挪威海域实时 | 免费，需要 AIS API client credentials | **当前使用** |
-| **AISHub** | aishub.net | 全球实时 | 免费/小额 | TODO：付费接入 |
-| **MarineTraffic API** | marinetraffic.com | 全球实时 | $50–$500/月 | TODO：评估 tier |
-| **VesselFinder API** | vesselfinder.com | 全球实时 | $50–$300/月 | TODO：备选 |
+| **AISHub** | aishub.net | 全球实时 | 免费/小额 | 付费备选 |
+| **MarineTraffic API** | marinetraffic.com | 全球实时 | $50–$500/月 | 待评估 tier |
+| **VesselFinder API** | vesselfinder.com | 全球实时 | $50–$300/月 | 备选 |
 | **自建 SDR 接收** | RTL-SDR + AIS-catcher | 仅本地 30–50km | 硬件 $30 | 不考虑 |
 | **NOAA 历史数据** | Marine Cadastre | 美国近海历史 | 免费 | 可用于冷启动 |
 
@@ -36,16 +36,9 @@
 - 字段：mmsi, lat, lon, sog, cog, heading, nav_status, name, vessel_type, flag
 - 刷新频率：数据约 30–60s 更新一次，可随意轮询
 
-### TODO：多源 AIS 与实时流接入
+### 多源 AIS 与实时流接入历史
 
-- [ ] 接入 AISStream WebSocket 采集器，作为 BarentsWatch 覆盖不足的实时补充
-- [ ] 将 BarentsWatch、AISStream、自定义 `vessel_ais` 映射源统一写入原始观测层
-- [ ] 通过聚合接口做去重、字段合并、冲突记录和默认来源选择
-- [ ] 开放字段级聚合策略配置，让用户决定不同字段优先信任哪个来源
-- [ ] 评估 AISHub 订阅（全球覆盖，约 $30/月），接入全球实时流
-- [ ] 评估 MarineTraffic API tier，对比 AISHub 数据质量与成本
-- [ ] 实现多数据源适配器，通过 `datasource_config` 切换
-- [ ] 真实高频 AIS 稳定接入后，评估将 `vessel_position` 迁移为 TimescaleDB hypertable（保留 Postgres 原生分区作为备选）
+AISStream WebSocket collector、`/api/v1/vessels/snapshot` 和 `/ws` vessels channel 已在后续计划中落地。仍有价值的后续项集中维护在根目录 [TODO](/home/ray/dev/linkong/planet/TODO.md) 的 AIS / Vessels 小节。
 
 多源 AIS 的详细设计见 [AIS 多源采集、冲突记录与聚合接口计划](/home/ray/dev/linkong/planet/docs/plans/earth-vessel-ais-aggregation-plan.md)。
 
@@ -252,7 +245,7 @@ IMO         9811000
 ### Phase 4 — 性能与生产化（2–3 天）
 
 - `vessel_position` 按天分区，7 天自动清理
-- TODO：真实数据量达到百万级/日后，将 `vessel_position` 升级为 TimescaleDB hypertable，配置 retention policy 与压缩策略
+- 真实数据量达到百万级/日后，再评估是否将船只时序数据升级为 TimescaleDB hypertable，并配置 retention policy 与压缩策略
 - GeoJSON endpoint 用 Redis 缓存 15s
 - 若需 bbox 精确查询，引入 PostGIS `geography` + `ST_DWithin`
 - InstancedMesh + frustum culling，目标 5 万船只 60fps