481 lines
11 KiB
Markdown
481 lines
11 KiB
Markdown
# 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`
|
||
|
||
本文用于以后重新生成与 `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
|
||
数据库：pbf_analysis 当前确认未修改的数据
|
||
规则包：navsea-core
|
||
原始 PBF：newpec-mvt-20260106
|
||
reference footprint：pbf-delivery-full-20260415
|
||
生成方式：四段分片重建后合并
|
||
审计顺序：对象保真 → 渲染/几何 → AOI 视觉
|
||
```
|
||
|
||
如果上述任一输入发生变化，生成结果应视为新的全国版本，不能继续沿用 `20260418-rebuild` 的版本含义。
|