# NavSea 语义重建流水线说明

## 1. 流水线概览

NavSea 当前的数据库流水线可以分成两段：

1. 上游导入段  
   将原始 PBF 拆入数据库，形成 `features` 与 `properties` 两张核心表。

2. 语义重建与校验段  
   在不修改现有渲染逻辑、不修改 `style.json`、不修改原始 PBF 结构的前提下，建立语义叠加层与校验层。

当前真实的流水线可概括为：

```text
原始 PBF
→ PBF 导入（外部前置步骤，结果进入 features / properties）
→ 属性展开（at_attributes）
→ 语义投影（feature_semantic）
→ 对象类型候选生成（object_type_candidates）
→ 审计与统计（object_catalog / object_type_stats / style_layers / tile_density）
→ 规范对象规则（canonical_object_rules / canonical_layer_rules）
→ 语义叠加层构建（pbf_relayer_candidates）
→ 检测目录与渲染兼容层（pbf_detection_catalog / pbf_render_compatibility）
→ 语义校验（classification / geometry / render / detection / spatial）
→ 最终 NavSea 语义数据集（数据库中的已校验语义叠加结果）
```

需要明确一点：当前仓库中的脚本并不直接生成“新的 NavSea 矢量瓦片文件”。当前系统产出的是一套可重建、可审计、可校验的数据库语义数据集；下游若要生成新的 NavSea 矢量瓦片，应以这些表为输入继续执行后续生产步骤。

## 2. 分步流水线

### Step 00 - 原始 PBF 导入

目的  
将原始 PBF 解析并导入数据库。

输入  
原始 PBF 数据

输出  
`features`  
`properties`

说明  
这一步是当前语义流水线的前置条件。当前仓库中没有提供这一步的导入脚本，但后续所有步骤都假定这两张表已存在。

### Step 01 - 提取 `at` 属性

目的  
把 `properties` 表中 `k='at'` 的 JSON 属性展开成结构化键值表。

输入表  
`properties`

输出表  
`at_attributes`

脚本  
`navsea_audit.py`

### Step 02 - 构建语义投影表

目的  
把原始要素与已展开的属性汇总到单要素视角，形成后续语义分析使用的基础表。

输入表  
`features`  
`at_attributes`

输出表  
`feature_semantic`

字段要点  
`feature_id`、`z/x/y`、`vt_layer`、`geom_type`、`class_name`、`shape_name`、`layer_name`

脚本  
`navsea_audit.py`

### Step 03 - 构建对象目录

目的  
从 `feature_semantic` 聚合出对象目录，用于观察每类对象在不同来源层和几何类型上的分布。

输入表  
`feature_semantic`

输出表  
`object_catalog`

脚本  
`navsea_audit.py`

### Step 04 - 生成对象类型候选

目的  
为每个要素生成对象类型候选，优先级为：

```text
class_name > shape_name > vt_layer
```

输入表  
`feature_semantic`

输出表  
`object_type_candidates`

脚本  
`navsea_audit.py`

### Step 05 - 构建对象类型统计

目的  
统计每个对象类型与几何类型的分布，为规则生成和几何白名单提供依据。

输入表  
`object_type_candidates`

输出表  
`object_type_stats`

脚本  
`navsea_audit.py`

### Step 06 - 构建样式层分析

目的  
从 `style.json` 中抽取现有渲染层信息，并与对象候选做交叉比对，确认渲染轨仍可复用。

输入  
`src/pbf/style.json`  
`object_type_candidates`

输出表  
`style_layers`  
`style_mapping`

脚本  
`navsea_audit.py`

### Step 07 - 构建密度与基础异常分析

目的  
计算瓦片密度与审计阶段的几何异常，为后续语义校验提供分析输入。

输入表  
`features`  
`feature_semantic`

输出表  
`tile_density`  
`tile_layer_density`  
`tile_density_top100`  
`anomaly_navigation_geom`  
`anomaly_reef_geom`  
`geometry_consistency_audit`

说明  
`geometry_consistency_audit` 是审计阶段保留下来的旧版几何分布快照，不是当前正式校验表。

脚本  
`navsea_audit.py`

### Step 08 - 构建来源层规则

目的  
基于现有 `source_layer`、样式绑定关系和语义密度，判断每个来源层属于：

```text
semantic_layer
container_layer
style_or_source_layer
```

输入表  
`feature_semantic`  
`style_layers`

输出表  
`canonical_layer_rules`

脚本  
`navsea_relayer.py`

### Step 09 - 构建规范对象规则

