# NavSea 语义分包与叠加渲染设计

## 目标

本设计说明 NavSea 如何将某一坐标区域内的海图数据按语义拆分成多个 `pbf` 包，并在客户端或 Resolver 侧叠加恢复出与当前整包渲染近似等价的最终视觉结果。

这份设计服务于三个目标：

1. 在不损失海图细节的前提下重构 `pbf` 数据结构。
2. 让安全相关数据与细节相关数据可以分开交付、缓存、下载和审计。
3. 为后续离线包、Tile Resolver、按需加载和流量控制提供基础。

## 核心结论

可以将一个区域的 `pbf` 按语义拆分成多个包。

这些包在渲染时叠加后，可以恢复出与当前整包 `pbf` 基本一致的视觉结果。

但前提是：

1. 各包的语义边界稳定。
2. 样式明确知道每一层来自哪个包。
3. 叠加顺序固定。
4. 有专门的分包叠加一致性审计。

## 逻辑分层模型

当前建议的逻辑层仍采用 `NavSea_Chart_Domain_Model_v1.md` 中定义的三层模型：

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

并保留：

4. `domain_pending`

说明：

- `safety_core` 是最低安全底线。
- `safety_extended` 是重要但允许降级的数据层。
- `detail` 是信息丰富但不构成最低安全底线的层。
- `domain_pending` 是尚未完成业务语义重建的过渡层，不应直接成为正式 Chart Domain 的长期成员。

## 物理分包模型

建议 `v1` 采用“逻辑三层，物理两包”的结构：

1. `safety.pbf`
   包含：
   - `safety_core`
   - `safety_extended`

2. `detail.pbf`
   包含：
   - `detail`

在兼容阶段可允许：

3. `compat_pending.pbf`
   仅用于兼容迁移期承载少量 `domain_pending` 层。

如果不单独出第三包，也可以在迁移期临时将少量 `domain_pending` 兼容层放入 `safety` 包，但必须有审计记录。

## 为什么不建议一开始拆成很多小包

虽然理论上可以拆成：

- `hazard.pbf`
- `contour.pbf`
- `marks.pbf`
- `labels.pbf`
- `seabed.pbf`

但 `v1` 不建议这样做。

原因：

1. 客户端 source 数量会快速膨胀。
2. 样式复杂度显著增加。
3. Tile Resolver 逻辑会变重。
4. 网络请求会被切碎。
5. 审计维度会显著复杂化。

因此 `v1` 先采用两包结构最稳。

## 叠加渲染原则

语义分包后，最终渲染必须遵守以下原则。

### 原则 1：安全层不能被细节层替代

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

即使 `detail` 中恰好存在一个对象在视觉上看起来能表达某种危险，也不能把它作为安全底线的替代依据。

### 原则 2：Resolver 按包返回，不按 layer/feature 拼装

`v1` Resolver 必须按物理包分发，不在客户端做 feature 级或 layer 级重组。

也就是说：

- 返回 `safety` 包
- 返回 `detail` 包

而不是：

- 从多个包中抽若干 layer
- 再动态重新打成新 tile

### 原则 3：样式叠加顺序固定

客户端的样式层顺序必须固定，不能由请求时动态推断。

最基础的顺序建议是：

1. 背景与底图
2. `safety` 面层
3. `detail` 面层
4. `safety` 线层
5. `detail` 线层
6. `safety` 符号层
7. `detail` 符号层
8. `safety` 文字层
9. `detail` 文字层

### 原则 4：分包后必须还能恢复旧视觉

当前阶段的首要目标不是做新视觉，而是：

- 新结构
- 旧视觉

所以“分包叠加结果”和“原始整包结果”必须可做等价审计。

## 推荐消费模式

### 模式 A：单 Style，多 Source 叠加

这是当前最推荐的模式。

样式中声明：

- `domain_safety`
- `domain_detail`

然后不同 layer 从不同 source 取数据。

优点：

1. 最符合 MapLibre / Mapbox Style 常规工作方式。
2. 不需要客户端自行拼瓦片。
3. 便于渐进迁移旧样式。
4. 最适合当前阶段的视觉等价验证。

### 模式 B：Resolver 选择性返回包

Resolver 按场景返回：

- 只返回 `safety`
- 返回 `safety + detail`

客户端仍按固定 source/固定 style 消费。

优点：

1. 更适合离线/带宽优化。
2. 可以基于业务场景做包级裁剪。

要求：

