pbf/STEP_RECORD.md

# PBF Step Record

Last Updated: 2026-04-01
Repo: `/root/sourceserver/pbf`
Remote: `ssh://git@nas:2222/tei/pbf.git`

## Active Baseline

当前唯一固定使用的视觉审计页面：

- `http://192.168.200.184/newpec/navsea-compare-karatsu-20nm.html`

当前页面版本体系：

- `HTML: compare-r14-20260401-1523`

当前页面支持 2 个 profile，但仍是同一张 HTML：

1. 唐津 20 海里
   - `Style: karatsu-final-style-r4-20260401-1523 (style.navsea-delivery-karatsu-20nm-final.json)`
   - `PBF: karatsu-final-pbf-20nm-20260401-0248 (pbf-delivery-karatsu-20nm-final)`

2. 九州
   - `Style: kyushu-style-r1-20260331-2205 (style.navsea-delivery-kyushu.json)`
   - `PBF: kyushu-pbf-reencoded-20260325-1105 (pbf-delivery-kyushu-reencoded)`

访问方式：

- 默认唐津：
  - `http://192.168.200.184/newpec/navsea-compare-karatsu-20nm.html`
- 九州模式：
  - `http://192.168.200.184/newpec/navsea-compare-karatsu-20nm.html?profile=kyushu`

工作规则：

- 不再新增 compare 页面
- 视觉确认统一只看这一个 URL
- 页面必须保持：
  - 左右联动
  - 点击拾取
  - HTML / Style / PBF 三层版本可见

## Current Truth

当前继续收敛的主 style 文件：

- [`src/pbf/style.navsea-delivery-karatsu-10nm.json`](/root/sourceserver/pbf/src/pbf/style.navsea-delivery-karatsu-10nm.json)
- [`src/pbf/style.navsea-delivery-karatsu-20nm-final.json`](/root/sourceserver/pbf/src/pbf/style.navsea-delivery-karatsu-20nm-final.json)

当前九州 delivery style：

- [`src/pbf/style.navsea-delivery-kyushu.json`](/root/sourceserver/pbf/src/pbf/style.navsea-delivery-kyushu.json)

关于当前问题，已经确认：

- `20nm pbf` 本身最近没有被重建改坏
- 鱼礁、灯塔、灯台等对象在 `20nm pbf` 里仍然存在
- 当前 compare 页右侧使用的是 `20nm final PBF`，不是旧的 `20nm delivery`
- 当前“看起来又丢了”的主因优先判断为：
  - style 表达式 / icon 选择问题
  - 图层叠放和 icon-size 导致的近距离互相遮挡
  - 不是 compare HTML 切错
  - 也不是 20nm pbf 最近重建坏了对象

当前新增结论：

- 紫色大 `X` 对应的不是 `428`
- 在当前 sprite 体系里：
  - `409 -> symbol-daytime-409`
  - `429 -> symbol-daytime-429`
- `428` 更像鱼礁/椭圆眼形符号
- 第二类“X 丢了”的问题，已经确认有一部分是危险物点与红绿小灯在近坐标重叠：
  - 例如同一热点存在：
    - `険悪物(class_code=420)` at `[3023,524]`
    - red light `30600002` at `[3013,524]`
    - green light `30600001` at `[3029,505]`
- 这类问题更像图层叠放和当前 icon-size 过大，不是 PBF 缺对象
- `fid=13025299` 这类对象的最新结论已经纠正：
  - 左侧原始版是 `p航行危険障害物 / 分類番号 409 / 孤立危険物`
  - 当前 `20nm final` 后台对象保真审计显示这类 `409` 在 final 里是完整保留下来的
  - 当前问题已经收敛成：
    - 旧 `20nm delivery` 没保留 `class_code`
    - `20nm final style` 之前没有对 `navigation_hazard_point` 按 `class_code` 选 icon
  - 也就是说，这批点现在的主问题是 `final style`，不是 `final PBF` 丢对象

一句话判断：

- 当前 `20nm final` 这条线，危险物对象保真已经过关
- 当前主矛盾是 `style`

## Object Preservation Audit

当前已经新增一条专门的对象保真审计：

- 脚本：
  - [`navsea_object_preservation_audit.py`](/root/sourceserver/pbf/navsea_object_preservation_audit.py)
- 报告：
  - [`report/object_preservation_20nm/object_preservation_delivery_20nm.md`](/root/sourceserver/pbf/report/object_preservation_20nm/object_preservation_delivery_20nm.md)
  - [`report/object_preservation_20nm/object_preservation_final_20nm.md`](/root/sourceserver/pbf/report/object_preservation_20nm/object_preservation_final_20nm.md)

当前结论非常明确：

- `delivery_20nm`
  - raw objects: `2090`
  - preserved: `0`
  - raw class lost: `2090`
- `final_20nm`
  - raw objects: `2090`
  - preserved: `2090`
  - missing object: `0`
  - raw class lost: `0`

