diff --git a/AGENTS.md b/AGENTS.md index 3e8934d..c8be928 100644 --- a/AGENTS.md +++ b/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_Semantic_Package_Overlay_Design.md`](/root/sourceserver/pbf/NavSea_Semantic_Package_Overlay_Design.md) +5. [`NavSea_Chart_Domain_Model_v1.md`](/root/sourceserver/pbf/NavSea_Chart_Domain_Model_v1.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: diff --git a/NavSea_Audit_Logic_And_Evolution_2026-04-01.md b/NavSea_Audit_Logic_And_Evolution_2026-04-01.md new file mode 100644 index 0000000..d265e19 --- /dev/null +++ b/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 + +当前项目的正式审计规则可以压成一句话: + +- 先审“对象有没有丢”,再审“渲染有没有错”,最后才审“视觉像不像”。 + diff --git a/STEP_RECORD.md b/STEP_RECORD.md index 04f33eb..8cefe8f 100644 --- a/STEP_RECORD.md +++ b/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