Document audit logic and evolution

AGENTS.md

@@ -17,11 +17,12 @@ When resuming work in this project, read in this order:
 1. [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md)
 2. [`PROJECT_HANDOFF_2026-03-31.md`](/root/sourceserver/pbf/PROJECT_HANDOFF_2026-03-31.md)
 3. [`NavSea_Delivery_Preflight_Audit_Spec.md`](/root/sourceserver/pbf/NavSea_Delivery_Preflight_Audit_Spec.md)
+4. [`NavSea_Audit_Logic_And_Evolution_2026-04-01.md`](/root/sourceserver/pbf/NavSea_Audit_Logic_And_Evolution_2026-04-01.md)
 
 If the task is specifically about Domain work, also read:
 
-4. [`NavSea_Chart_Domain_Model_v1.md`](/root/sourceserver/pbf/NavSea_Chart_Domain_Model_v1.md)
+5. [`NavSea_Chart_Domain_Model_v1.md`](/root/sourceserver/pbf/NavSea_Chart_Domain_Model_v1.md)
-5. [`NavSea_Semantic_Package_Overlay_Design.md`](/root/sourceserver/pbf/NavSea_Semantic_Package_Overlay_Design.md)
+6. [`NavSea_Semantic_Package_Overlay_Design.md`](/root/sourceserver/pbf/NavSea_Semantic_Package_Overlay_Design.md)
 
 ## Current Reliable Audit Baseline
 
@@ -35,6 +36,16 @@ Important limitation:
 
 - `Karatsu 20nm delivery` is currently not object-auditable with the existing audit script because the delivery PBF no longer preserves enough trace-back anchor fields
 
+## Audit Order
+
+Current official order:
+
+1. object preservation audit
+2. render audit
+3. AOI / visual audit
+
+Do not treat a visual match as a pass if objects have already been dropped or wrongly merged.
+
 ## Current Visual Regression Baseline
 
 The current working visual baseline is:

NavSea_Audit_Logic_And_Evolution_2026-04-01.md

