pbf/NavSea_Delivery_Preflight_Audit_Spec.md

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 已经覆盖：

• 物体级 render observation 对比
• 标注缺失专项
• Style 语义专项
• 按 tile instance 粒度输出 Markdown / JSON 报告

当前仍未完全自动化的部分：

• 场景窗口审计
• 部署一致性自动校验
• 航海版 / 钓鱼版双阈值硬门禁
• 已登记等价表达规则的自动判定

因此，在这些能力补齐前：

• 自动审计报告只能视为主证据
• 固定样区人工复核仍是强制步骤

13. 规范与现有文档关系

本规范是交付前的执行规范。

相关上位和配套文档：

• NavSea_Chart_Domain_Model_v1.md
• NavSea_Legacy_Field_Exit_Roadmap.md
• NavSea_Original_vs_Delivery_Render_Audit_Karatsu_20nm.md

后续如航海版与钓鱼版正式拆分，应在本规范下再各自补一份专项验收细则。