重点含义：

- 旧 `20nm delivery` 的危险物细分类全部丢失
- 当前 `20nm final` 的危险物细分类已经完整保留下来
- `p航行危険障害物:409` 在 final 中是：
  - raw=`25`
  - preserved=`25`

## Final Release Candidate

当前已经产出一版 `20nm final release` 候选：

- 输出目录：
  - `/home/wwwroot/pbf-delivery-karatsu-20nm-final`
- 当前在线对比页：
  - `http://192.168.200.184/newpec/navsea-compare-karatsu-20nm.html`
- 当前候选 style：
  - [`src/pbf/style.navsea-delivery-karatsu-20nm-final.json`](/root/sourceserver/pbf/src/pbf/style.navsea-delivery-karatsu-20nm-final.json)

当前候选的生成方式：

- 以当前稳定 `/home/wwwroot/pbf-delivery-karatsu-20nm` 为输入
- 使用 protobuf 层属性裁剪脚本生成
- 脚本：
  - [`navsea_minimize_release_tiles.py`](/root/sourceserver/pbf/navsea_minimize_release_tiles.py)

当前 final candidate 只保留 `20` 个字段：

- `canonical_object_type`
- `class_code`
- `chart_fill_pattern`
- `chart_fill_style`
- `chart_icon_image`
- `chart_label_position_code`
- `chart_label_subtext`
- `chart_label_text`
- `chart_line_color`
- `chart_line_width`
- `chart_symbol_code`
- `chart_text_color`
- `chart_text_style`
- `depth_value_m`
- `display_code`
- `least_depth_m`
- `light_color_code`
- `light_sector_mode`
- `name_ja`
- `place_name_en`

当前 final candidate 量化结果：

- feature instances:
  - `269883`
- distinct `canonical_object_type`:
  - `137`
- 原始 `20nm delivery` 大小:
  - `29,527,981` bytes
- final candidate 大小:
  - `24,470,260` bytes
- 压缩幅度约:
  - `17.1%`

当前判断：

- 这版已经满足“字段显著裁剪”
- 为了恢复危险物和灯标/浮标细节，重新带回了：
  - `class_code`
  - `display_code`
- `r4` 已补上：
  - `navigation_hazard_point` 按 `class_code` 选 icon
- 之前 `r3` 已把危险物和航标 icon-size 收回旧版默认尺度，优先减轻危险物与灯标互相遮挡
- 但当前 AOI 图像审计仍显示大差异
- 所以它目前只能算 `final release candidate`
- 还不能直接认定为稳定最终版

## Audit Method

当前认可的可信审计方法：

1. `20nm compare` 肉眼审图
2. 小范围 AOI 图像对比
3. compare 页点击拾取
4. `10nm rerun` 对象级 backend audit

当前小范围试验方法文档：

- [`NavSea_20nm_Small_Scope_Audit_Method.md`](/root/sourceserver/pbf/NavSea_20nm_Small_Scope_Audit_Method.md)
- [`NavSea_Audit_Logic_And_Evolution_2026-04-01.md`](/root/sourceserver/pbf/NavSea_Audit_Logic_And_Evolution_2026-04-01.md)

当前 pilot 热点配置：

- [`strict_audit_hotspots_20nm_pilot.json`](/root/sourceserver/pbf/strict_audit_hotspots_20nm_pilot.json)

当前 pilot 报告：

- [`report/strict_audit_pilot/strict_audit_summary.md`](/root/sourceserver/pbf/report/strict_audit_pilot/strict_audit_summary.md)
- [`report/strict_audit_pilot/strict_audit_summary.json`](/root/sourceserver/pbf/report/strict_audit_pilot/strict_audit_summary.json)

当前结论：

- 不再只看整屏 diff
- 不再只看 `20nm` backend 总量数字
- `20nm` backend 仍不适合当严格对象级审计
- 当前正式审计顺序已经明确为：
  - 先 `object preservation audit`
  - 再 `render audit`
  - 最后 `AOI / visual audit`
- 其中 `20nm` 的危险物对象保真，当前已经有专门脚本和报告，不再只靠 render audit 猜

## Current Audit Status

### 20nm Visual Pilot

当前新版 `r14 / style-r4` strict audit：

- [`report/strict_audit_final_20nm_r4/strict_audit_summary.md`](/root/sourceserver/pbf/report/strict_audit_final_20nm_r4/strict_audit_summary.md)
- changed ratio: `0.916883`

当前 3 个热点：

1. `takashima_main_harbor_marks`
   - changed ratio: `0.800170`
2. `takashima_inner_nearshore_hazards`
   - changed ratio: `0.711509`
3. `east_breakwater_marks`
   - changed ratio: `0.999713`

这说明：

- 视觉仍然没有收敛到“可推广”状态
- 主港航标区仍是第一优先级观察点
- 近岸碍航与鱼礁区有一点改善，但离稳定还远

### 10nm Object-Level Backend Audit

