CM95/docs/CM95_S52_NavSea运行时呈现契约_v1.md

CM95 S-52 NavSea 运行时呈现契约 v1

1. 目标

本契约定义 NavSea 如何消费 CM95 Delivery PBF 中的 S-52 海图事实，并在用户修改水深、安全等深线或颜色设置后立即重新呈现，而不重新生成、下载或替换 PBF。

本契约只规定数据与算法责任边界，不在 CM95 Server 中实现 NavSea UI，也不把 NavSea Store/业务生命周期引入 PBF Builder。

2. 总体责任

CM95/PBF 负责

• 几何；
• 原始水深事实的规范化数值；
• Lookup identity 与静态 S-52 Presentation 提示；
• 与用户设置无关的属性派生；
• runtime CSP 所需的最小事实；
• 不可从单个 Feature 自身恢复的必要空间上下文摘要。

NavSea Runtime 负责

• 当前用户的水深颜色设置；
• shallowContour / safetyContour / safetyDepth / deepContour；
• twoShades；
• safety contour 实际选择；
• SOUNDG 深/浅字形；
• OBSTRN/WRECKS isolated danger；
• isolated danger 引起的 DisplayBase / priority promotion；
• 设置变化后的即时重算和 MapLibre style 更新。

3. Runtime Settings

建议 NavSea 运行时形成一个统一的只读快照，例如：

S52MarinerRuntimeSettings
  shallowContourM
  safetyContourM
  safetyDepthM
  deepContourM
  twoShades
  depthColorRules

depthColorRules 属于 NavSea 现有的用户自定义显示能力，可以独立于 S-52 四个标准深度阈值。服务器不得把用户颜色写入 PBF。

一次重算必须使用同一个 settings snapshot，避免 DEPARE、DEPCNT、SOUNDG 与 hazard 在同一帧使用不同设置。

4. PBF Runtime 字段

DEPARE / DRGARE

主要字段：

• depth_min_m
• depth_max_m
• s52_runtime_csp = DEPARE01 | DEPARE02

chart_fill_style 仅作为当前 NavSea 既有 style 的兼容语义，不应覆盖精确 depth_min_m/depth_max_m 的事实地位。

DEPCNT

主要字段：

• contour_depth_m
• least_depth_m（兼容）
• s52_runtime_csp = DEPCNT02
• s52_quapos_code（有值时）

SOUNDG

主要字段：

• depth_value_m
• s52_sounding_depth_m
• s52_sounding_swept
• s52_sounding_low_quality
• s52_runtime_csp = SOUNDG02

OBSTRN / UWTROC / WRECKS

主要字段：

• s52_hazard_depth_m
• s52_surrounding_max_drval1_m
• s52_surrounding_min_drval2_m
• s52_watlev_code
• s52_expsou_code
• s52_catobs_code
• s52_catwrk_code
• s52_quapos_code
• s52_quasou_codes
• s52_tecsou_codes
• s52_status_codes
• s52_runtime_csp = OBSTRN04 | WRECKS02

数组类 code 在 Delivery MVT 中以 JSON 字符串保存，NavSea Adapter 负责一次标准化解析，不由 MapLibre style 直接解析 JSON。

5. DEPARE 运行时规则

NavSea 可以有两层规则：

1. 用户自定义 depthColorRules 优先决定颜色；
2. 未启用自定义颜色时，可按 S-52 DEPARE01/02 的 shallow/safety/deep/twoShades 规则得到标准颜色角色。

颜色计算以 PBF 的精确 depth_min_m/depth_max_m 为输入。用户修改阈值只改变已有 DEPARE polygon 的显示，不生成原海图不存在的新等深边界，也不在客户端重新切割 polygon。

因此，例如原始海图区间为 5–10m，用户将颜色阈值设为 7m，NavSea 可以按规则重新给整个 5–10m 区域着色，但不能假装原数据中存在一条精确的 7m 面边界。

6. DEPCNT 与 safety contour

contour_depth_m 是事实；s52_is_safety_contour 是运行时结果。

规则语义保持：

• 若存在与 safetyContourM 相等的实际等深线，选该深度；
• 否则选择下一条更深的实际等深线；
• 不允许服务器把默认 3m 的选择永久写入 runtime PBF。

这里不能只靠单个 Feature 的 MapLibre expression 完成“下一条更深”判断，因为它需要知道可用 contour depth 集合。

NavSea Runtime 因此需要维护稳定的 ContourCatalog（按当前有效海图/尺度上下文的已知等深值排序），先计算：

