pbf/NavSea_Legacy_Field_Exit_Roadmap.md

NavSea 摆脱旧字段体系路线图

目标：让 NavSea 的使用版样式与交付版 pbf 不再依赖旧海图字段体系，最终做到：

• 样式主逻辑不再直接读取 分類番号
• 样式主逻辑不再直接读取 形状分類番号
• 样式主逻辑不再直接读取 表示用番号
• 样式主逻辑不再直接读取 灯色、灯略記、明弧/分孤
• 检索和渲染都优先依赖 canonical_* 与 chart_*

1. 当前状态

当前使用版已经迈出第一步，但还没有真正摆脱旧字段体系。

1.1 已完成

• fid 已替换为 NavSea 自有 16 进制 ID
• canonical_family
• canonical_object_type
• detection_key
• semantic_key
• render_layer

1.2 仍未完成

当前使用版样式仍直接读取这些旧字段：

• 分類番号
• 形状分類番号
• 表示用番号
• 灯色
• 灯略記
• 表示位置
• 名称
• 名称補助
• 日本語地名
• 英文字地名
• 水深値(m)
• 高さ/深度(m)

说明：

• 其中 名称、名称補助、日本語地名、英文字地名 不应视为要被完全淘汰的“坏字段”
• 它们属于内容字段，应保留或映射为 chart_label_*
• 真正要退出的是“旧渲染控制字段”

2. 旧字段退出的对象范围

优先退出的旧字段：

• 分類番号
• 形状分類番号
• 表示用番号
• 灯色
• 灯略記
• 明弧/分孤
• 表示位置
• 水深値(m)
• 高さ(m)
• 高さ/深度(m)
• 角度

不建议简单删除，而应先完成“等价替代字段”。

3. 对应的新字段体系

3.1 对象语义层

继续保留并强化：

• canonical_family
• canonical_object_type
• detection_key
• semantic_key

这层回答：

• 这个对象是什么

3.2 渲染语义层

必须补齐：

• chart_render_type
• chart_symbol_family
• chart_symbol_code
• chart_line_style
• chart_fill_style
• chart_text_style
• chart_priority
• chart_visibility_min
• chart_visibility_max
• chart_collision_group

这层回答：

• 这个对象应该怎么画

3.3 专项语义层

必须补齐：

• chart_label_text
• chart_label_subtext
• chart_label_anchor
• chart_label_dx
• chart_label_dy
• light_color_code
• light_character_code
• light_sector_mode
• hazard_class
• hazard_severity
• area_usage_class
• depth_value_m
• clearance_height_m
• least_depth_m
• bearing_deg

这层回答：

• 具体符号、文字和业务检索所需的细节是什么

4. 替代关系

4.1 灯标体系

旧字段：

• 形状分類番号
• 表示用番号
• 灯色
• 灯略記
• 明弧/分孤

新字段：

• chart_symbol_family=navigation_light 或 navigation_mark
• chart_symbol_code
• light_color_code
• light_character_code
• light_sector_mode
• chart_label_text
• chart_label_subtext

退出条件：

• 样式中灯标相关层不再直接 get 旧灯标字段

4.2 危险物/鱼礁体系

旧字段：

• 分類番号
• 表示用番号

新字段：

• canonical_object_type
• hazard_class
• hazard_severity
• chart_symbol_code
• chart_fill_style

退出条件：

• 危险物和鱼礁图形不再依赖旧编码号判断

4.3 等深线/水深体系

旧字段：

• 表示用番号
• 水深値(m)
• 高さ/深度(m)

新字段：

• chart_line_style
• chart_text_style
• depth_value_m
• least_depth_m

退出条件：

• 等深线粗细、类别和数字显示不再依赖旧字段

4.4 边界/区域体系

旧字段：

• 分類番号
• 表示用番号

新字段：

• canonical_object_type
• chart_line_style
• chart_fill_style
• area_usage_class

退出条件：

• 锚地、航路、鱼业区、危险界等区域表现不再用旧编码做主判断

4.5 地名体系

旧字段：

• 名称
• 名称補助
• 日本語地名
• 英文字地名
• 表示位置

新字段：