目的  
为每个 `canonical_object_type` 固化规范对象规则，包括：

- `canonical_family`
- `classification_basis`
- `source_layer_scope`
- `allowed_geom_types`
- `preferred_geom_type`

输入表  
`object_catalog`  
`object_type_stats`

输出表  
`canonical_object_rules`

补充输出表  
`object_geometry_allowlist`

脚本  
`navsea_relayer.py`

### Step 10 - 构建语义叠加层

目的  
在保留现有渲染轨的前提下，为每个要素附加：

- 规范对象类型
- 规范对象族
- 检测键
- 语义键
- 渲染兼容层

输入表  
`feature_semantic`  
`object_type_candidates`  
`canonical_layer_rules`  
`canonical_object_rules`

输出表  
`pbf_relayer_candidates`

脚本  
`navsea_relayer.py`

### Step 11 - 构建语义统计与检测目录

目的  
从语义叠加层生成两个下游核心视图：

1. 渲染兼容统计  
   用于确认 `render_layer` 与原有 `source_layer` 的数量关系

2. 检测目录  
   用于安全检测、对象检测和规则匹配

输入表  
`pbf_relayer_candidates`

输出表  
`pbf_source_object_stats`  
`pbf_render_compatibility`  
`pbf_detection_catalog`

脚本  
`navsea_relayer.py`

### Step 12 - 运行分类校验

目的  
确认每个 `canonical_object_type` 的映射是否稳定，是否存在未知对象、歧义映射或规则冲突。

输入表  
`pbf_source_object_stats`  
`canonical_object_rules`

输出表  
`classification_validation`

脚本  
`navsea_semantic_validation.py`

### Step 13 - 运行几何一致性校验

目的  
确认每个规范对象的几何类型是否符合白名单与规则定义。

输入表  
`pbf_detection_catalog`  
`object_geometry_allowlist`

输出表  
`geometry_consistency`

脚本  
`navsea_semantic_validation.py`

### Step 14 - 运行渲染等价校验

目的  
确认语义叠加层没有破坏现有 style 渲染轨。

输入表  
`style_layers`  
`features`  
`pbf_render_compatibility`

输出表  
`style_render_equivalence`

脚本  
`navsea_semantic_validation.py`

### Step 15 - 运行检测目录完整性校验

目的  
确认 `detection_key` 对象目录稳定且几何一致。

输入表  
`pbf_detection_catalog`  
`geometry_consistency`

输出表  
`detection_catalog_integrity`

脚本  
`navsea_semantic_validation.py`

### Step 16 - 运行空间密度诊断

目的  
基于 `features` 直接计算的瓦片密度和分 zoom 阈值，识别空间热点瓦片。

输入表  
`tile_density`  
`tile_layer_density`  
`features`  
`pbf_relayer_candidates`

输出表  
`spatial_anomalies`

规则要点  
- `tile_density` 只允许来自 `features`
- 每个 zoom 单独计算阈值
- 跳过 `z=0`
- 支持 `DENSITY_STATISTICS_ERROR`
- 每个异常 tile 单独落一行

脚本  
`navsea_semantic_validation.py`

### Step 17 - 生成总体验证结论

目的  
把分类、几何、渲染、检测目录和空间诊断汇总成一条总状态。

输入表  
`classification_validation`  
`geometry_consistency`  
`style_render_equivalence`  
`detection_catalog_integrity`  
`spatial_anomalies`

输出表  
`semantic_validation_summary`

脚本  
`navsea_semantic_validation.py`

## 3. 表依赖图

### 3.1 主干数据血缘

```text
原始 PBF
  ↓
features + properties
  ↓
at_attributes
  ↓
feature_semantic
  ├─→ object_catalog
  ├─→ object_type_candidates
  │     ↓
  │   object_type_stats
  │
  └─→ style_layers ← style.json

object_catalog + object_type_stats
  ↓
canonical_object_rules
  ↓
object_geometry_allowlist

feature_semantic + style_layers
  ↓
canonical_layer_rules

feature_semantic + object_type_candidates + canonical_layer_rules + canonical_object_rules
  ↓
pbf_relayer_candidates
  ↓
pbf_source_object_stats
  ├─→ pbf_render_compatibility
  └─→ pbf_detection_catalog
```

### 3.2 并行校验血缘