effectiveSafetyContourM = min(depth >= safetyContourM)

再把该值注入 DEPCNT style expression。

若当前没有足够的 ContourCatalog 信息，必须 fail-closed：不错误突出某一条线为 safety contour。后续若 Runtime 收集 catalog 的成本过高，可在 PBF 契约增加相邻等深值元数据，但 v1 不先制造新的冗余字段。

7. SOUNDG 运行时规则

SOUNDG 的数值深度、扫测状态和质量状态是事实；SOUNDS* / SOUNDG* 前缀及最终 symbol sequence 属于运行时结果。

核心规则：

depth <= safetyDepthM  -> shallow sounding family
otherwise              -> normal sounding family

随后根据 swept / low-quality 和数值位数生成最终 S-52 symbol sequence。

用户修改 safetyDepthM 后只需重新计算当前可见 SOUNDG 的 presentation，不重新加载 PBF。

8. Hazard / isolated danger 运行时规则

OBSTRN/WRECKS 必须根据同一个 safetyContourM settings snapshot 重新执行对应 CSP。

PBF 中的 hazard depth、WATLEV、EXPSOU、QUASOU 等是输入事实；以下均为运行时输出，不能直接信任旧 tile 中的固定值：

• isolated danger yes/no；
• ISODGR51 等最终符号；
• DisplayBase promotion；
• Hazards priority promotion；
• hazard 内附带 sounding 的 shallow/normal 字形。

当前 PBF 已将相交 DEPARE 的必要深度摘要一起交付，避免 NavSea 为每个 hazard 再做昂贵的 polygon 空间相交。

9. 静态 Presentation

以下不依赖水深 mariner settings 的属性仍可直接消费 PBF 物化结果：

• LIGHTS05 静态结果；
• TOPMAR01；
• 静态 TX/TE；
• 静态 SY/LS/LC/AP/AC/CA；
• s52_symbol_sequence / s52_line_sequence；
• s52_symbol_rotation_deg；
• 静态 OP 已应用后的 s52_display_priority。

NavSea 不应为这些规则重复实现一套与 Server 不同的 Lookup 解释器。

10. MapLibre Adapter 边界

建议 NavSea 增加一个纯 Presentation Adapter，而不是把判断分散到各个 UI/Layer：

PBF feature properties
        +
S52MarinerRuntimeSettings snapshot
        +
ContourCatalog
        ↓
S52RuntimePresentationAdapter
        ↓
normalized render properties / style expressions
        ↓
MapLibre

Adapter 不获取网络、不修改用户设置、不拥有 PBF 下载生命周期，只做确定性转换。

11. 设置变化

用户修改任何 mariner setting 后：

1. 形成新的 settings snapshot；
2. 更新 effective safety contour；
3. 重新生成/更新 DEPARE、DEPCNT、SOUNDG、hazard 对应 style/runtime properties；
4. 请求 MapLibre repaint；
5. 不清 tile cache，不重新下载 PBF，不重新生成 Server 数据。

禁止继续显示基于旧 settings 推导的 safety contour / isolated danger / sounding shallow 状态。

12. Fail-closed

• 缺少精确水深事实时，不凭颜色或旧派生字段反推水深；
• 缺少 ContourCatalog 时，不伪造 safety contour；
• hazard 所需事实不足时，保留普通危险物显示，但不错误声明 isolated danger；
• JSON code 字段解析失败时，视为空集合并记录诊断；
• 运行时设置无效时回退 NavSea 明确定义的默认 settings snapshot，而不是使用 PBF 内历史派生值。

13. v1 暂未纳入

Plain / Symbolized Boundaries 会改变 Area Lookup Table 选择，尚未完全纳入上述 runtime Adapter。第一版继续沿用当前 boundary table 编译路径；待 NavSea/Style Compiler 能同时持有 Plain 与 Symbolized 两套 Area rule 后再统一运行时切换。

14. 接入门槛

NavSea 正式消费 runtime PBF 前至少验证：

• 修改水深颜色不触发 PBF 网络请求；
• 修改 safety depth 后 SOUNDG 即时变化；
• 修改 safety contour 后 DEPCNT 和 hazard 使用同一个新值；
• runtime PBF 中不存在旧固定 s52_is_safety_contour / s52_isolated_danger 等结果；
• reference PBF 仍可用于 OpenCPN 对照；
• 同一设置、同一 Feature 输入必须得到确定性相同输出。