guard high-extent tile reencoding

report/full_extent_shift_root_cause_2026-04-18.md

@@ -0,0 +1,109 @@
+# 全国 full / semantic 高 extent 几何错移根因报告
+
+## 1. 结论
+
+- 当前全国 `full / semantic` 中反复出现的“大块空白 / 岛礁附近整块打穿 / 右侧大片缺失”问题
+- 根因不是 `style` 改图标本身
+- 真正根因是：
+  - 某条会重写 `PBF` 的生产链路
+  - 在处理原始 `extent = 1048576` 的高精度 tile 时
+  - 用了 `4096` 口径重编码几何
+- 结果会把 tile 的几何整体错移，尤其是 `Y` 坐标整张 tile 下移一个：
+  - `1048576 - 4096 = 1044480`
+  量级的偏移
+
+## 2. 证据
+
+### 2.1 生产坏 tile 的数值签名
+
+- 代表坏 tile：
+  - `/tmp/navsea_hotspot_rebuild/backup_full/12/3526/1643.pbf`
+  - `/tmp/navsea_hotspot_rebuild/backup_semantic/12/3526/1643.pbf`
+- 对比 source tile：
+  - `/home/wwwroot/newpec/exported_auto/tile.mapple-on.jp__newpec-mvt-20260106__z___x___y_.pbf/tiles/12/3526/1643.pbf`
+- source 正常 overflow：
+  - `20480`
+- 坏 tile overflow：
+  - `1064960`
+
+### 2.2 复现实验
+
+- 已直接拿 source tile 做重编码实验
+- 当把原始 `extent = 1048576` tile 重新编码时，故意把 layer `extent` 改成 `4096`
+- 可以稳定复现出与生产坏 tile 一模一样的几何签名：
+  - `overflow = 1064960`
+- 这说明：
+  - 当前线上坏 tile 不是随机损坏
+  - 而是非常明确的“高 extent tile 被按 4096 口径重编码”的产物
+
+### 2.3 热点备份审计结果
+
+- 对修前热点 full 备份：
+  - [`hotspot_backup_full_shift_audit_2026-04-18.json`](/root/sourceserver/pbf/report/hotspot_backup_full_shift_audit_2026-04-18.json)
+- 对修前热点 semantic 备份：
+  - [`hotspot_backup_semantic_shift_audit_2026-04-18.json`](/root/sourceserver/pbf/report/hotspot_backup_semantic_shift_audit_2026-04-18.json)
+- 结果：
+  - `backup_full`：`154` 张里有 `42` 张命中该签名
+  - `backup_semantic`：`154` 张里有 `43` 张命中该签名
+
+## 3. 为什么会让人误以为是“改图标导致的”
+
+- 图标 / style 变更本身不会把海底等深线、海岸线、陆域几何整块打空
+- 但“图标改名 / 属性改写”这类需求往往会触发：
+  - `decode pbf`
+  - `改属性`
+  - `encode pbf`
+  这条重写链
+- 一旦这条链在高 extent tile 上没有保回原始 extent
+  - 几何就会被整体写坏
+- 所以用户看到“像是改 style 图标之后坏了”
+  - 现象上是对的
+  - 但根因不是 style
+  - 而是“被图标/属性变更触发的 PBF 重编码链”出了错
+
+## 4. 本轮代码修复
+
+### 4.1 已新增重编码守卫
+
+- [`navsea_tile_reencode_guard.py`](/root/sourceserver/pbf/navsea_tile_reencode_guard.py)
+
+用途：
+
+- 统一保存原 layer `extent`
+- 重编码后立即和 source tile 做几何签名比对
+- 一旦出现：
+  - overflow 异常增大
+  - 或命中 `1048576 -> 4096` 错重编码签名
+  直接报错，不允许静默产出坏 tile
+
+### 4.2 已新增根因审计脚本
+
+- [`navsea_extent_shift_audit.py`](/root/sourceserver/pbf/navsea_extent_shift_audit.py)
+
+用途：
+
+- 审计目标目录里是否存在：
+  - 高 extent tile 被按 4096 口径错重编码
+  的几何签名
+
+### 4.3 已加固语义版 PBF 重写链
+
+- 已修改：
+  - [`build_semantic_delivery_assets.py`](/root/sourceserver/pbf/build_semantic_delivery_assets.py)
+
+当前要求：
+
+- decode 时显式带出原始 layer extent
+- encode 时必须按原 layer extent 写回
+- 每张被重写的 tile 写完后立即做几何守卫校验
+
+## 5. 当前对线上问题的影响
+
+- 热点 AOI 中已修过的 tile：
+  - 已通过重建替换为当前正确几何
+- 但全国目录里仍可能存在更多尚未重建的历史坏 tile
+- 因此要“彻底解决”全国问题，最终仍需要：
+  - 用当前受保护的生产链路重建全国 `full`
+  - 再基于新的 full 重建 `semantic`
+  - 并在部署前跑一轮 `extent shift audit`
+