chore: 全量快照提交以防磁盘风险

NavSea_Semantic_Package_Overlay_Design.md

@@ -0,0 +1,347 @@
+# 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. 是否存在分包叠加的一致性审计