# NavSea PBF Schema v2

版本：v2 Draft  
用途：定义 NavSea 交付用 Vector Tile 的字段结构，兼顾渲染、碰撞、检索和旧海图兼容。

## 1 设计目标

v2 schema 要同时满足四件事：

- 保持旧海图渲染内容不明显缩水
- 支撑新的语义渲染体系
- 支撑碰撞检测和检索
- 控制字段职责，避免样式继续直接依赖大量原始编码

## 2 字段分组

v2 建议把交付字段分成 8 组：

- identity
- taxonomy
- render_semantics
- labels
- light
- hazard_area
- normalized_numeric
- source_legacy

## 3 identity

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `fid` | string | 是 | NavSea 自有对象标识，使用可逆算法生成的 16 进制字符串 |
| `fid_legacy_raw` | integer/string | 否 | 旧版原始 `fid`，建议只保留在 engineering 口径或 SQL trace |
| `fid_algo_id` | string | 否 | `fid` 生成算法标识，例如 `feistel32_aes_cyclewalk_v1` |
| `fid_key_id` | string | 否 | `fid` 生成时使用的密钥标识 |
| `render_layer` | string | 是 | 交付瓦片中的目标图层名 |
| `source_layer` | string | 否 | 原始图层名，建议保留到工程版或过渡期交付版 |

说明：

- 对“只做图片渲染”的产品可以弱化 `fid`
- 对当前 NavSea 的交付目标，不建议删除 `fid`
- 不建议继续直接暴露旧版原始 `fid`
- 建议基于 `tasks/pbf/fiddecode.md` 的可逆算法生成 NavSea 自有 `fid`
- 工程实现建议使用 `signed int32` 全域作为 legacy `fid` 的可逆映射范围

## 4 taxonomy

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `canonical_family` | string | 是 | 大类语义 |
| `canonical_object_type` | string | 是 | 细粒度对象类型 |
| `detection_key` | string | 是 | 用于检测和规则系统的稳定分类键 |
| `semantic_key` | string | 否 | 内部语义归并键，过渡期可保留 |

## 5 render_semantics

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `chart_render_type` | string | 是 | `symbol` / `line` / `fill` / `label` / `none` |
| `chart_symbol_family` | string | 否 | 符号族，例如 `navigation_light`、`hazard`、`depth_mark` |
| `chart_symbol_code` | string | 否 | 稳定符号码，例如 `lighthouse`、`rock_awash` |
| `chart_line_style` | string | 否 | 线型预设，例如 `boundary_dashed`、`contour_major` |
| `chart_fill_style` | string | 否 | 面填充预设，例如 `depth_zone_0_5`、`reef_area` |
| `chart_text_style` | string | 否 | 文字样式预设，例如 `place_name_sea`、`light_label` |
| `chart_priority` | integer | 是 | 绘制优先级，用于层级和碰撞 |
| `chart_visibility_min` | integer | 否 | 最小显示 zoom |
| `chart_visibility_max` | integer | 否 | 最大显示 zoom |
| `chart_collision_group` | string | 否 | 文本或符号碰撞组，例如 `place_label`、`light_label` |

说明：

- `chart_render_type` 和 `chart_priority` 建议作为最基础必填渲染字段
- 样式层优先读取 `chart_*` 字段，不再优先读取旧编码

## 6 labels

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `chart_label_text` | string | 否 | 主标注文本 |
| `chart_label_subtext` | string | 否 | 次级标注，例如灯略记 |
| `chart_label_anchor` | string | 否 | `top` / `bottom` / `left` / `right` / `center` |
| `chart_label_dx` | number | 否 | X 偏移 |
| `chart_label_dy` | number | 否 | Y 偏移 |

说明：

- 旧样式中的 `名称`、`名称補助`、`日本語地名`、`英文字地名` 仍可保留
- 新样式应优先使用 `chart_label_*`

## 7 light

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `light_color_code` | string | 否 | `white` / `red` / `green` / `yellow` / `mixed` |
| `light_character_code` | string | 否 | `Fl` / `Oc` / `Iso` / `F` / `V-AIS` |
| `light_sector_mode` | string | 否 | `sector` / `omni` / `none` |
| `light_arc_code` | string | 否 | 灯弧附加表达，是否交付由产品决定 |

说明：

- 灯弧本身可以不渲染
- 但灯质、灯色、略记对检索和标签仍有价值

## 8 hazard_area

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `hazard_class` | string | 否 | `rock` / `reef` / `wreck` / `obstruction` / `shoal` |
| `hazard_severity` | string | 否 | `critical` / `major` / `minor` / `context` |
| `area_usage_class` | string | 否 | `anchorage` / `route` / `fishery` / `restricted` / `water` |

## 9 normalized_numeric

建议把部分旧数值字段归一化，方便检索和规则判断。

| 字段 | 类型 | 必填 | 来源建议 |
| --- | --- | --- | --- |
| `depth_value_m` | number | 否 | 由 `水深値(m)` 归一化 |
| `clearance_height_m` | number | 否 | 由 `高さ(m)` 归一化 |
| `least_depth_m` | number | 否 | 由 `高さ/深度(m)` 中深度语义归一化 |
| `bearing_deg` | number | 否 | 由 `角度` 归一化 |

说明：

- 这些字段主要服务于检索、检测和统一显示
- 原始字段在过渡期可并存

## 10 source_legacy

以下字段是根据当前旧 `style.json` 的实际依赖，建议在 v2 过渡期继续保留的旧字段：

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

说明：

- 当前旧样式实际还使用了船舶动态字段 `cog`、`sog`、`hdg`、`length`、`rot`、`delay`
- 这些字段来自其他源，不属于 NavSea 静态海图对象 schema 的核心范围

## 11 v2 最低交付要求

每个 NavSea feature 至少应满足：

- `fid`
- `canonical_family`
- `canonical_object_type`
- `detection_key`
- `render_layer`
- `chart_render_type`
- `chart_priority`

## 12 工程版与交付版

建议分两种输出口径：

### 12.1 delivery schema

用途：前端渲染、检索、碰撞、正式交付。

保留：

- identity
- taxonomy
- render_semantics
- labels
- light
- hazard_area
- normalized_numeric
- 关键 `source_legacy`

### 12.2 engineering schema

用途：调试、抽查、问题复盘、映射核验。

在 delivery schema 基础上可额外保留：

- `fid_legacy_raw`
- `fid_algo_id`
- `fid_key_id`
- 更完整的原始 `at`
- 更多 `source_layer` / 原始属性
- 临时校验字段

## 13 v2 与当前 builder 的差距

当前 `navsea_tile_builder.py` 已经输出：

- 原始全部属性
- `canonical_object_type`
- `canonical_family`
- `semantic_key`
- `detection_key`
- `render_layer`

当前尚未系统输出的 v2 关键字段包括：

- `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_label_*`
- `light_*`
- `hazard_*`
- `area_usage_class`
- `normalized_numeric`

这部分是 builder 下一阶段的主要补齐目标。
