pbf/NavSea_Chart_Domain_Model_v1.md

# NavSea Chart Domain Model v1

## 1. 目的

本文件定义 NavSea 在“去掉交付版 `pbf` 对旧日文 layer 体系依赖”之后，面向渲染、离线包、Tile Resolver 和业务消费的 **语义分层模型**。

这不是旧 `source-layer` 的简单改名，而是一次 **按语义重建 layer domain** 的设计。

目标：

- 让交付版 `pbf` 的 layer 结构按航海语义组织
- 为离线最小包 / 增强包 / 细节包提供稳定结构
- 为 Tile Resolver 提供明确的优先级
- 为后续“去旧字段依赖”“去日文化技术依赖”提供域模型基础
- 为审计提供明确的验收口径

## 2. 核心结论

NavSea 不应只分成 `Safety / Detail` 两层，而应分成 **三层语义域**：

1. `safety_core`
2. `safety_extended`
3. `detail`

同时再保留一个过渡状态：

4. `domain_pending`

其中：

- `safety_core`
  - 生存核心层
  - 离线最小包必须包含
  - Tile Resolver 永远优先返回
- `safety_extended`
  - 增强安全层
  - 对航海有价值，但缺失不会立刻致命
  - 建议缓存，可离线降级
- `detail`
  - 细节层
  - 信息丰富，但不是安全底线
  - 可延迟加载，甚至可完全缺失
- `domain_pending`
  - 语义尚未完成重建的过渡层
  - 不能直接进入最终交付域模型

## 3. 设计原则

### 3.1 这是“语义分层”，不是“旧 layer 改英文名”

域模型的判断依据应是：

- 航海风险
- 是否属于安全底线
- 是否必须离线存在
- 是否属于细节补充

不应只依据：

- 旧 `source-layer`
- 旧编码号
- 当前样式中是否好画

### 3.2 物体优先，图层其次

最终分层应该优先考虑对象语义，而不是历史制图层名。

例如：

- `navigation_marks`
  - 虽然来自点层，但本质是安全核心对象
- `place_label_sea`
  - 虽然在视觉上重要，但不属于安全底线

### 3.3 逻辑层三层，物理分发两包

推荐结构：

- 逻辑域模型：三层
  - `safety_core`
  - `safety_extended`
  - `detail`
- 物理分发模型：两包
  - `safety`
  - `detail`

其中：

- `safety = safety_core + safety_extended`
- `detail = detail`

如果需要极简离线模式，可额外定义：

- `base_pack = safety_core`

### 3.4 安全层不得被细节层替代

这是一个硬约束：

- 任意 `detail` feature 不得被视为 `safety_core` 的替代来源

即使某个 `detail` 对象在视觉上“看起来像”危险物、边界或航标，也不能因为它恰好被画出来，就把它当作安全底线的一部分。

原因：

- `detail` 本来就是允许缺失的
- 离线模式下，`detail` 可能根本不下载
- 如果系统把 `detail` 当作 `safety_core` 的替代，会导致错误安全感

因此：

- `safety_core` 必须由明确归入 `safety_core` 的对象独立构成
- 不允许通过 `detail` 的“视觉相似性”补齐安全层

### 3.5 Resolver 以物理包为最小分发单位

`v1` 阶段必须明确限制客户端复杂度：

- Tile Resolver 的最小分发单位是物理包
- 不在客户端做 feature 级或 layer 级重组

也就是说，Resolver 优先返回：

- `safety` 包
- `detail` 包

而不是：

- 从某个 tile 中抽几个 `safety_core` layer
- 再拼几个 `detail` layer
- 然后在客户端重新生成一块新 `pbf`

原因：

- 客户端复杂度会显著增加
- 缓存模型会被打碎
- 调试、审计、回放都会变复杂
- 第一阶段很容易陷入过度工程

因此 `v1` 原则是：

- 逻辑上按 domain 建模
- 物理上按包分发
- 客户端只做“选包”，不做“重组包”