当前最可信的对象级 backend 审计报告：

- [`NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.rerun.md`](/root/sourceserver/pbf/NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.rerun.md)
- [`NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.rerun.json`](/root/sourceserver/pbf/NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.rerun.json)

当前结果：

- `exact_match = 121855`
- `mismatch = 12912`
- `missing_in_engineering = 5`

这说明：

- 当前 10nm 已经不是“对象大面积丢失/多出”的阶段
- 现在主要是 visual / semantic mismatch 修复

当前 mismatch 最大几组：

- `P基本線ククリ = 7873`
- `P基本線 = 2876`
- `L基本線 = 619`
- `p航路標識群 = 574`
- `p投錨注意障害物 = 374`
- `p航行危険障害物 = 296`

## Delivery Field Policy

总目标：

- `尽可能减少日文`

当前字段处置规则：

- `canonical_family`
  - 保留
  - 已经是英文

- `canonical_object_type`
  - 不直接删除
  - 改成稳定英文值

- `semantic_key`
  - 正式 release PBF 直接删除
  - audit 版若保留，可以继续保留现有值
  - 当前不强制改英文

- `detection_key`
  - 正式 release PBF 直接删除
  - audit 版若保留，可以继续保留现有值
  - 当前不强制改英文

具体到这类对象：

- `canonical_object_type = 漁業協同組合`
  - 不直接删除
  - 改成稳定英文值
  - 当前建议：
    - `fisheries_cooperative`

- `canonical_family = symbol`
  - 保留

- `semantic_key = symbol:漁業協同組合`
  - release PBF 直接删除
  - audit 版若保留，可以继续保留：
    - `symbol:漁業協同組合`

- `detection_key = symbol:漁業協同組合`
  - release PBF 直接删除
  - audit 版若保留，可以继续保留：
    - `symbol:漁業協同組合`

一句话：

- 业务语义字段英文化
- 审计追踪字段从正式交付版尽量移除

当前对 `/home/wwwroot/pbf-delivery-karatsu-20nm` 的全量扫描结果：

- 日文字段名：
  - `0`
- 但含日文值的核心字段仍很多

当前最主要的残留字段：

- `canonical_object_type`
  - `235688`
- `semantic_key`
  - `235688`
- `detection_key`
  - `235688`
- `chart_label_text`
  - `3338`
- `place_name_ja`
  - `2552`
- `name_ja`
  - `803`
- `name_subtext_ja`
  - `18`

说明：

- 当前已经基本摆脱“日文键名”
- 但还远没有摆脱“日文语义值”
- 最大头仍然是：
  - `canonical_object_type`

当前关于 `canonical_object_type` 的快速基线：

- 当前 `/home/wwwroot/pbf-delivery-karatsu-20nm` 成品 PBF 中
  - 实际出现的 distinct `canonical_object_type` 一共有 `137` 种
- 数据库中可以直接查
  - 主表：`pbf_relayer_candidates`
  - 字段：`canonical_object_type`
  - 已有索引：`idx_navsea_object (canonical_object_type, geom_type)`
- 当前数据库表规模：
  - `pbf_relayer_candidates` 约 `6,664,855` 行
- 说明：
  - `PBF` 里的 distinct 数 = 当前这批成品实际输出了多少种
  - `数据库` 里的 distinct 数 = 候选对象全集范围，通常会大于等于当前成品 PBF
  - `semantic_key`
  - `detection_key`

## Current Priority

当前继续修的优先顺序：

1. 鱼礁 / 障害点 icon 表达
2. 灯 / 灯台 / flare 表达
3. `baseline` 相关 mismatch
4. 九州沿用同一张 compare 页后的热点审计

如果 style 修到一定程度仍然不对，再回到 builder 看：

- 是否需要补更细的 delivery 语义字段

## Key Files

- [`AGENTS.md`](/root/sourceserver/pbf/AGENTS.md)
- [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md)
- [`src/pbf/navsea-compare-karatsu-20nm.html`](/root/sourceserver/pbf/src/pbf/navsea-compare-karatsu-20nm.html)
- [`src/pbf/style.navsea-delivery-karatsu-10nm.json`](/root/sourceserver/pbf/src/pbf/style.navsea-delivery-karatsu-10nm.json)
- [`src/pbf/style.navsea-delivery-kyushu.json`](/root/sourceserver/pbf/src/pbf/style.navsea-delivery-kyushu.json)
- [`NavSea_20nm_Small_Scope_Audit_Method.md`](/root/sourceserver/pbf/NavSea_20nm_Small_Scope_Audit_Method.md)

## Quick Resume Prompt

`继续围绕同一个 compare 页 navsea-compare-karatsu-20nm.html 修 delivery style。默认先看唐津 profile，按 pilot 热点先修鱼礁和灯标；需要看九州时就在同一张页面切到 kyushu profile。视觉确认用 20nm compare，严格对象级 backend 审计看 10nm rerun。`