```text
pbf_source_object_stats + canonical_object_rules
  ↓
classification_validation

pbf_detection_catalog + object_geometry_allowlist
  ↓
geometry_consistency

style_layers + features + pbf_render_compatibility
  ↓
style_render_equivalence

pbf_detection_catalog + geometry_consistency
  ↓
detection_catalog_integrity

features
  ↓
tile_density + tile_layer_density
  ↓
spatial_anomalies

classification_validation
geometry_consistency
style_render_equivalence
detection_catalog_integrity
spatial_anomalies
  ↓
semantic_validation_summary
```

## 4. 表分类

下表按照当前数据库中的实际表进行分类。

| 表名 | 分类 | 说明 |
| --- | --- | --- |
| `features` | CORE TABLE | 原始要素主表，保存 `id`、`z/x/y`、`vt_layer`、`geom_type` |
| `properties` | CORE TABLE | 原始属性键值表 |
| `at_attributes` | SEMANTIC TABLE | `properties.k='at'` 的展开结果 |
| `feature_semantic` | SEMANTIC TABLE | 单要素语义投影表 |
| `object_type_candidates` | SEMANTIC TABLE | 对象类型候选表 |
| `object_catalog` | ANALYSIS TABLE | 对象目录与分布分析 |
| `object_type_stats` | ANALYSIS TABLE | 对象类型与几何统计 |
| `style_layers` | ANALYSIS TABLE | 从 `style.json` 提取的渲染层信息 |
| `style_mapping` | ANALYSIS TABLE | 样式层与对象候选的交叉映射 |
| `canonical_layer_rules` | SEMANTIC TABLE | 来源层规则表 |
| `canonical_object_rules` | SEMANTIC TABLE | 规范对象规则表 |
| `object_geometry_allowlist` | SEMANTIC TABLE | 对象几何白名单 |
| `pbf_relayer_candidates` | SEMANTIC TABLE | 语义叠加主表 |
| `pbf_source_object_stats` | ANALYSIS TABLE | 语义叠加聚合统计表 |
| `pbf_render_compatibility` | ANALYSIS TABLE | 渲染兼容统计表 |
| `pbf_detection_catalog` | SEMANTIC TABLE | 安全检测目录表 |
| `classification_validation` | VALIDATION TABLE | 分类稳定性校验表 |
| `geometry_consistency` | VALIDATION TABLE | 当前正式几何一致性校验表 |
| `geometry_consistency_audit` | ANALYSIS TABLE | 审计阶段保留的旧版几何快照 |
| `style_render_equivalence` | VALIDATION TABLE | 渲染等价校验表 |
| `detection_catalog_integrity` | VALIDATION TABLE | 检测目录完整性校验表 |
| `spatial_anomalies` | VALIDATION TABLE | 空间密度异常表 |
| `semantic_validation_summary` | VALIDATION TABLE | 整体验证摘要 |
| `tile_density` | ANALYSIS TABLE | 每瓦片 feature 数量 |
| `tile_layer_density` | ANALYSIS TABLE | 每瓦片、每来源层 feature 数量 |
| `tile_density_top100` | ANALYSIS TABLE | 最高密度瓦片 Top100 |
| `anomaly_navigation_geom` | ANALYSIS TABLE | 航标类几何异常审计 |
| `anomaly_reef_geom` | ANALYSIS TABLE | 鱼礁类几何异常审计 |
| `feature_flat` | TEMP TABLE | 当前数据库中的遗留/临时表，不在现行语义脚本主路径上 |

## 5. 官方执行顺序

当前建议的正式执行顺序如下：

1. 导入原始 PBF，生成 `features` 和 `properties`
2. 运行 `navsea_audit.py`，构建基础语义表、分析表和密度表
3. 运行 `navsea_relayer.py`，生成规范规则与语义叠加层
4. 运行 `navsea_semantic_validation.py`，生成分类、几何、渲染、检测目录和空间校验结果
5. 读取 `semantic_validation_summary` 确认总体状态
6. 以 `pbf_relayer_candidates` 为主表，结合 `features`、`properties`、`at_attributes` 产出下游 NavSea 数据集或矢量瓦片生产输入

## 6. 执行命令

### 6.1 构建基础语义与分析表

```bash
.venv/bin/python navsea_audit.py
```

作用  
从 `features` / `properties` 出发，构建：

- `at_attributes`
- `feature_semantic`
- `object_catalog`
- `geometry_consistency_audit`
- `object_type_candidates`
- `object_type_stats`
- `style_layers`
- `style_mapping`
- `tile_density`
- `tile_layer_density`
- `tile_density_top100`
- 审计异常表

### 6.2 构建语义叠加层

```bash
.venv/bin/python navsea_relayer.py
```

作用  
生成：