### 3.6 `land_area` 是陆海主判定层

为了支持快速、稳定地将陆地与海洋分开渲染，`v1` 明确规定：

- `land_area` 是陆海二分的唯一主来源
- `land_area` 内部视为陆地
- `land_area` 外部默认视为海域/水域背景

同时明确：

- `baseline_area`
- `baseline_line`
- `baseline_outline`
- `onshore_structure_*`
- 港岸结构、防波堤、码头边线

这些对象可以辅助表达岸线和港湾结构，但**不作为陆海主判定层**。

这条规则的目的，是让显示层和后续 Resolver / 切包逻辑都能用一条简单规则完成陆海分离，而不需要在多个 layer 之间做启发式拼接判断。

## 4. 域定义

### 4.1 `safety_core`

定义：

- 没有它就不该航行
- 离线底线包必须存在
- 缺失会直接影响最低安全判断

典型特征：

- 航行危险
- 航标
- 水深核心
- 危险地形
- 地形基础参考

### 4.2 `safety_extended`

定义：

- 对航行明显重要
- 但缺失不会立刻让系统失去最低安全能力

典型特征：

- 锚地
- 净空/限制
- 重要结构物
- 基本边界参考

### 4.3 `detail`

定义：

- 丰富表达、增强理解、提升体验
- 但不影响最低安全底线

典型特征：

- 地名
- 底质
- 次级边界
- 支撑线
- 展示性文字

### 4.4 `domain_pending`

定义：

- 当前尚未完成语义重建
- 仍然带旧编码痕迹
- 只能作为过渡层，不得直接当最终域模型交付

典型特征：

- 编码型 layer
- 仅具“稳定占位名”，不具业务语义

## 5. 第一轮域归类

以下归类是当前讨论后的 `v1` 基线。

### 5.1 `safety_core`

- `navigation_hazard_area`
- `navigation_hazard_outline`
- `navigation_hazard_point`
- `depth_contour`
- `depth_contour_overview`
- `navigation_marks`
- `fixed_fishing_gear_area`
- `land_area`
- `submerged_reef_area`

### 5.2 `safety_extended`

- `anchor_caution_hazard_area`
- `anchor_caution_hazard_outline`
- `anchor_caution_hazard_point`
- `anchorage_area`
- `anchorage_outline`
- `anchorage_point`
- `clearance_limit_line`
- `clearance_limit_point`
- `bridge_structure`
- `onshore_structure_area`
- `onshore_structure_line`
- `onshore_structure_point`
- `baseline_area`
- `baseline_line`
- `baseline_outline`
- `route_area`
- `route_outline`
- `route_axis_line`
- `route_boundary_point`
- `leading_line_outline`
- `pilot_station_point`

### 5.3 `detail`

- `place_label_sea`
- `place_label_land`
- `seabed_text_point`
- `facility_boundary_area`
- `facility_boundary_outline`
- `facility_boundary_point`
- `hole_area`
- `bathymetry_line`
- `seabed_line`

### 5.4 `domain_pending`

这几类当前不得直接进入最终 Chart Domain：

- `depth_zone_739`
- `depth_zone_741`
- `clip_outline_754`

原因：

- 仍然依赖旧编码
- 语义不够明确
- Resolver 和离线模型无法稳定消费

## 6. 对当前层命名的解释

本模型中的 layer 名，指的是 **建议标准语义层名**，不是当前交付版实际使用的旧日文 `source-layer`。

也就是说，像：

- `P錨泊地等`
- `p航路標識群`
- `L等深線`

应先标准化为：

- `anchorage_area`
- `navigation_marks`
- `depth_contour`

再进入 Chart Domain 分类。

## 7. 面向 Tile Resolver 的结构建议

未来 Tile Resolver 不应只拿“某个标准 layer 名”做决策，还应同时读取：

- `chart_domain`
- `resolver_priority`
- `offline_pack`

