Checkpoint CM95 PBF production code and docs for Linux migration

2026-09-11 18:10:56 +08:00
parent 0ca1f63320
commit b52b3447cf
116 changed files with 55495 additions and 2 deletions
--- a/NavSea_CM95接入规范-v1.md
+++ b/NavSea_CM95接入规范-v1.md
@@ -0,0 +1,229 @@
+# NavSea CM95 接入规范
+
+版本：`v1`  
+状态：首版实施规范  
+用途：定义将具备合法使用授权的 CM95 海图数据转换为 PBF，并直接接入现有 NavSea Full semantic style 的数据契约、实施顺序和验收门禁。
+
+## 1. 结论
+
+CM95 必须向 NavSea 的既有 PBF 契约靠齐；不为 CM95 重写一套海图 style，也不允许把 CM95 原始对象类别直接暴露给前端 style。
+
+当前接入基线为：
+
+- style：[`src/pbf/style.navsea-delivery-full-semantic-unified-20260808.json`](/root/sourceserver/pbf/src/pbf/style.navsea-delivery-full-semantic-unified-20260808.json)
+- sprite：`http://192.168.200.184/newpec/sprite-semantic-unified-20260808/sprite`
+- glyphs：`http://192.168.200.184/newpec/fonts/{fontstack}/{range}.pbf`
+
+CM95 转换产物必须满足该 style 的 `source-layer`、字段和值域要求。满足后，新 style 只需复制基线文件并修改 `sources.navsea_delivery.tiles` 的瓦片地址。
+
+## 2. 边界与前提
+
+- 仅处理已获授权解码、转换、缓存和部署的 CM95 数据。
+- CM95 解码器不属于本仓库交付物；本规范的输入是已经合法导出的矢量要素及其属性。
+- 转换过程不得篡改海图几何、深度、净空、航标与危险物的原始业务含义。
+- 所有要素必须有稳定的上游对象身份；若 CM95 未提供全局稳定 ID，必须由“数据集版本 + 原始 cell/record ID + 几何类型”生成可复现的 `source_id`。
+- 第一版只追求“复用当前 style 并可审计”，不以压缩字段或全国一次性全量生产为目标。
+
+## 3. 目标架构
+
+```text
+CM95 合法导出数据
+  -> CM95 解析与原始对象归档
+  -> CM95→NavSea 语义/渲染映射
+  -> NavSea 兼容要素集
+  -> Web Mercator MVT/PBF
+  -> 现有 NavSea Full semantic style
+```
+
+其中“CM95→NavSea 语义/渲染映射”是唯一允许理解 CM95 原始类别与属性差异的层。MVT 和 style 只消费 NavSea 的标准图层与字段。
+
+## 4. 固定图层契约
+
+第一版 PBF 的图层名称必须与当前 style 完全一致。不得随意以 CM95 对象名作为图层名。
+
+| 业务类别 | 目标 `source-layer` |
+| --- | --- |
+| 海域底色、水深区 | `baseline_area`、`depth_zone_739`、`depth_zone_741` |
+| 海岸、陆地与岸线 | `land_area`、`baseline_line`、`baseline_outline` |
+| 等深线与测深文字 | `depth_contour`、`bathymetry_line`、`seabed_text_point` |
+| 航标、灯塔、浮标、灯弧 | `navigation_marks` |
+| 航行危险物 | `navigation_hazard_point`、`navigation_hazard_area`、`navigation_hazard_outline` |
+| 锚泊及锚泊注意 | `anchorage_point`、`anchorage_area`、`anchorage_outline`、`anchor_caution_hazard_point`、`anchor_caution_hazard_area`、`anchor_caution_hazard_outline` |
+| 渔具与渔业禁限 | `fixed_fishing_gear_area` |
+| 设施、桥梁、净空 | `facility_boundary_point`、`facility_boundary_area`、`facility_boundary_outline`、`bridge_structure`、`clearance_limit_point`、`clearance_limit_line` |
+| 地名和陆上设施 | `place_label_sea`、`place_label_land`、`onshore_structure_point`、`onshore_structure_line`、`onshore_structure_area` |
+| 其他已由 style 消费的图层 | `pilot_station_point`、`seabed_line`、`submerged_reef_area`、`hazard_boundary_outline`、`hole_area`、`clip_outline_754` |
+
+未能映射到上述图层的 CM95 对象不得静默丢弃：应写入工程版的 `cm95_unmapped` 隔离层并生成映射缺口报告；该隔离层不进入正式 style。
+
+## 5. 字段契约
+
+### 5.1 每个已交付要素必须有的字段
+
+| 字段 | 要求 |
+| --- | --- |
+| `fid` | NavSea 稳定、可复现的对象标识；不能使用每次构建都会变化的临时序号。 |
+| `canonical_family` | NavSea 大类语义。 |
+| `canonical_object_type` | NavSea 细粒度对象类型。 |
+| `render_layer` | 与实际 `source-layer` 相同的目标渲染层。 |
+| `chart_render_type` | `fill`、`line`、`symbol`、`label` 或 `none`。 |
+| `chart_priority` | 绘制/碰撞优先级。 |
+| `source_id` | 可回查 CM95 上游对象的稳定标识；工程版必留，交付版建议保留。 |
+| `source_dataset_id` | CM95 数据集、cell 或版本标识；工程版必留。 |
+
+### 5.2 当前 style 的直接渲染字段
+
+按对象类型填写以下字段，未适用字段可缺省，但不得以伪造值替代：
+
+| 对象类别 | 必要或高优先级字段 |
+| --- | --- |
+| 面与水深区 | `chart_fill_style`、`chart_fill_pattern` |
+| 线 | `chart_line_color`、`chart_line_width`、`chart_line_pattern` |
+| 图标 | `chart_icon_image`、`chart_symbol_code`、`class_code`、`display_code`、`shape_class_code` |
+| 文字 | `chart_label_text`、`chart_label_subtext`、`chart_text_style`、`chart_text_color`、`chart_label_position_code` |
+| 灯标 | `light_color_code`、`chart_label_subtext`；有弧段时还需 `arc_id` 与可追溯的原始弧段编码。 |
+
+`chart_icon_image`、`chart_fill_pattern` 和 `arc_id` 的取值必须是当前 semantic sprite 中真实存在的键。不得写入旧 `symbol-daytime-*`、`fill-daytime-*` 或未经 sprite 审计的新键。
+
+### 5.3 CM95 原始属性保留
+
+CM95 的原始属性不得直接成为 style 的长期依赖，但工程版必须保留以下可追溯信息：
+
+- CM95 对象类别/OBJL；
+- 原始对象 ID、cell/数据集 ID、更新时间或版本；
+- 原始属性全集或其不可逆裁剪前的外部 trace；
+- 原始几何类型；
+- 映射规则 ID 与映射版本。
+
+交付版可裁掉详细 trace，但必须能凭 `fid` 在工程索引中回查到上述信息。
+
+## 6. CM95 映射实施方式
+
+建立一个版本化映射表，例如 `tasks/pbf/mappings/cm95_to_navsea_v1.yaml`。每条规则至少包含：
+
+- `cm95_object_class`：CM95 原始对象类别；
+- `geometry_type`：点、线、面；
+- `condition`：属性条件；
+- `target_source_layer`：本规范第 4 节中的目标层；
+- `canonical_family`、`canonical_object_type`；
+- `style_fields`：需物化的 `chart_*`、灯标、文字或数值字段；
+- `rule_id`、`mapping_version`；
+- `safety_class`：`hard_gate`、`important` 或 `normal`。
+
+映射优先级如下：
+
+1. 航标、灯火、浮标、灯弧；
+2. 暗礁、沉船、障碍物、浅水、干出与露出对象；
+3. 水深区、等深线、测深与净空；
+4. 海陆边界、陆地、航道、锚地、限制区、渔具；
+5. 设施、地名和一般说明。
+
+同一 CM95 类别因属性不同而表现不同，必须拆成多条显式规则；不能只按对象类别做一对一映射。
+
+## 7. PBF 生成规则
+
+- 统一投影为 EPSG:3857，使用 XYZ `z/x/y` 切片。
+- MVT extent 固定为 `4096`，同一目标图层内保持一致。
+- 首版目标 zoom 为 `0–12`；小范围试产可先产出覆盖 AOI 的 `z8–12`。
+- 面、线裁切须带足够 buffer，避免瓦片边缘断裂；点不得因边界判断被重复删除。
+- 保持原始几何类型；不得将面危险物降级为点，或把线界线误转为面。
+- 同一 `fid` 在不同 zoom/tile 的实例可重复出现，但其身份和核心语义必须一致。
+- 构建时输出工程版 PBF、交付版 PBF、映射缺口 JSON/Markdown 和 `fid -> source_id` 审计索引。
+
+## 8. Style 接入方式
+
+以当前基线 style 复制一个 CM95 部署版本。首版只允许修改以下内容：
+
+```json
+{
+  "name": "NavSea CM95 <区域> <版本>",
+  "sources": {
+    "navsea_delivery": {
+      "tiles": ["https://<host>/pbf-cm95-<区域>-<版本>/{z}/{x}/{y}.pbf"]
+    }
+  }
+}
+```
+
+保持不变：
+
+- 全部 layer ID、顺序、filter 和 paint/layout；
+- semantic sprite URL；
+- glyph URL；
+- 外部 tide 与底图 source。
+
+若某一类 CM95 数据无法命中现有 style，优先补充映射字段或 sprite 映射；只有确认现有 style 无法表达且完成专项审计后，才允许新增 style layer。
+
+## 9. 分阶段交付
+
+### 阶段 A：单 AOI 可视化样本
+
+- 选择一个含陆地、水深、航标和危险物的港口或近岸 AOI。
+- 导出 CM95 原始对象清单及 `source_id`。
+- 完成第 6 节映射表的最小覆盖。
+- 生成 z8–12 PBF，使用只改 tile URL 的 style 打开。
+
+通过条件：底图、水深、等深线、陆地、主要航标和危险物均可显示，且无大面积空白或错误覆盖。
+
+### 阶段 B：安全对象闭环
+
+- 补齐所有 `hard_gate` 对象的分类、图层和符号字段。
+- 灯火必须同时验证灯色、略记和灯弧（如原始数据提供）。
+- 危险物必须验证水上/水下/露出/干出语义不会画反。
+
+通过条件：对象保全审计的安全对象缺失数为 `0`，关键图标/文字/symbol sprite 缺失数为 `0`。
+
+### 阶段 C：区域扩展与发布
+
+- 扩展至完整目标海域及 z0–12。
+- 收敛未映射对象；剩余对象须有明确的隔离理由和风险结论。
+- 生成正式交付版及可回查工程索引。
+
+## 10. 必须执行的审计顺序
+
+按项目正式口径执行，不能以视觉相似替代对象保全：
+
+1. **对象保全审计**：以 `source_id + source_dataset_id + geometry_type` 回对 CM95 原始导出与 PBF；检查缺失、错误重分层、错误合并、身份丢失。
+2. **渲染审计**：扫描 PBF 字段、style 命中和 sprite 资源；检查关键对象是否获得有效 fill、line、icon、text。
+3. **AOI 视觉审计**：在固定中心点和 zoom 检查叠压、边缘裁切、标签、海陆关系与安全感知。
+
+CM95 没有“旧 NavSea PBF”可作为对象基准时，CM95 原始导出数据就是第一层审计的基准；不可跳过这一层。
+
+## 11. 硬门禁
+
+以下任一项不通过，CM95 PBF 不得切换到正式 URL：
+
+- `hard_gate` 对象存在缺失、身份不可回查或错误图层；
+- `chart_icon_image`、`chart_fill_pattern`、`arc_id` 引用不存在的 sprite 键；
+- 深度、净空、危险物或灯火发生单位错误、正负号错误或水上/水下语义反转；
+- PBF 投影、extent、坐标轴或 tile y 方向错误；
+- style 实际加载的 tile URL 不是候选 CM95 PBF；
+- 映射缺口被静默丢弃；
+- 未完成针对目标 AOI 的人工视觉复核。
+
+## 12. 首次实施的输入与产出
+
+开始实施前需要提供：
+
+- 一个合法导出的 CM95 AOI 样本；
+- 导出格式和字段/对象类别字典；
+- 数据集版本、坐标参考和深度/高度单位说明；
+- 目标海域、目标 zoom、部署 PBF URL；
+- 至少一个包含航标、危险物、水深区和陆地的验收 AOI。
+
+首次实施完成时必须交付：
+
+- `cm95_to_navsea_v1.yaml` 映射表；
+- CM95→NavSea 转换脚本；
+- 工程版与交付版 PBF；
+- 映射缺口报告、对象保全报告、sprite 闭合报告和 AOI 审计报告；
+- 仅替换瓦片 URL 的 CM95 style 文件。
+
+## 13. 与既有文档的关系
+
+- 本规范定义 CM95 作为新上游数据源时如何接入；
+- [NavSea PBF Schema v2](tasks/pbf/NavSea_PBF_schema_v2.md) 定义通用 PBF 字段方向；
+- [NavSea Tile Generation Pipeline v2](tasks/pbf/NavSea_tile_generation_pipeline_v2.md) 定义既有原始 PBF→交付 PBF 流程；
+- [NavSea 交付前审计规范](NavSea_Delivery_Preflight_Audit_Spec.md) 定义正式交付审计门禁。
+
+出现冲突时，以安全对象不丢失、可回查和当前 style 实际字段契约为最高优先级。