pbf/NavSea_CM95接入规范-v1.md

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
• 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. 目标架构

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 部署版本。首版只允许修改以下内容：

{
  "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 定义通用 PBF 字段方向；
• NavSea Tile Generation Pipeline v2 定义既有原始 PBF→交付 PBF 流程；
• NavSea 交付前审计规范 定义正式交付审计门禁。

出现冲突时，以安全对象不丢失、可回查和当前 style 实际字段契约为最高优先级。