建议输出字段：

- `chart_domain`
  - `safety_core | safety_extended | detail | domain_pending`
- `resolver_priority`
  - 整数，数值越小优先级越高
- `offline_pack`
  - `base | safety | detail | pending`
- `domain_status`
  - `active | pending | deprecated`

建议默认优先级：

- `safety_core`: `10`
- `safety_extended`: `20`
- `detail`: `30`
- `domain_pending`: `99`

## 8. 面向分包的结构建议

推荐的物理输出结构：

```text
tiles/
  ├── safety/{z}/{x}/{y}.pbf
  └── detail/{z}/{x}/{y}.pbf
```

其中：

- `safety`
  - 包含 `safety_core + safety_extended`
- `detail`
  - 包含 `detail`

如果后续确实需要更细粒度离线控制，可扩展为：

```text
tiles/
  ├── safety-core/{z}/{x}/{y}.pbf
  ├── safety-extended/{z}/{x}/{y}.pbf
  └── detail/{z}/{x}/{y}.pbf
```

但当前 `v1` 建议先不要切太细，以免：

- 分发复杂
- 前端消费复杂
- 缓存策略过碎

## 9. 审计设计

这部分是本文件最重要的配套要求：**域模型不是写出来就算完成，必须可以审计。**

### 9.1 审计目标

要能回答：

1. 每个标准 layer 是否被正确归入某个 Chart Domain
2. 是否有对象被错分到不合适的域
3. 是否有 `domain_pending` 层被错误放入正式交付
4. 按当前 style 渲染时，域变化是否破坏原始渲染
5. 离线包拆分后，是否仍满足“安全底线”

### 9.2 审计分层

建议分 4 层审计。

#### A. 规则审计

检查内容：

- 每个标准 layer 是否有明确域归属
- 每个域归属是否有规则来源
- 是否存在重复归类或冲突归类

建议表结构：

- `chart_domain_rules`
- `chart_domain_rule_trace`

建议最小字段：

- `domain_rule_id`
- `bundle_id`
- `layer_std`
- `chart_domain`
- `resolver_priority`
- `offline_pack`
- `rule_reason`

#### B. 数据审计

检查内容：

- 当前交付版/工程版 `pbf` 中，每个 feature 属于哪个标准 layer
- 是否存在 feature 无法映射到任何域
- 是否存在 `domain_pending` layer 进入了正式输出

建议输出：

- `feature_count by chart_domain`
- `feature_count by layer_std`
- `feature_count by domain_pending`

关键断言：

- 每个正式输出 feature 必须有 `chart_domain`
- `domain_pending` 不得进入最终交付版

#### C. Resolver 审计

检查内容：

- `safety_core` 是否总是优先被 Resolver 选择
- `detail` 是否不会覆盖 `safety_core`
- 离线模式下 Base Pack 是否真的包含全部 `safety_core`
- Resolver 是否始终按物理包返回，而不是按 layer/feature 临时拼装

关键断言：

- `safety_core` 丢失即判定不通过
- `detail` 缺失不影响 `base_pack` 合格
- 不允许 `detail` 被当作 `safety_core` 的替代来源
- 不允许客户端执行 feature 级或 layer 级重组后再返回 tile

#### D. 渲染审计

检查内容：

- 在 layer domain 切换后，原始样式与新样式是否仍然等价
- 是否有 feature 因域拆分而不再被渲染
- 是否有对象在新样式中出现“语义画反”
  - 水下对象被画成陆地/露出
  - 水上对象被画成水下/危险物
  - render-support 层被错误强化成业务语义对象

##### D-1. Style 语义审计

这是渲染审计中的强制子项，目的不是只看“有没有画出来”，而是看：

- 新版 style 是否忠于旧版 style 的表现语义
- 是否把旧版的弱语义/辅助语义误画成强语义
- 是否把航行关键语义画反

重点检查：

