pbf/report/full_extent_shift_root_cause_2026-04-18.md

全国 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
• 对修前热点 semantic 备份：
  • 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

用途：

• 统一保存原 layer extent
• 重编码后立即和 source tile 做几何签名比对
• 一旦出现：
  • overflow 异常增大
  • 或命中 1048576 -> 4096 错重编码签名 直接报错，不允许静默产出坏 tile

4.2 已新增根因审计脚本

• navsea_extent_shift_audit.py

用途：

• 审计目标目录里是否存在：
  • 高 extent tile 被按 4096 口径错重编码 的几何签名

4.3 已加固语义版 PBF 重写链

• 已修改：
  • build_semantic_delivery_assets.py

当前要求：

• decode 时显式带出原始 layer extent
• encode 时必须按原 layer extent 写回
• 每张被重写的 tile 写完后立即做几何守卫校验

5. 当前对线上问题的影响

• 热点 AOI 中已修过的 tile：
  • 已通过重建替换为当前正确几何
• 但全国目录里仍可能存在更多尚未重建的历史坏 tile
• 因此要“彻底解决”全国问题，最终仍需要：
  • 用当前受保护的生产链路重建全国 full
  • 再基于新的 full 重建 semantic
  • 并在部署前跑一轮 extent shift audit