- 样式必须在缺少 `detail` 时仍可安全退化。
- 不允许缺少 `safety_core` 时依赖 `detail` 伪装补齐。

## 推荐目录结构

### 局部测试目录

```text
/home/wwwroot/pbf-domain-karatsu-10nm/
  ├── safety/{z}/{x}/{y}.pbf
  ├── detail/{z}/{x}/{y}.pbf
  ├── chart_domain_build_audit.json
  └── chart_domain_build_audit.md
```

### 全国目录建议

```text
/home/wwwroot/pbf-domain-full/
  ├── safety/{z}/{x}/{y}.pbf
  ├── detail/{z}/{x}/{y}.pbf
  ├── build_audit.json
  ├── build_audit.md
  ├── overlay_audit.json
  └── overlay_audit.md
```

## 样式组织建议

### 兼容阶段

优先使用：

- 旧样式规则
- 新 Domain 包 source

也就是当前已经验证过的路径：

- 保留旧 `paint`
- 保留旧 `layout`
- 保留旧 `filter`
- 仅替换 `source` 与 `source-layer`

### 清理阶段

在视觉对齐后，再逐步：

1. 去掉旧日文 `layer id`
2. 去掉旧字段依赖
3. 收敛到纯标准语义 layer
4. 最终形成新的可读样式层命名

## 审计设计

分包以后，必须增加一套新的“叠加一致性审计”。

建议至少做三类审计。

### 1. 构建审计

检查：

- 每个 feature 被分到了哪个包
- 是否有 feature 被错误丢弃
- `domain_pending` 数量和明细
- 包内实际 layer 集合

当前已有样例：

- `chart_domain_build_audit.json`
- `chart_domain_build_audit.md`

### 2. 渲染等价审计

比较：

- 原始版：原始样式 + 原始 `pbf`
- 分包版：兼容样式 + `safety/detail` 叠加结果

审计单位：

- `fid` 优先
- 无 `fid` 用 `geometry + 稳定旧属性`
- 保留 tile instance 粒度

注意：

- 分包版不能按新标准 layer 名直接对比
- 必须按 `source_layer_jp` 或 trace 回溯后的旧身份对齐

当前已经为此新建了 Domain 专用脚本方向：

- `src/Domain/navsea_domain_render_audit.py`

### 3. 包级可用性审计

验证以下两种消费结果：

1. `safety` 单独加载
2. `safety + detail` 叠加加载

目标：

- `safety` 单独时，满足最低安全表达
- `safety + detail` 时，尽可能恢复原始整包视觉

## 推荐审计结论口径

建议把审计结论分成三档：

1. `safe_minimum_pass`
   `safety` 单独可用于最低安全判断

2. `overlay_equivalent_pass`
   `safety + detail` 叠加结果与原始版视觉等价

3. `pending_semantic_gap`
   存在尚未完成业务语义重建的层，仅靠兼容模式暂时保留

## 当前阶段的正确顺序

推荐按以下顺序推进，不要反过来：

1. 重构 `pbf` 内部结构
2. 用新结构恢复旧视觉
3. 用 Domain 专用审计确认“叠加等价”
4. 再做分包消费策略和 Resolver 策略
5. 最后才做新的 UI/新视觉/新风格

## 当前阶段的可接受实现

就当前工程而言，以下做法是合理的：

1. 区域级生成
   例如先做唐津 10 海里

2. 输出两包
   - `safety`
   - `detail`

3. 提供一个兼容样式
   目标是“看起来和旧版一样”

4. 提供 Domain 专用审计
   不修改原有工程版审计体系

这意味着：

- 旧体系继续可用
- Domain 体系独立演进
- 两条线彼此不污染

## 后续实施建议

建议下一阶段按以下顺序执行：

1. 固化唐津 10 海里 Domain 审计结论
2. 将唐津流程推广到九州区域
3. 补齐 `domain_pending` 的正式业务语义
4. 在全国范围生成 `safety/detail` 双包
5. 增加 `safety-only` 与 `safety+detail` 双场景验收

## 总结

某个坐标区域的 `pbf` 完全可以按语义拆成多个包。

这些包叠加后，可以恢复到与当前整包渲染近似等价的状态。

这不是额外能力，而是 NavSea Domain 设计成立的核心验证点之一。

真正需要控制的，不是“能不能拆”，而是：

1. 语义边界是否稳定
2. 样式是否固定知道从哪个包取哪种对象
3. `detail` 是否错误替代 `safety`
4. 是否存在分包叠加的一致性审计