- `canonical_layer_rules`
- `canonical_object_rules`
- `object_geometry_allowlist`
- `pbf_relayer_candidates`
- `pbf_source_object_stats`
- `pbf_render_compatibility`
- `pbf_detection_catalog`

### 6.3 运行语义校验

```bash
.venv/bin/python navsea_semantic_validation.py
```

作用  
生成：

- `classification_validation`
- `geometry_consistency`
- `style_render_equivalence`
- `detection_catalog_integrity`
- `spatial_anomalies`
- `semantic_validation_summary`

### 6.4 仅重建密度表

如果只需要更新空间密度与热点诊断，可以单独执行：

```bash
.venv/bin/python - <<'PY'
from navsea_audit import NavSeaAudit, DbConfig
NavSeaAudit(DbConfig()).build_tile_density()
PY
```

随后再执行：

```bash
.venv/bin/python navsea_semantic_validation.py
```

## 7. 最终输出数据集

### 7.1 当前系统中的“最终语义数据集”

当前系统中，最接近“最终 NavSea 语义要素表”的主表是：

`pbf_relayer_candidates`

它保存了：

- `feature_id`
- `z/x/y`
- `source_layer`
- `geom_type`
- `class_name`
- `shape_name`
- `layer_name`
- `object_type_source`
- `canonical_object_type`
- `semantic_granularity`
- `canonical_family`
- `classification_basis`
- `source_layer_scope`
- `semantic_key`
- `detection_key`
- `render_layer`

### 7.2 原始属性与语义属性的对应关系

`pbf_relayer_candidates` 本身并不保存原始全部属性值，因此最终语义数据集应按下述方式理解：

- 原始要素主键与瓦片定位来自 `features`
- 原始属性全集来自 `properties`
- 展开的 `at` 属性来自 `at_attributes`
- 语义投影属性来自 `feature_semantic`
- 规范对象分类来自 `pbf_relayer_candidates`

也就是说，当前 NavSea 最终语义数据集实际上是一个“主表 + 关联表”结构：

```text
主表：
  pbf_relayer_candidates

关联恢复：
  features        → 原始要素标识、瓦片坐标、几何类型
  properties      → 原始属性键值
  at_attributes   → 展开的 at 属性
  feature_semantic → class_name / shape_name / layer_name
```

### 7.3 关于 geometry 的说明

当前数据库 schema 中，`features` 表仅保存：

- `id`
- `z/x/y`
- `vt_layer`
- `geom_type`

它不保存完整坐标几何体字段。  
因此，当前数据库中的“最终语义数据集”是面向语义重建、校验和下游生成的语义索引层，而不是一张带完整坐标几何的空间实体表。

### 7.4 下游生成 NavSea 数据的推荐入口

如果后续要生成 NavSea 下游数据或重新生成矢量瓦片，推荐以：

- `pbf_relayer_candidates` 作为语义主表
- `features` 作为原始要素锚点
- `properties` / `at_attributes` 作为原始属性源

共同构成生产输入。

## 8. 从零重建步骤

### 最小可复现步骤

1. 将原始 PBF 导入数据库，得到 `features` 与 `properties`
2. 执行 `navsea_audit.py`
3. 执行 `navsea_relayer.py`
4. 执行 `navsea_semantic_validation.py`
5. 检查 `semantic_validation_summary`
6. 若需要下游数据生产，则从 `pbf_relayer_candidates` 联合 `features`、`properties`、`at_attributes` 提取最终数据集

### 推荐的重建命令顺序

```bash
.venv/bin/python navsea_audit.py
.venv/bin/python navsea_relayer.py
.venv/bin/python navsea_semantic_validation.py
```

### 重建完成后的关键检查点

至少应检查以下表是否已刷新：

- `feature_semantic`
- `object_type_candidates`
- `canonical_object_rules`
- `canonical_layer_rules`
- `pbf_relayer_candidates`
- `pbf_detection_catalog`
- `classification_validation`
- `geometry_consistency`
- `style_render_equivalence`
- `detection_catalog_integrity`
- `spatial_anomalies`
- `semantic_validation_summary`

### 当前系统的审计终点

当前系统的“可审计终点”不是一个新的矢量瓦片文件，而是：

- 一套可复现的语义规则表
- 一套可复现的语义叠加主表
- 一套可重复执行的验证表

即：

```text
canonical_layer_rules
canonical_object_rules
pbf_relayer_candidates
pbf_detection_catalog
semantic_validation_summary
```

这套终点定义了 NavSea 当前语义流水线的正式数据库输出。