# NavSea 全国 Full PBF 重建流水线说明

最后确认：`2026-06-11`

## 1. 文档目的

本文固化当前全国 Full PBF 基线的可重复重建节点：

- 当前基线目录：`/home/wwwroot/pbf-delivery-full-20260418-rebuild`
- 原始海图来源：全国 `newpec` PBF
- 语义来源：MySQL `pbf_analysis`
- 固定规则包：`navsea-core`
- 历史固定代码节点：Git commit `6d72340`
- 当前专用分支对应节点：Git commit `5cb0eea`

本文用于以后重新生成与 `pbf-delivery-full-20260418-rebuild` 业务内容等价的全国 Full PBF。

这里的“业务内容等价”是指：

- 瓦片范围一致
- source layer、对象和属性语义一致
- 几何与 extent 一致
- 样式消费结果和人工视觉判断一致

不强制要求每个 PBF 文件的二进制 SHA256 完全一致。编码库版本、属性顺序或 feature 编码顺序变化，都可能造成字节不同。

## 2. 当前确认条件

### 2.1 数据库

当前已确认数据库内容没有被修改。

数据库配置由 `navsea_tile_builder.py` 的 `DbConfig` 提供：

- database：`pbf_analysis`
- unix socket：`/tmp/mysql.sock`

当前关键表数量：

| 表 | 行数 |
| --- | ---: |
| `features` | `6685117` |
| `properties` | `23659423` |
| `pbf_relayer_candidates` | `6685117` |

规则包：

- `bundle_id = navsea-core`
- 当前状态：`v1-draft`

### 2.2 原始 PBF

原始几何与原始属性来源：

```text
/home/wwwroot/newpec/exported_auto/
tile.mapple-on.jp__newpec-mvt-20260106__z___x___y_.pbf/tiles
```

本文后续命令将其写成单行路径。

### 2.3 Reference Footprint

全国瓦片生成范围使用：

```text
/home/wwwroot/pbf-delivery-full-20260415
```

`--reference-tile-root` 只决定需要生成哪些 `z/x/y` 瓦片。

实际瓦片几何仍读取原始 `newpec` PBF，语义数据仍读取 MySQL。不要把 `20260415` 理解成新包的内容来源。

### 2.4 固定代码版本

2026-04-18 全国分片重建时，固定使用的是当时的 HEAD 版本。对应可追溯节点：

```text
6d72340 guard high-extent tile reencoding
```

当前工作区的 `navsea_tile_builder.py` 已经包含后续修改，不能用于严格复建该历史基线。应使用独立 Git worktree，同时固定：

- `navsea_tile_builder.py`
- `navsea_mapping_registry.py`
- `tasks/pbf/mappings/` 下的规则文件

## 3. 流水线总览

```text
原始 newpec 全国 PBF
        +
MySQL pbf_analysis 语义表
        +
navsea-core 映射规则
        ↓
固定 6d72340 代码节点
        ↓
按 z0-8 / z9-10 / z11 / z12 分片重建
        ↓
合并全国候选根目录
        ↓
瓦片数量与 mapping audit
        ↓
对象保真与 geometry / extent audit
        ↓
全国固定 AOI 视觉审计
        ↓
人工确认后切换 style 和正式目录
```

## 4. 重建前准备

### 4.1 禁止直接覆盖当前基线

不要直接写入：

```text
/home/wwwroot/pbf-delivery-full-20260418-rebuild
```

先生成候选目录，审计通过后再切换。本文示例候选目录：

```text
/home/wwwroot/pbf-delivery-full-rebuild-candidate
```

### 4.2 建立固定代码 worktree

```bash
cd /root/sourceserver/pbf

git worktree add --detach /tmp/navsea-full-rebuild-code 6d72340
```

检查固定版本：

```bash
git -C /tmp/navsea-full-rebuild-code rev-parse HEAD
```

期望以 `6d72340` 开头。

### 4.3 设置路径变量

```bash
export REPO=/root/sourceserver/pbf
export CODE=/tmp/navsea-full-rebuild-code
export PY=/root/sourceserver/pbf/.venv/bin/python

export SOURCE=/home/wwwroot/newpec/exported_auto/tile.mapple-on.jp__newpec-mvt-20260106__z___x___y_.pbf/tiles
export REFERENCE=/home/wwwroot/pbf-delivery-full-20260415

export PARTS=/home/wwwroot/pbf-delivery-full-rebuild-candidate.parts
export CANDIDATE=/home/wwwroot/pbf-delivery-full-rebuild-candidate
```

### 4.4 输入预检

