固化全国 Full semantic extentfix 重建基线
This commit is contained in:
OpenAI Codex
480
NavSea_全国完整PBF重建流水线说明.md
Normal file
480
NavSea_全国完整PBF重建流水线说明.md
Normal file
@@ -0,0 +1,480 @@
|
||||
# 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` 的版本含义。
|
||||
Reference in New Issue
Block a user