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`](/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)

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