```bash
test -d "$SOURCE"
test -d "$REFERENCE"
test -x "$PY"
test -f "$CODE/navsea_tile_builder.py"
```

检查 reference 瓦片总数：

```bash
find "$REFERENCE" -type f -name '*.pbf' | wc -l
```

当前期望：

```text
65148
```

检查数据库连接和关键表：

```bash
cd "$REPO"

$PY - <<'PY'
import pymysql
from navsea_tile_builder import DbConfig

config = DbConfig()
connection = pymysql.connect(
    host=config.host,
    port=config.port,
    user=config.user,
    password=config.password,
    database=config.database,
    unix_socket=config.unix_socket,
)

with connection:
    with connection.cursor() as cursor:
        for table in ("features", "properties", "pbf_relayer_candidates"):
            cursor.execute(f"SELECT COUNT(*) FROM `{table}`")
            print(table, cursor.fetchone()[0])
PY
```

## 5. 全国分片重建

### 5.1 清理候选输出

候选目录只能在确认它不是正式目录后删除：

```bash
rm -rf "$PARTS" "$CANDIDATE"
mkdir -p "$PARTS"
```

### 5.2 通用构建参数

四个分片必须使用相同业务参数：

```text
--strip-legacy-japanese-delivery
--release-minimal
--fid-key 'thisMyWorld@2026'
--bundle-id navsea-core
```

机器实际只有 4 核。建议四个分片各使用 `workers=1` 并行执行，避免沿用历史上的过度并发参数。

### 5.3 z0 至 z8

```bash
$PY "$CODE/navsea_tile_builder.py" \
  --source-root "$SOURCE" \
  --reference-tile-root "$REFERENCE" \
  --output "$PARTS/z0_8" \
  --zmin 0 \
  --zmax 8 \
  --workers 1 \
  --strip-legacy-japanese-delivery \
  --release-minimal \
  --fid-key 'thisMyWorld@2026' \
  --bundle-id navsea-core
```

### 5.4 z9 至 z10

```bash
$PY "$CODE/navsea_tile_builder.py" \
  --source-root "$SOURCE" \
  --reference-tile-root "$REFERENCE" \
  --output "$PARTS/z9_10" \
  --zmin 9 \
  --zmax 10 \
  --workers 1 \
  --strip-legacy-japanese-delivery \
  --release-minimal \
  --fid-key 'thisMyWorld@2026' \
  --bundle-id navsea-core
```

### 5.5 z11

```bash
$PY "$CODE/navsea_tile_builder.py" \
  --source-root "$SOURCE" \
  --reference-tile-root "$REFERENCE" \
  --output "$PARTS/z11" \
  --zmin 11 \
  --zmax 11 \
  --workers 1 \
  --strip-legacy-japanese-delivery \
  --release-minimal \
  --fid-key 'thisMyWorld@2026' \
  --bundle-id navsea-core
```

### 5.6 z12

```bash
$PY "$CODE/navsea_tile_builder.py" \
  --source-root "$SOURCE" \
  --reference-tile-root "$REFERENCE" \
  --output "$PARTS/z12" \
  --zmin 12 \
  --zmax 12 \
  --workers 1 \
  --strip-legacy-japanese-delivery \
  --release-minimal \
  --fid-key 'thisMyWorld@2026' \
  --bundle-id navsea-core
```

如需四段并行，应分别保存日志并检查每个命令的退出状态。不能仅根据目录里已经出现 PBF 就判断任务完成。

## 6. 分片验收与合并

### 6.1 检查 mapping audit

每个分片会在其父目录生成对应的 mapping audit 文件。必须检查：

- 构建进程正常退出
- `written` 数量符合对应 zoom 范围
- 没有影响交付字段的 unresolved mapping
- 没有异常大批量 skipped tile

### 6.2 合并候选根目录

```bash
mkdir -p "$CANDIDATE"

cp -a "$PARTS/z0_8/." "$CANDIDATE/"
cp -a "$PARTS/z9_10/." "$CANDIDATE/"
cp -a "$PARTS/z11/." "$CANDIDATE/"
cp -a "$PARTS/z12/." "$CANDIDATE/"
```

这些分片的 zoom 范围互不重叠，合并时不应出现同路径覆盖冲突。

### 6.3 检查瓦片数量

```bash
find "$CANDIDATE" -type f -name '*.pbf' -printf '%P\n' |
  awk -F/ '{count[$1]++} END {for (z in count) print "z" z "=" count[z]}' |
  sort -V
```

当前基线期望：

| Zoom | 瓦片数 |
| ---: | ---: |
| `0` | `1` |
| `5` | `10` |
| `6` | `27` |
| `7` | `76` |
| `8` | `230` |
| `9` | `813` |
| `10` | `3156` |
| `11` | `12279` |
| `12` | `48556` |
| 合计 | `65148` |