- 陆海主判定是否与旧版一致
- 水上 / 水下 / 露出 / 干出语义是否与旧版一致
- 危险物、潜堤、暗礁、浅水区等是否被误画成普通背景
- render-support 层是否仍保持旧版的支撑性表现
  - 例如 `P穴 -> hole_area` 必须忠于旧版透明/孔洞式表现，不得画成陆地区块
- 文字与符号是否仍表达旧版相同含义
  - 有对象、无数字
  - 有线、无深度标注
  - 有主符号、无关键辅助注记

审计口径：

- 旧版 style 是表现基准
- 新版 style 是对旧版 style 的语义转译，不是重新设计
- 只要旧版表现会影响航行判断，该表现就必须被视为“语义表现”，纳入审计
- 交付前执行规范详见 [`NavSea_Delivery_Preflight_Audit_Spec.md`](/root/sourceserver/pbf/NavSea_Delivery_Preflight_Audit_Spec.md)

关键断言：

- 不允许把水域对象画成陆地感对象
- 不允许把陆地/露出对象画成水下对象
- 不允许把 render-support 层画成会误导航行判断的实体语义对象
- 不允许因样式转译而丢失关键深度数字、净空数字、灯标说明、危险物标记

审计口径：

- 原始 `pbf` + 原始 style
- 工程版/交付版 `pbf` + 对应 style
- 按 feature instance 级别比较 icon/text/line/fill

关键断言：

- 不允许因为域重组导致“原来有渲染、现在完全没渲染”
- 不允许 `safety_core` 对象被错误降到 `detail`

## 10. 审计通过条件

本模型建议的最低通过条件如下：

### 10.1 命名通过

- 所有正式输出 layer 必须使用标准层名
- 不再直接暴露旧日文 layer 名

### 10.2 域归类通过

- 所有正式输出 layer 必须属于：
  - `safety_core`
  - `safety_extended`
  - `detail`
- 不允许正式交付 layer 仍停留在 `domain_pending`

### 10.3 渲染通过

- 原始版 vs 新版渲染审计通过
- 不存在 feature 完全失去渲染观察
- Style 语义审计通过
- 不存在会影响航行判断的“语义画反”
- render-support 层未被误画为强业务语义对象

### 10.4 离线通过

- `base_pack` 能独立支撑 `safety_core`
- `safety_pack` 能完整支撑安全域
- 缺失 `detail` 时，不得靠 `detail` 外观相似对象替代 `safety_core`
- Resolver 返回应保持物理包边界，不做客户端临时重组

## 11. 当前已知风险

### 11.1 编码层风险

当前最大的风险仍然是：

- `depth_zone_739`
- `depth_zone_741`
- `clip_outline_754`

如果这些层不先做语义拆解，后续：

- Resolver 无法稳定使用
- 离线打包会失真
- Chart Domain 会夹杂“编码占位层”

### 11.2 容器层风险

这几层当前仍偏“容器命名”：

- `baseline_area`
- `facility_boundary_area`
- `bathymetry_line`

它们虽然比旧日文层名好，但还不是最终最清晰的业务层名。

## 12. 建议的推进顺序

### Phase 1

- 完成 layer 标准命名
- 不改现有运行系统
- 只形成 Chart Domain 设计与审计要求

### Phase 2

- 建立 `chart_domain_rules`
- 为每个标准 layer 补：
  - `chart_domain`
  - `resolver_priority`
  - `offline_pack`

### Phase 3

- 输出新的语义域 layer 结构
- 仍保留可逆追溯
- 做渲染审计和 Resolver 审计

### Phase 4

- 正式切换交付版
- 旧日文 layer 退出交付体系

## 13. 当前结论

NavSea 下一步不是继续停留在“旧 layer 改英文名”，而是要进入：

- **按语义重建 layer domain**

`v1` 的基础结论是：

- 三层域模型是必要的
- 需要额外保留 `domain_pending`
- 推荐逻辑三层、物理两包
- 任何后续切换都必须配套审计