Initial import of NavSea pbf project

2026-03-17 19:48:15 +08:00
commit 5f3f7409b3
84 changed files with 43889 additions and 0 deletions
--- a/NavSea_Legacy_Field_Exit_Roadmap.md
+++ b/NavSea_Legacy_Field_Exit_Roadmap.md
@@ -0,0 +1,347 @@
+# 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：做等价性审计
+
+目标：
+
+- 对比旧样式与新样式的主要对象覆盖
+- 对比使用版旧字段驱动与新字段驱动的渲染结果
+
+验收：
+
+- 核心对象组通过审计：
+  - 灯标
+  - 危险物
+  - 鱼礁
+  - 等深线
+  - 水深数字
+  - 锚地/航路/鱼业区
+  - 地名
+
+## 阶段 D：旧字段降级为兼容字段
+
+目标：
+
+- 使用版样式停止直接依赖旧渲染控制字段
+- 旧字段只保留在数据里，供兼容、回查或历史对照
+
+验收：
+
+- 使用版样式完全跑在新字段体系上
+- 工程版仍保留旧字段和 trace 以便审计
+
+## 阶段 E：旧字段退场
+
+目标：
+
+- 仅在确认无样式、无检索、无检测依赖后，才从交付版中移除旧渲染控制字段
+
+注意：
+
+- 这不是近期动作
+- 必须放在最后
+
+## 6. 退出门禁
+
+一个旧字段只有在同时满足以下条件时，才允许从使用版交付中移除：
+
+- 已存在稳定的新字段替代
+- 使用版样式不再直接读取它
+- 检索规则不再直接读取它
+- 碰撞或检测链路不再直接读取它
+- 工程版仍能回查原值
+- 审计报告确认关键对象渲染未明显退化
+
+## 7. 下一步最值得做的事
+
+如果目标是“真正摆脱旧字段体系”，下一步最值得直接落地的是：
+
+1. 在 builder 里补齐第一批 `chart_*` 字段  
+   重点对象：
+   - 灯标
+   - 危险物
+   - 鱼礁
+   - 等深线
+   - 水深数字
+   - 锚地/航路/鱼业区
+
+2. 出一份“纯新字段样式”  
+   要求：
+   - 不再读取 `分類番号`
+   - 不再读取 `形状分類番号`
+   - 不再读取 `表示用番号`
+
+3. 对唐津 10 海里做一次新旧样式对照审计  
+   目标：
+   - 看哪些对象已经可以完全脱离旧字段
+   - 看哪些对象还需要旧字段兜底
+
+## 8. 最终判断
+
+完全摆脱旧字段体系是可行的，但前提不是“删除旧字段”，而是：
+
+- 先补齐新字段
+- 再迁移样式
+- 再做等价性审计
+- 最后才让旧字段退出主流程
+
+一句话总结：
+
+> 下一步不是“把旧字段删掉”，而是“把旧字段一项一项替换掉，直到样式和业务都不再依赖它们”。