# 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. 最终判断

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

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

一句话总结：

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