# 全国 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`