• chart_label_text
• chart_label_subtext
• chart_label_anchor
• chart_label_dx
• chart_label_dy
• chart_text_style

说明：

• 地名文本本身不是要淘汰的“旧体系”
• 要退出的是“用原始字段名直接驱动样式”的方式

5. 实施阶段

阶段 A：补齐数据字段

目标：

• builder 输出完整 chart_*
• builder 输出完整 light_*
• builder 输出完整 hazard_*
• builder 输出完整数值归一化字段

验收：

• 使用版 pbf 中，核心对象都能拿到可直接渲染的新字段

阶段 B：建立纯新字段样式

目标：

• 新样式不再直接读取 分類番号
• 新样式不再直接读取 形状分類番号
• 新样式不再直接读取 表示用番号

例外：

• 文本内容字段暂时允许保留

验收：

• style json 中 ["get", "..."] 不再出现旧渲染控制字段

阶段 C：做等价性审计

目标：

• 对比旧样式与新样式的主要对象覆盖
• 对比使用版旧字段驱动与新字段驱动的渲染结果
• 对比旧样式与新样式的语义表现是否一致
  • 不是只看“画没画出来”
  • 还要看“有没有画反”

Style 语义审计必须回答：

• 水上 / 水下 / 露出 / 干出 是否仍与旧样式一致
• render-support 层是否被错误强化为业务语义对象
• 深度数字、净空数字、灯标说明、危险物标记是否仍正确出现
• 是否存在“点击能命中，但地图上没显示关键数字/文字”的情况
• 交付前审计执行方式以 NavSea_Delivery_Preflight_Audit_Spec.md 为准

特别红线：

• P穴 -> hole_area 这类辅助层，必须忠于旧样式的支撑性表现
• 不允许因为新语义转译，把它画成陆地色、危险礁色或其他会误导航行判断的强语义表现

验收：

• 核心对象组通过审计：
  • 灯标
  • 危险物
  • 鱼礁
  • 等深线
  • 水深数字
  • 锚地/航路/鱼业区
  • 地名
• 航行关键语义不得出现“画反”：
  • 水下画成水上
  • 水上画成水下
  • 支撑层画成实体语义层

阶段 D：旧字段降级为兼容字段

目标：

• 使用版样式停止直接依赖旧渲染控制字段
• 旧字段只保留在数据里，供兼容、回查或历史对照

验收：

• 使用版样式完全跑在新字段体系上
• 工程版仍保留旧字段和 trace 以便审计

阶段 E：旧字段退场

目标：

• 仅在确认无样式、无检索、无检测依赖后，才从交付版中移除旧渲染控制字段

注意：

• 这不是近期动作
• 必须放在最后

6. 退出门禁

一个旧字段只有在同时满足以下条件时，才允许从使用版交付中移除：

• 已存在稳定的新字段替代
• 使用版样式不再直接读取它
• 检索规则不再直接读取它
• 碰撞或检测链路不再直接读取它
• 工程版仍能回查原值
• 审计报告确认关键对象渲染未明显退化
• Style 语义审计确认旧样式表现已被等价转译
• 不存在因删旧字段导致的航行关键语义误绘

7. 下一步最值得做的事

如果目标是“真正摆脱旧字段体系”，下一步最值得直接落地的是：

1. 在 builder 里补齐第一批 chart_* 字段
   重点对象：

   • 灯标
   • 危险物
   • 鱼礁
   • 等深线
   • 水深数字
   • 锚地/航路/鱼业区

2. 出一份“纯新字段样式”
   要求：

   • 不再读取 分類番号
   • 不再读取 形状分類番号
   • 不再读取 表示用番号

3. 对唐津 10 海里做一次新旧样式对照审计
   目标：

   • 看哪些对象已经可以完全脱离旧字段
   • 看哪些对象还需要旧字段兜底

8. 最终判断

完全摆脱旧字段体系是可行的，但前提不是“删除旧字段”，而是：

• 先补齐新字段
• 再迁移样式
• 再做等价性审计
• 最后才让旧字段退出主流程

一句话总结：

下一步不是“把旧字段删掉”，而是“把旧字段一项一项替换掉，直到样式和业务都不再依赖它们”。