当前数据库没有 `z1-z4` 对应的受支持输出，因此最终目录中没有这些 zoom 的 PBF。

## 7. 交付审计

审计顺序必须保持：

1. 对象保真审计
2. 渲染与 geometry / extent 审计
3. AOI / 人工视觉审计

不能因为画面看起来接近，就跳过对象和几何门禁。

### 7.1 Geometry / Extent 审计

```bash
cd "$REPO"

$PY navsea_geometry_native_audit.py \
  --target-root "$CANDIDATE" \
  --label full-rebuild-candidate \
  --output-dir report/full_rebuild_candidate_geometry
```

重点检查：

- `source_extent_mismatch_tiles = 0`
- 不出现历史上的 `extent=4096` 错退
- 高精度 tile 继续保持原始 source 的 `extent=1048576`
- 不出现旧坏片式的大范围几何错移

坐标超 extent 本身不一定是错误。必须结合 source extent 和原始 tile 对照判断。

### 7.2 与当前基线做结构比较

不要只比较 SHA256。推荐逐瓦片解码后比较：

- layer 集合
- layer extent
- feature 数量
- feature geometry
- 标准化后的 properties
- NavSea FID

对结构差异必须输出具体 `z/x/y`、layer 和 feature 锚点，不能只给一个全局差异数量。

### 7.3 全国 AOI 视觉审计

候选目录需要可通过 HTTP 访问，例如：

```text
http://192.168.200.184/pbf-delivery-full-rebuild-candidate/{z}/{x}/{y}.pbf
```

通过 compare 页的临时覆盖参数审计候选包：

```bash
$PY navsea_full_aoi_visual_audit.py \
  --compare-url 'http://192.168.200.184/newpec/navsea-compare-full-audit.html?deliveryTileUrl=http%3A%2F%2F192.168.200.184%2Fpbf-delivery-full-rebuild-candidate%2F%7Bz%7D%2F%7Bx%7D%2F%7By%7D.pbf' \
  --variant full \
  --output-dir report/full_rebuild_candidate_visual
```

人工复核至少覆盖：

- 博多港
- 唐津
- 东京湾
- 大阪湾
- 冲绳
- `z10`
- `z12`

重点确认：

- 没有大片空白
- 岛屿、岸线和危险物没有错位
- 安全图标和关键文字没有缺失
- 点击拾取仍能定位到正确对象

## 8. 发布切换

所有审计通过前，不修改正式 style，不覆盖当前基线。

推荐发布方式：

1. 保留当前 `/home/wwwroot/pbf-delivery-full-20260418-rebuild`
2. 将候选目录部署为带新日期或版本号的正式目录
3. 更新 extentfix style 的 tile URL
4. 更新全国 compare 页可见版本字符串
5. 部署 style 和 compare 页
6. 清缓存后再次完成固定 AOI 人工确认
7. 在 `STEP_RECORD.md` 记录新目录、版本、审计报告和切换时间

只有明确要求原路径替换时，才对 `pbf-delivery-full-20260418-rebuild` 做原子目录切换。切换前必须保留可快速回退的旧目录。

## 9. 历史脚本的职责边界

### `navsea_tile_builder.py`

全国 Full PBF 的核心生成器。

负责：

- 从原始 PBF 读取几何与原始 feature
- 从 MySQL 读取语义投影
- 应用 NavSea mapping registry
- 输出 delivery layer、标准字段和 NavSea FID

### `navsea_rebuild_hotspot_tiles.py`

只用于固定 AOI 热点重建和问题定位。

它不是全国 Full PBF 的正式生成 pipeline，不能用它代替本文的全国分片重建。

### `navsea_geometry_native_audit.py`

负责 geometry、extent 和 native 风险审计。

### `navsea_full_aoi_visual_audit.py`

负责全国固定 AOI 的浏览器截图和视觉 diff。

## 10. 节点结论

以后需要重新生成全国 Full PBF 时，以本文作为入口节点。

固定重建要素为：

```text
历史代码节点：6d72340
当前分支节点：5cb0eea
数据库：pbf_analysis 当前确认未修改的数据
规则包：navsea-core
原始 PBF：newpec-mvt-20260106
reference footprint：pbf-delivery-full-20260415
生成方式：四段分片重建后合并
审计顺序：对象保真 → 渲染/几何 → AOI 视觉
```

如果上述任一输入发生变化，生成结果应视为新的全国版本，不能继续沿用 `20260418-rebuild` 的版本含义。