CM95/docs/CM95_S52_静态物化与运行时呈现边界_v1.md

CM95 S-52 静态物化与运行时呈现边界 v1

1. 目的

本文件冻结 CM95 → PBF → NavSea 链路中 S-52 Presentation 的责任边界，避免把船员可修改的显示参数提前固化进全国 PBF。

核心原则：PBF 保存海图事实、稳定语义和与船员设置无关的静态 Presentation 提示；NavSea Runtime 负责随用户设置变化的 Presentation 结果。

S52MarinerSettings 继续保留，但只作为 OpenCPN/S-52 对照渲染的固定参考配置，不再作为 NavSea Delivery PBF 的唯一真值。

2. 两种模式

2.1 runtime

runtime 是 NavSea Delivery 的默认方向。

对于依赖船员水深设置的 CSP，不在 PBF 构建阶段决定最终颜色、安全等深线、浅深测深字形或 isolated danger 最终状态，而是保留 CSP 名称和运行时所需事实字段。

当前 v1 延迟到 Runtime 的 CSP：

• DEPARE01
• DEPARE02
• DEPCNT02
• SOUNDG02
• OBSTRN04
• WRECKS02

2.2 reference

reference 用于 OpenCPN/S-52 对照、PoC 和回归验证。

该模式继续使用固定 S52MarinerSettings：

• shallow_contour_m = 2.0
• safety_contour_m = 3.0
• safety_depth_m = 3.0
• deep_contour_m = 6.0
• two_shades = false

只有该模式允许把上述参数推导出的最终 CSP 结果物化到 PBF，用于参考画面对照；这些结果不得被当作 NavSea 用户运行时的永久真值。

3. PBF 中必须保留的事实

水深相关事实至少包括：

• DEPARE/DRGARE：depth_min_m、depth_max_m
• DEPCNT：contour_depth_m，同时兼容现有 least_depth_m
• SOUNDG：depth_value_m / s52_sounding_depth_m
• 危险物：s52_hazard_depth_m
• 与 isolated danger 判断相关的 WATLEV、EXPSOU、CATOBS、CATWRK、QUAPOS、QUASOU、TECSOU、STATUS 归一化运行时字段
• 相交水深区摘要：s52_surrounding_max_drval1_m、s52_surrounding_min_drval2_m

运行时 CSP 通过：

• s52_mariner_dependent = 1
• s52_runtime_csp = <CSP>
• 未解析的 s52_csp

明确标识。

4. 不得在 runtime PBF 中固定的结果

以下结果依赖用户/船员设置，不得作为 runtime PBF 的永久真值：

• DEPARE 最终浅水/中水/深水颜色
• s52_is_safety_contour
• s52_sounding_prefix
• s52_sounding_is_shallow
• 由 safety contour 决定的 s52_isolated_danger
• 由 isolated danger 引起的 DisplayBase promotion
• 由 safety depth/contour 决定的危险物最终符号

two_shades 同样属于运行时设置，由 DEPARE Runtime Presentation 处理。

5. 仍可静态物化的内容

与船员设置无关、只依赖对象属性和固定 S-52 规则的内容继续在服务器物化，例如：

• LIGHTS05 的灯色、sector 几何、灯质文本和静态符号提示
• TOPMAR01 在已确定 floating/rigid 上下文后的符号
• QUAPOS01、SLCONS03、RESTRN01 等与船员水深阈值无关的 CSP
• 静态 TX/TE
• 静态 SY/LS/LC/AP/AC/CA
• Lookup 自身的 Display Category / Display Priority，除非 CSP 在运行时明确覆盖

6. 对四个待修问题的重新分类

6.1 DisplayBase promotion

UDWHAZ03 导致的 DisplayBase promotion 属于 mariner-dependent runtime presentation。

因此 runtime PBF 不应把当前固定 safety contour 推导出的 s52_display_base_promoted=1 写成永久结果。reference 模式仍可保留该行为用于对照。

6.2 OP priority override

OP(...) 本身属于 Presentation Rule IR。

• 静态 Lookup/静态 CSP 中的 OP：服务器可物化并正确覆盖 s52_display_priority
• mariner-dependent CSP 中的 OP：必须随 Runtime CSP 一起延迟执行

6.3 多个 SY/LS

多个 SY、多个 LS 属于静态规则序列保真问题，与船员水深设置无关，下一阶段应完整保留顺序，不能只取第一条。

6.4 SY ORIENT

通用 SY(symbol, ORIENT) 的旋转角属于对象/规则事实，不属于船员水深设置；下一阶段应加入 PBF Presentation Contract，并保留属性引用解析后的角度。

7. Symbolized Boundaries

Plain / Symbolized Boundaries 本质上也是 mariner presentation 设置，但它会影响 Area Lookup Table 本身，不只是单个 CSP 的输出。

因此 v1 不把它伪装成已完全 runtime 化：

• 当前 runtime 模式先解决水深阈值、测深、危险物等深度相关动态结果；
• s52_boundary_table 暂时仍用于参考/编译路径；
• 后续由 S-52 Style Compiler / NavSea Runtime 同时持有 Plain 与 Symbolized 规则后，再彻底从 PBF 构建参数中移除该选择。

8. CLI 约定

build-tile 与 build-sample-aoi 增加：

--s52-mariner-mode runtime|reference

默认值为 runtime。

OpenCPN 对照或需要固定参考画面的任务必须显式使用 reference，避免参考参数误进入 NavSea 正式 PBF。

9. 本轮后续修复状态

边界冻结后，本轮已经继续完成四项 Presentation 物化修复：

1. 静态 OP(...) 已能按 S-52 priority code 覆盖 s52_display_priority，并保留 s52_priority_override；
2. 多 LS 已新增 s52_line_sequence / s52_line_count，多 SY 保留 s52_symbol_sequence 并新增 s52_symbol_count；
3. SY(symbol, ORIENT) 已解析对象属性角度，新增 s52_symbol_rotation_deg、s52_symbol_rotation_source 与 s52_symbol_rule_sequence；
4. reference 模式中的 isolated danger 已将 Display Category 提升为 Displaybase、Display Priority 提升为 Hazards；runtime 模式只保留事实与 CSP，不固化该结果。

后续应进入单 tile PBF 合同回归和 NavSea Runtime 消费接口设计，而不是重新把上述结果烧回全国 PBF。