docs(pbf): archive Full production provenance and engineering history

NavSea_coast_wall_z12_bin_生成说明.md

@@ -0,0 +1,206 @@
+# NavSea coast_wall_z12.bin 生成说明
+
+本文说明如何从当前 MySQL 三层格子生成 `coast_wall_z12.bin`。
+
+生成脚本：
+
+- [`coastline/build_coast_wall_z12_bin.py`](/root/sourceserver/pbf/coastline/build_coast_wall_z12_bin.py)
+
+当前输入数据库：
+
+- `navsea_japan_coast_grid`
+
+当前输入表：
+
+- `navsea_grid_cell`
+
+## 1. 设计口径
+
+这个 bin 文件不是重新从原始海岸线矢量或 PBF 几何开始栅格化。
+
+当前口径是：
+
+1. 先使用数据库里已经生成好的三层格子
+2. 再按 `density_overview_grid` 的密度优先级融合
+3. 最后编码成 z12 / 40x40 的 blocked wall 二进制文件
+
+三层输入：
+
+- `fish_port_20m`
+- `hazard_50m`
+- `coast_200m`
+
+融合规则：
+
+- `20x20` 永远保留
+- `50x50` 如果和已保留的 `20x20` 重叠，则跳过
+- `200x200` 如果和已保留的 `20x20` 或已保留的 `50x50` 重叠，则跳过
+
+这和 `density_overview_grid.geojson` 的规则一致：同一区域优先使用更高密度格子，避免重复表达同一片阻断区域。
+
+## 2. bin 格式
+
+输出 bin 用于快速查询：
+
+```text
+isBlocked(lon, lat) -> bool
+```
+
+空间划分：
+
+- zoom：`z12`
+- 每个 z12 tile 切成 `40 x 40`
+- 每个 tile 最多 `1600` 个 cell
+
+tile 内编码：
+
+- blocked cell 数量 `<= 96`：使用 sparse `uint16[]`
+- blocked cell 数量 `> 96`：使用 bitset `uint32[50]`
+
+文件结构：
+
+- Header
+- BlockDirectory
+- TileDirectory
+- DataBlob
+
+这个结构的目的主要是节约物理存储空间，同时让运行时可以按 block / tile 做快速查询。
+
+## 3. 九州测试生成
+
+推荐先生成九州范围样例：
+
+```bash
+cd /root/sourceserver/pbf
+./.venv/bin/python coastline/build_coast_wall_z12_bin.py \
+  --preset kyushu \
+  --out out/navmask/coast_wall_z12_kyushu.bin \
+  --debug-geojson out/navmask/coast_wall_z12_kyushu.debug.geojson \
+  --debug-limit 2000
+```
+
+输出文件：
+
+- `out/navmask/coast_wall_z12_kyushu.bin`
+- `out/navmask/coast_wall_z12_kyushu.bin.meta.json`
+- `out/navmask/coast_wall_z12_kyushu.debug.geojson`
+
+当前九州样例统计：
+
+```text
+tiles=813
+cells=148453
+sparse=351
+bitset=462
+blocks=7
+size=122625 bytes
+```
+
+## 4. 小范围 smoke test
+
+可以用福冈附近小范围做快速验证：
+
+```bash
+cd /root/sourceserver/pbf
+./.venv/bin/python coastline/build_coast_wall_z12_bin.py \
+  --self-test \
+  --bbox 130,33,131,34.5 \
+  --out out/navmask/coast_wall_z12_fukuoka_smoke.bin \
+  --query 130.4,33.6 \
+  --progress-every 0
+```
+
+这个命令会：
+
+- 跑内置编码自测
+- 生成小范围 bin
+- 用内置 reader 查询 `130.4,33.6`
+
+当前验证结果：
+
+```text
+query lon=130.4 lat=33.6 blocked=True
+```
+
+## 5. 全国生成
+
+全国生成命令：
+
+```bash
+cd /root/sourceserver/pbf
+./.venv/bin/python coastline/build_coast_wall_z12_bin.py \
+  --preset all \
+  --out out/navmask/coast_wall_z12.bin
+```
+
+如果需要 debug GeoJSON，可以追加：
+
+```bash
+  --debug-geojson out/navmask/coast_wall_z12.debug.geojson \
+  --debug-limit 5000
+```
+
+全国生成会扫描完整三层数据库，耗时和内存都会高于九州样例。
+
+## 6. 参数说明
+
+常用参数：
+
+- `--preset kyushu`：生成九州范围样例，默认值
+- `--preset all`：生成全国范围
+- `--bbox min_lon,min_lat,max_lon,max_lat`：自定义经纬度范围，优先于 `--preset`
+- `--out PATH`：输出 bin 路径
+- `--meta-json PATH`：输出 meta JSON；不指定时默认写到 `<out>.meta.json`
+- `--debug-geojson PATH`：输出抽样 blocked cell GeoJSON
+- `--debug-limit N`：debug GeoJSON 最多输出多少个 cell
+- `--query lon,lat`：生成后用内置 reader 查询一个点
+- `--self-test`：执行基础编码自测
+- `--progress-every N`：每读取 N 行打印一次进度，设为 `0` 可关闭
+
+查看帮助：
+
+```bash
+cd /root/sourceserver/pbf
+./.venv/bin/python coastline/build_coast_wall_z12_bin.py --help
+```
+
+## 7. 输出 meta
+
+生成器会写出 meta JSON，包含：
+
+- 生成时间
+- 数据库名
+- bbox / preset
+- z12 cell 大小
+- density 融合规则
+- 三层源数据行数
+- 三层去重后数量
+- 三层保留 / 跳过统计
+- bin 文件大小
+- block / tile / sparse / bitset 统计
+- 可选 query 查询结果
+
+示例：
+
+- `out/navmask/coast_wall_z12_kyushu.bin.meta.json`
+
+## 8. 当前验证项
+
+脚本内已包含：
+
+- `tileId` pack / unpack
+- `cellId` pack
+- `blockId` pack
+- sparse encode
+- bitset encode
+- writer / reader 抽样 roundtrip
+- `is_blocked_lonlat()` 查询
+
+已验证命令：
+
+```bash
+cd /root/sourceserver/pbf
+./.venv/bin/python -m py_compile coastline/build_coast_wall_z12_bin.py
+./.venv/bin/python coastline/build_coast_wall_z12_bin.py --help
+./.venv/bin/python coastline/build_coast_wall_z12_bin.py --self-test --bbox 130,33,131,34.5 --out out/navmask/coast_wall_z12_fukuoka_smoke.bin --query 130.4,33.6 --progress-every 0
+```