@@ -0,0 +1,406 @@
+# NavSea Audit Logic And Evolution
+
+Last Updated: 2026-04-01
+
+## Goal
+
+这份文档统一说明两件事：
+
+1. 当前 `pbf` 项目应该采用什么审计口径
+2. 审计方法是如何一步步升级到现在这个状态的
+
+当前最重要的原则只有一条：
+
+- 审计第一优先级不是“看起来像不像”
+- 而是“不能丢对象”
+
+只有对象保真先过关，后面的渲染审计和视觉复原才有意义。
+
+## Current Audit Order
+
+当前正式口径按下面 3 层执行，顺序不能反过来。
+
+### 1. Object Preservation Audit
+
+目标：
+
+- 先判断原始对象有没有在 delivery / final 里被等价保留下来
+- 优先抓：
+  - `missing object`
+  - `wrong relayer`
+  - `over-merged object`
+  - `raw class lost`
+
+判断标准：
+
+- 优先用 `fid`
+- 没有 `fid` 时，再退回 `geometry + stable legacy properties`
+- 至少要保留：
+  - 原始 `source_layer`
+  - 原始危险物/航标细分类
+  - 能追回原始对象的锚点
+
+这是“硬门槛”：
+
+- 如果对象已经丢了
+- 或者对象被归并成别的对象
+- 那么不允许进入“渲染已通过”的判断
+
+### 2. Render Audit
+
+目标：
+
+- 在“对象没丢”的前提下，检查它有没有被正确渲染
+
+重点看：
+
+- icon 是否存在
+- text 是否存在
+- fill / line / outline 是否存在
+- source-layer 是否消费正确
+- style layer 是否命中正确
+
+这一层回答的是：
+
+- 原始版渲染了多少对象
+- 现在渲染了多少对象
+- 哪些对象从“有 icon/text”变成了“没有”
+
+### 3. Visual / AOI Audit
+
+目标：
+
+- 用固定页面和固定热点去验证“现在具体是怎么画出来的”
+
+当前固定页面：
+
+- `http://192.168.200.184/newpec/navsea-compare-karatsu-20nm.html`
+
+这一层只做两件事：
+
+- 校准 backend render audit 的盲区
+- 验证 style 修改是否真的把用户看到的问题修掉了
+
+这一层不能替代前两层。
+
+## Current Ground Truth
+
+截至 2026-04-01，当前项目的真实状态是：
+
+### A. 20nm Visual Baseline
+
+固定视觉审计页：
+
+- `http://192.168.200.184/newpec/navsea-compare-karatsu-20nm.html`
+
+用途：
+
+- 肉眼确认
+- 点击拾取
+- AOI 热点截图审计
+
+它是当前唯一固定的视觉基线。
+
+### B. 10nm Object-Level Backend Baseline
+
+当前最可信的对象级 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)
+
+原因：
+
+- 这条线还能较可靠地对象回对
+- `missing / extra / mismatch` 的意义相对稳定
+
+### C. 20nm Backend Audit Limitation
+
+当前 `20nm` backend render audit 能提供信号，但不能独立作为严格对象级放行依据。
+
+它能告诉我们：
+
+- 哪一层整体有问题
+- 哪类 icon/text 大量不一致
+
+但它不能稳定告诉我们：
+
+- 某一个具体 `fid` 是否等价保留下来了
+
+例如：
+
+- `icon_missing_in_engineering | p航行危険障害物 | 664`
+- `extra_icon_in_engineering | navigation_hazard_point | 664`
+
+这说明“这一层出问题了”，但不能自动定位到：
+
+- `fid=13025299` 这种具体对象为什么消失
+
+## Audit Evolution
+
+下面是审计方法升级到现在的过程。
+
+### Phase 0: General Engineering Audit
+
+最早主要是：
+
+- 原始版 vs engineering 版
+- 看总体 render compatibility
+
+代表报告：
+
+- [`NavSea_Original_vs_Engineering_Render_Audit_Karatsu_10nm.md`](/root/sourceserver/pbf/NavSea_Original_vs_Engineering_Render_Audit_Karatsu_10nm.md)
+- [`NavSea_Original_vs_Engineering_Render_Audit_Kyushu.md`](/root/sourceserver/pbf/NavSea_Original_vs_Engineering_Render_Audit_Kyushu.md)
+
+这一阶段解决的是：
+
+- 整体链路能不能跑
+- 原始 layer 和工程 layer 有没有大体对上
+
+问题：
+
+- 太偏“工程验证”
+- 还不是 delivery 收口口径
+
+### Phase 1: Delivery Render Audit
+
+开始转向：
+
+- 原始版 vs delivery 版
+
+代表报告：
+
+- [`NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.md`](/root/sourceserver/pbf/NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.md)
+- [`NavSea_Original_vs_Delivery_Render_Audit_Karatsu_20nm_2026-03-31.md`](/root/sourceserver/pbf/NavSea_Original_vs_Delivery_Render_Audit_Karatsu_20nm_2026-03-31.md)
+
+这一阶段的升级点：
+
+- 开始看真正 delivery 产物
+- 开始统计：
+  - `exact_match`
+  - `mismatch`
+  - `missing_in_engineering`
+  - `extra_in_engineering`
+
+问题：
+
+- `20nm delivery` 这条线在去旧字段后，trace-back anchor 不够
+- 所以 `20nm` 很快变成“层级粗审可用，对象精审不稳”
+
+### Phase 2: FID-Only / Refresh Variants
+
+为了继续挤出更多对象级信息，出现了几种变体：
+
+- `fidonly`
+- `refresh`
+- `r7`
+
+代表报告：
+
+- [`NavSea_Original_vs_Delivery_Render_Audit_Karatsu_20nm_2026-03-31.fidonly.md`](/root/sourceserver/pbf/NavSea_Original_vs_Delivery_Render_Audit_Karatsu_20nm_2026-03-31.fidonly.md)
+- [`NavSea_Original_vs_Delivery_Render_Audit_Karatsu_20nm_2026-03-31.refresh.md`](/root/sourceserver/pbf/NavSea_Original_vs_Delivery_Render_Audit_Karatsu_20nm_2026-03-31.refresh.md)
+- [`NavSea_Original_vs_Delivery_Render_Audit_Karatsu_20nm_2026-03-31.r7.md`](/root/sourceserver/pbf/NavSea_Original_vs_Delivery_Render_Audit_Karatsu_20nm_2026-03-31.r7.md)
+
+这一阶段的升级点：
+
+- 尽量靠 `fid`
+- 尽量把样式改动后的 20nm 页面状态也纳入
+
+问题：
+
+- 仍然是“20nm 全局层级信号大于对象级信号”
+- 能看出层整体有问题，但很难直接精确锁到某个对象
+
+### Phase 3: 10nm Rerun As Trusted Backend Baseline
+
+这是一次关键收口。
+
+代表报告：
+
+- [`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)
+
+这一阶段的升级点：
+
+- 明确承认：
+  - `20nm` 不是当前最可信对象级 backend baseline
+  - `10nm rerun` 才是
+
+意义：
+
+- 后端对象级判定终于有了一条相对稳定的参考线
+
+局限：
+
+- 它解决的是“对象级 backend 可信度”
+- 不能代替 `20nm compare` 的视觉确认
+
+### Phase 4: Unified Strict Audit
+
+为了解决“后台数字和肉眼感受不一致”，引入了 strict audit。
+
+核心脚本：
+
+- [`navsea_strict_audit.py`](/root/sourceserver/pbf/navsea_strict_audit.py)
+
+代表报告：
+
+- [`report/strict_audit/strict_audit_summary.md`](/root/sourceserver/pbf/report/strict_audit/strict_audit_summary.md)
+- [`report/strict_audit_final_20nm/strict_audit_summary.md`](/root/sourceserver/pbf/report/strict_audit_final_20nm/strict_audit_summary.md)
+
+这一阶段的升级点：
+
+- 把浏览器真实截图差异
+- 和 backend render audit 摘要
+- 放进同一份报告
+
+问题：
+
+- 一开始还是偏整屏 diff
+- 太粗，不能指导具体修复
+
+### Phase 5: Small Scope AOI Audit
+
+这是最近一次重要升级。
+
+方法文档：
+
+- [`NavSea_20nm_Small_Scope_Audit_Method.md`](/root/sourceserver/pbf/NavSea_20nm_Small_Scope_Audit_Method.md)
+
+热点配置：
+
+- [`strict_audit_hotspots_20nm_pilot.json`](/root/sourceserver/pbf/strict_audit_hotspots_20nm_pilot.json)
+- [`strict_audit_hotspots_20nm.json`](/root/sourceserver/pbf/strict_audit_hotspots_20nm.json)
+
+这一阶段的升级点：
+
+- 不再只看整屏 diff
+- 改成看固定热点 AOI
+- 每个热点绑定 backend focus
+
+意义：
+
+- 更适合修 style
+- 更适合校准 icon/text/sprite/runtime 盲区
+
+当前问题：
+
+- 热点覆盖还不全
+- 例如 `荒曽根/大曽根` 这块危险物区当前就不在热点里
+
+## Why Serious Missing-Object Issues Still Escaped
+
+像 `fid=13025299` 这种“左边有、右边没有等价对象”的情况，之所以还能漏过，是因为当前审计仍有 3 个盲点。
+
+### 1. 20nm Backend Audit Is Layer-Level, Not Fid-Level Enough
+
+它会报：
+
+- 这一层整体少了 icon
+- 这一层整体多了 icon
+
+但不自动报：
+
+- 哪个 `fid`
+- 哪个 `class_code`
+- 是“丢对象”还是“错误归并”
+
+### 2. Hazard Semantics Are Too Coarse In Builder
+
+当前 builder 对：
+
+- `p航行危険障害物`
+- `p投錨注意障害物`
+
+的语义推断太粗，很多对象只剩：
+
+- `fish_reef`
+- `wreck`
+- `obstruction`
+- `hazard_mark`
+
+这会导致原始 `409` 这种细分类在 delivery 线中失真。
+
+### 3. AOI Visual Audit Coverage Is Incomplete
+
+当前热点更偏：
+
+- 高岛主港
+- 高岛近岸
+- 东侧防波堤
+
+还没有覆盖：
+
+- `荒曽根 / 大曽根` 这类危险物密集区
+
+## Current Official Audit Logic
+
+从现在开始，项目内应统一采用下面这套逻辑。
+
+### Audit Gate 1: Object Preservation Gate
+
+必须回答：
+
+- 原始对象是否还在
+- 是否仍能等价追踪
+- 是否被错误归并成别的对象
+
+建议新增专项：
+
+- `hazard object preservation audit`
+  - 按 `fid`
+  - 按原始 `source_layer`
+  - 按原始 `分類番号`
+
+### Audit Gate 2: Render Gate
+
+只有对象保真过了，才进入这层。
+
+必须回答：
+
+- 原始渲染了多少对象
+- 现在渲染了多少对象
+- 哪些对象有 icon/text/fill/line 差异
+
+### Audit Gate 3: AOI Visual Gate
+
+最后才是：
+
+- 固定 compare 页
+- 固定 AOI 热点
+- 点击拾取核对
+
+目的：
+
+- 验证用户肉眼看到的问题是否已经真的修掉
+
+## Recommended Next Upgrade
+
+当前最该补的不是新的 style，而是新的审计能力。
+
+建议下一步按这个顺序升级：
+
+1. 新增 `hazard preservation audit`
+   - 专门检查：
+     - `p航行危険障害物`
+     - `p投錨注意障害物`
+   - 输出：
+     - 原始 `fid`
+     - 原始 `分類番号`
+     - delivery `class_code`
+     - 是否 still equivalent
+
+2. 增加 `fid watchlist audit`
+   - 可以直接追像 `13025299` 这种 fid
+   - 输出 raw / delivery / final 的对照
+
+3. 扩充 AOI 热点
+   - 把 `荒曽根 / 大曽根` 危险物区加入热点配置
+
+4. 最后再改 builder
+   - 为 `409` 这类对象增加显式保真规则
+
+## Current One-Sentence Rule
+
+当前项目的正式审计规则可以压成一句话：
+
+- 先审“对象有没有丢”，再审“渲染有没有错”，最后才审“视觉像不像”。
+

STEP_RECORD.md

@@ -169,6 +169,7 @@ Remote: `ssh://git@nas:2222/tei/pbf.git`
 当前小范围试验方法文档：
 
 - [`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 热点配置：
 
@@ -184,6 +185,10 @@ Remote: `ssh://git@nas:2222/tei/pbf.git`
 - 不再只看整屏 diff
 - 不再只看 `20nm` backend 总量数字
 - `20nm` backend 仍不适合当严格对象级审计
+- 当前正式审计顺序已经明确为：
+  - 先 `object preservation audit`
+  - 再 `render audit`
+  - 最后 `AOI / visual audit`
 
 ## Current Audit Status