# 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` - 推荐逻辑三层、物理两包 - 任何后续切换都必须配套审计