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

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 完成“一比一还原”。
• 实施前必须先引入或生成可审计的高精度源数据包；没有源数据时，只能实现加载框架，不能伪造边界。