# NavSea 交付前审计规范 ## 1. 目标 本规范用于约束 NavSea 在正式交付前的审计方式，确保： - 交付版 `pbf` 不依赖工程期映射字段即可完成渲染与点击说明 - 交付版 style 忠于旧版 style 的表现语义，而不是重新设计 - 不只是“对象还在”，还要确认“对象被正确解释并正确表现” - 不会因为语义转译、样式改写或字段裁剪而引入航行风险 本规范既适用于当前 `delivery pbf`，也适用于后续拆分出的： - 航海版 - 钓鱼版 ## 2. 核心原则 ### 2.1 旧版表现是基准 - 对航行安全相关对象，旧版 `pbf + style.json` 是表现基准 - 新版 style 的职责是把旧版表现语义转译到新字段体系，不是重新设计 - 只有经过明确登记和批准的差异，才允许故意偏离旧版表现 ### 2.2 审计重点是“解释与表现” - 不能只审“对象有没有” - 必须审“对象命中了哪些渲染层” - 必须审“命中的渲染层是否保持了旧版相同的语义” - 必须审“最终画面是否仍会让用户做出相同的安全判断” ### 2.3 安全对象从严，普通对象从宽 - 灯火、浮标、危险物、暗礁、潜堤、洗岩、露岩、浅水区、陆海边界、净空限制等属于硬门禁对象 - 地名、底质、一般说明文字等允许有限偏差，但不得影响安全判断 ### 2.4 render-support 不得被强化成业务语义 - `P穴 -> hole_area` 这类支撑层必须忠于旧版支撑性表现 - 不允许把辅助层画成会误导用户的实体语义对象 - 不允许把透明/挖空/弱表现对象画成陆地色、危险礁色或其他强语义实体色 ## 3. 适用范围 本规范覆盖以下交付物： - `pbf` - `style json` - 对比页面与公开部署版本 - 自动审计脚本生成的 Markdown / JSON 报告 本规范不替代工程期数据库审计。旧新字段映射、trace 和回查仍由数据库承担。 ## 4. 术语 ### 4.1 旧版基准 - 原始 `pbf` - 原始 `style.json` ### 4.2 候选交付版 - 待交付 `pbf` - 待交付 style ### 4.3 物体 - 同一个原始海图对象 - 审计时优先按 legacy `fid` 对齐 - 无 `fid` 时，回退到 `geometry + 稳定旧属性` ### 4.4 feature instance - 同一物体在不同 tile / zoom 下的具体实例 - 渲染审计保留 tile 实例粒度，因为渲染具有 zoom 敏感性 ### 4.5 render hit - 某个 feature instance 在某个 style layer 上实际命中的一次渲染观察 - 观察类型分为： - `fill` - `line` - `icon` - `text` ### 4.6 有效 render hit - 不只是“命中了某层” - 还要求该命中对最终画面有实际贡献 - 透明填充、零宽线、不可见 icon、空文本等不得被算作有效命中 ### 4.7 场景窗口 - 固定中心点、固定缩放级、固定 viewport 的对比视窗 - 用于检查对象间叠压、标签碰撞、底色覆盖、整体安全感知 ## 5. 用途分轨 ### 5.1 航海版 目标： - 保障航行安全 - 支撑通航判断、风险识别、航线设计和安全计算 特点： - 用户视角大面积、粗线条 - 危险物和航标优先级最高 - 表现必须忠于旧版海图安全语义 ### 5.2 钓鱼版 目标： - 保障安全 - 强调地形、深度、底质和海里有什么 特点： - 用户视角小面积、高细节 - 地形和深度优先级高于多数航海辅助对象 - 对安全对象仍从严，对非安全对象允许有选择地弱化 ### 5.3 两版共用红线 - 安全对象不得缺失 - 不得出现“水上 / 水下 / 露出 / 干出”语义画反 - 不得把 render-support 层强化为危险误导源 - 不得缺失会影响判断的深度数字、净空数字、灯标关键信息 ## 6. 审计分层 交付前审计必须按以下顺序执行。 ### 6.1 第一层：Style 有效性门禁 检查内容： - style JSON 语法合法 - MapLibre / Mapbox Style 规范校验通过 - source、sprite、glyph、tile URL 可达 - 公开部署页实际加载的是候选交付版 style，不是旧缓存或其他旧版本 不通过示例： - `paint.fill-color` 表达式参数个数错误 - `match` 分支标签类型错误 - 公开页面仍引用旧 style 或旧 tile ### 6.2 第二层：对象存在性门禁 检查内容： - 审计对象总量是否与旧版同量级 - 安全关键对象是否仍能在候选交付版中被对齐到 - 不允许因字段清理、layer 重命名、id 变更导致对象失联 允许差异： - 工程追溯字段移除 - layer 名由旧日文名变为新语义名 不允许差异： - 安全关键对象在交付版完全找不到 - 只能在数据库中回查到，但运行时对象不存在 ### 6.3 第三层：物体级 render-hit 审计 这是主审计层。 对每个 feature instance，分别执行： - 旧版 `pbf + 旧版 style` - 候选交付版 `pbf + 候选交付版 style` 并记录： - `hit_count_old` - `hit_count_new` - `hit_types_old` - `hit_types_new` - 每个 hit 的 payload - 颜色 - 图标名 - 线宽 - dash - 文本值 - anchor - pattern - opacity 比较规则： - 先比有效 hit 数 - 再比 hit 类型集合 - 最后比 hit payload 特别说明： - 不能只比 hit 数量 - 命中数量一致但 icon / color / line width 语义不同，仍算不通过 - 透明 fill、零宽线、空文本等无效 hit 不得充数 ### 6.4 第四层：Style 语义审计 这是物体级审计的强制子项。 必须回答： - 陆海主判定是否与旧版一致 - 水上 / 水下 / 露出 / 干出语义是否与旧版一致 - 危险物、潜堤、暗礁、浅水区等是否被误画成普通背景 - render-support 层是否被错误强化为实体业务语义对象 - 点击能命中但地图上没显示关键数字/文字的情况是否存在 当前重点专项至少包括： - `depth_numeric_missing` - `clearance_numeric_missing` - `safety_icon_missing` - `support_layer_strengthened_fill` ### 6.5 第五层：场景窗口审计 render-hit 审计不能完全覆盖标签碰撞、遮挡、底色覆盖、叠压顺序等上下文问题，因此必须有场景窗口审计兜底。 每个候选交付版至少要有固定样区集，覆盖： - 港口进出口 - 近岸浅水带 - 灯火和浮标密集区 - 暗礁 / 潜堤 / 危险障碍物密集区 - 等深线和深度数字复杂区 - 适合钓鱼的复杂海底地形区 每个样区必须固定： - 中心经纬度 - 缩放级 - viewport 尺寸 - 左右对比截图 - 样区关注对象 场景窗口审计用于回答： - 危险是否一眼可见 - 关键数字是否在可读位置出现 - 颜色和底色是否传达了正确语义 - 新旧整体判断是否一致 ### 6.6 第六层：风险分级门禁 所有差异都必须分级。 建议最低分为： - `P0`: 会直接影响航行安全或错误通航判断 - `P1`: 会明显误导用户对危险或限制的识别 - `P2`: 有视觉差异，但不改变主要判断 - `P3`: 样式细节偏差或非关键缺失 `P0` 示例： - 水下物画成陆地或露出 - 露出物画成水下 - 灯火、浮标、危险物主图标缺失 - 关键深度数字、净空数字缺失 - 陆海边界明显误画 通过条件： - `P0` 必须为 0 - `P1` 必须在批准阈值以下并有整改计划 - `P2/P3` 允许暂存，但必须进入差异清单 ### 6.7 第七层：公开部署一致性审计 必须确认： - 本地 style 与公开 style 内容一致 - 本地 tile 与公开 tile 内容一致 - 对比页和单页加载的是候选交付版，而不是缓存或旧版本 公开页一旦与本地待交付版本不一致，交付前审计视为未完成。 ## 7. 航海版与钓鱼版的通过标准 ### 7.1 航海版硬门禁 以下对象不得缺失或画反： - 灯台、灯標、灯浮標、灯立標、航路標識 - 危险障碍物、暗礁、洗岩、露岩、潜堤、沉船 - 陆地、岸线、浅水区、干潮帯、可通航边界 - 净空限制、高度限制、航路边界、锚地相关限制 - 水深数字、关键等深线、关键危险辅助注记 额外要求： - 颜色、图标、线型必须忠于旧版安全语义 - 不允许为了“画面更好看”而改变危险对象的识别方式 ### 7.2 钓鱼版硬门禁 以下对象必须优先正确： - 水深数字 - 等深线 - 海底线与海底地形 - 底质 - 鱼礁、障碍物、沉船、潜堤、暗礁 - 近岸结构和小范围危险物 钓鱼版允许： - 弱化部分纯航海辅助对象 - 用更强调地形的方式表现非安全信息 但仍不允许： - 安全对象画反 - 缺失会导致挂底、碰撞、搁浅误判的对象 ## 8. 漏洞与补洞办法 单纯“比每个物体 hit 了多少层”仍然有漏洞。本规范明确要求同时补上以下检查。 ### 8.1 count 不等于等价 漏洞： - 新旧都 hit 了 2 层，但其中一层图标或颜色语义不同 补洞： - 必须比 `type + payload`，不能只比 count ### 8.2 命中不等于可见 漏洞： - 透明 fill、零宽线、空文本也可能被算作命中 补洞： - 审计统计必须区分“命中”与“有效命中” ### 8.3 单对象通过不等于整体安全 漏洞： - 对象单独没问题，但放进场景后被遮挡、碰撞或底色误导 补洞： - 固定样区做场景窗口审计 ### 8.4 旧新版不一定层数一一对应 漏洞： - 旧版 `1 icon`，新版可能拆成 `arc + symbol` - 或旧版 `fill + pattern`，新版用等价组合表达 补洞： - 审计允许“等价表达”，但必须登记等价规则 - 等价规则未经登记，不得自行解释为通过 ### 8.5 航海版和钓鱼版不能用同一把尺子 漏洞： - 同一条差异，对航海版是 `P0`，对钓鱼版可能是 `P2` 补洞： - 风险分级和通过阈值必须分轨维护 ## 9. 审计输出要求 每次交付前至少输出以下内容： - 一份 Markdown 审计报告 - 一份 JSON 审计明细 - 一份样区截图包 - 一份差异清单 - 一份例外清单 Markdown 报告至少包含： - 审计范围 - 匹配口径 - 总体结果统计 - 主要问题层 - 标注专项问题 - Style 语义专项问题 - `P0/P1/P2/P3` 分布 - 场景窗口结论 - 是否通过 JSON 明细至少包含： - 物体标识 - tile 实例信息 - 旧版命中 - 新版命中 - 差异类型 - 风险等级 - 是否属于航海版硬门禁对象 - 是否属于钓鱼版硬门禁对象 ## 10. 通过与不通过判定 交付版只有在同时满足以下条件时，才允许进入正式交付： - Style 有效性门禁通过 - 对象存在性门禁通过 - 物体级 render-hit 主审计通过 - Style 语义审计通过 - 场景窗口审计通过 - `P0 = 0` - 公开部署一致性审计通过 下列任一情况直接判定不通过： - 安全对象完全失去渲染 - 安全对象出现语义画反 - render-support 层被画成强实体语义对象 - 关键深度数字、净空数字、灯标主注记缺失 - 公开部署版本与本地待交付版本不一致 ## 11. 例外管理 若确有必要故意偏离旧版表现，必须登记： - 对象类型 - 影响范围 - 偏离原因 - 新旧差异说明 - 风险等级 - 批准人 - 回滚方式 未登记例外一律按缺陷处理。 ## 12. 当前脚本实现边界 当前 [`navsea_render_audit.py`](/root/sourceserver/pbf/navsea_render_audit.py) 已经覆盖： - 物体级 render observation 对比 - 标注缺失专项 - Style 语义专项 - 按 tile instance 粒度输出 Markdown / JSON 报告 当前仍未完全自动化的部分： - 场景窗口审计 - 部署一致性自动校验 - 航海版 / 钓鱼版双阈值硬门禁 - 已登记等价表达规则的自动判定 因此，在这些能力补齐前： - 自动审计报告只能视为主证据 - 固定样区人工复核仍是强制步骤 ## 13. 规范与现有文档关系 本规范是交付前的执行规范。 相关上位和配套文档： - [`NavSea_Chart_Domain_Model_v1.md`](/root/sourceserver/pbf/NavSea_Chart_Domain_Model_v1.md) - [`NavSea_Legacy_Field_Exit_Roadmap.md`](/root/sourceserver/pbf/NavSea_Legacy_Field_Exit_Roadmap.md) - [`NavSea_Original_vs_Delivery_Render_Audit_Karatsu_20nm.md`](/root/sourceserver/pbf/NavSea_Original_vs_Delivery_Render_Audit_Karatsu_20nm.md) 后续如航海版与钓鱼版正式拆分，应在本规范下再各自补一份专项验收细则。