pbf/PBF_ANALYSIS_DATABASE_TABLES.md

# pbf_analysis 数据库表功能说明

## 1. 目的

这份文档说明当前 `pbf_analysis` 数据库中各张 NavSea 相关表的用途、所处阶段、与当前工程的关系。

目标是让后续接手的人能快速回答这些问题：

- 哪些表是原始解析结果
- 哪些表是语义分类与归层结果
- 哪些表是规则注册表
- 哪些表是检测/碰撞/航行分析专题视图
- 哪些表是样式分析与渲染审计结果
- 哪些表是历史分析或中间产物

## 2. 总体分层

当前 `pbf_analysis` 里的表可以按用途分成 6 类：

1. 原始与基础解析层
2. 语义分类与归层层
3. 几何与空间支撑层
4. 规则注册与映射层
5. 样式分析与渲染审计层
6. 业务专题与异常分析层

说明：

- `BASE TABLE` 表示实体表
- `VIEW` 表示视图
- `table_rows` 为 MySQL 估计值，仅用于了解量级

## 3. 关键原则

当前数据库不是只存“最终结果”，而是同时承担四类职责：

- 保存原始解析和展平结果
- 保存分类和标准化结果
- 保存可追溯规则注册表
- 保存审计与专题查询结果

后续开发应优先遵循：

- 映射规则尽量收口到规则表
- 审计结果进专门审计表
- 原始值与标准值并存，避免不可逆覆盖

## 4. 表分组说明

### 4.1 原始与基础解析层

这些表主要用于把原始 `pbf` 解码成可查询的结构化数据。

#### `features`

- 类型：`BASE TABLE`
- 估计行数：`6653014`
- 关键字段：
  - `id, z, x, y, vt_layer, geom_type`
- 用途：
  - 保存原始瓦片的基础 feature 索引
  - 作为很多后续表的原始主干

#### `properties`

- 类型：`BASE TABLE`
- 估计行数：`22213975`
- 关键字段：
  - `feature_id, k, v`
- 用途：
  - 存原始属性键值对
  - 便于后续抽取 `fid`、`分類番号`、`名称` 等字段

#### `at_attributes`

- 类型：`BASE TABLE`
- 估计行数：`6674189`
- 关键字段：
  - `feature_id, k, v`
- 用途：
  - 拆分原始 `at` 属性集合
  - 为分类、渲染兼容、规则归纳提供细粒度字段来源

#### `feature_flat`

- 类型：`VIEW`
- 关键字段：
  - `feature_id, vt_layer, class_id, fid, at`
- 用途：
  - 对原始 feature 做便于分析的展平视图
  - 常用于快速查看对象分类号和 `fid`

#### `feature_semantic`

- 类型：`BASE TABLE`
- 估计行数：`6367524`
- 关键字段：
  - `feature_id, z, x, y, vt_layer, geom_type, class_name, shape_name, layer_name`
- 用途：
  - 原始对象语义的早期抽取层
  - 为后续 taxonomy 和 render 分析提供基础口径

#### `feature_geojson_lookup`

- 类型：`BASE TABLE`
- 估计行数：`6636967`
- 关键字段：
  - `z, x, y, feature_id, fid, vt_layer, geom_type`
- 用途：
  - 做 feature 与瓦片实例的查询映射
  - 便于回查到具体 tile

### 4.2 几何与空间支撑层

这些表负责把原始 feature 补成可空间分析的对象。

#### `feature_geometry_stage`

- 类型：`BASE TABLE`
- 估计行数：`13597637`
- 关键字段：
  - `feature_id, geometry_wkt`
- 用途：
  - 几何导入与中间转换阶段表
  - 为后续空间启用、几何核查服务

#### `navsea_feature_geometry`

- 类型：`BASE TABLE`
- 估计行数：`6685117`
- 关键字段：
  - `feature_id, geometry, geometry_source`
- 用途：
  - NavSea 当前正式使用的 feature 几何表
  - 支撑碰撞、空间专题和检测视图

#### `geometry_consistency`

- 类型：`BASE TABLE`
- 估计行数：`327`
- 关键字段：
  - `canonical_object_type, geometry_type, feature_count, geometry_consistency_status`
- 用途：
  - 统计某类对象的几何类型是否符合预期

#### `geometry_consistency_audit`

- 类型：`BASE TABLE`
- 估计行数：`331`
- 关键字段：
  - `canonical_object_type, geometry_type, feature_count, geometry_consistency_status`
- 用途：
  - 与 `geometry_consistency` 类似，用于审计记录与复核

#### `object_geometry_allowlist`

- 类型：`BASE TABLE`
- 估计行数：`310`
- 关键字段：
  - `canonical_object_type, geometry_type, rule_source, is_allowed, notes`
- 用途：
  - 定义哪些对象类型允许哪些几何类型
  - 是 geometry 审计的规则依据之一

### 4.3 语义分类与归层层

这些表描述“对象是什么”和“应该归到哪一层”。

#### `object_catalog`

- 类型：`BASE TABLE`
- 估计行数：`319`
- 关键字段：
  - `layer_name, class_name, shape_name, vt_layer, geom_type, feature_count`
- 用途：
  - 原始对象目录
  - 手工 taxonomy 审查和统计的基础表

#### `object_type_candidates`

- 类型：`BASE TABLE`
- 估计行数：`6473314`
- 关键字段：
  - `feature_id, object_type_source, object_type, vt_layer, geom_type`
- 用途：
  - 某个 feature 可能属于哪些对象类型的候选集合
  - 是 taxonomy 判定前的候选层

#### `object_type_stats`

- 类型：`BASE TABLE`
- 估计行数：`255`
- 关键字段：
  - `object_type, geom_type, feature_count`
- 用途：
  - 对候选对象类型做统计

#### `canonical_object_rules`

- 类型：`BASE TABLE`
- 估计行数：`221`
- 关键字段：
  - `canonical_object_type, canonical_family, classification_basis, source_layer_scope, ...`
- 用途：
  - 旧版人工整理的对象级归类规则汇总表
  - 偏分析结果，不是最新规则注册表

#### `canonical_layer_rules`

- 类型：`BASE TABLE`
- 估计行数：`49`
- 关键字段：
  - `source_layer, semantic_granularity, canonical_family, render_strategy, ...`
- 用途：
  - 旧版人工整理的层级归并规则表
  - 用于理解老系统如何按层做语义合并

#### `feature_semantic`

- 已在基础层列出
- 同时也是对象语义候选的重要来源

#### `pbf_relayer_candidates`

- 类型：`BASE TABLE`
- 估计行数：`6547009`
- 关键字段：
  - `feature_id, z, x, y, source_layer, geom_type, ... canonical_object_type, canonical_family, semantic_key, detection_key, render_layer`
- 用途：
  - 当前构建 `pbf` 时最重要的结果表之一
  - 保存 feature 经过分类和归层后的候选结果
  - `navsea_tile_builder.py` 会结合该表与原始 `pbf` 一起输出新瓦片

#### `pbf_source_object_stats`

- 类型：`BASE TABLE`
- 估计行数：`215`
- 关键字段：
  - `source_layer, render_layer, canonical_family, canonical_object_type, geom_type, detection_key, semantic_key, feature_count`
- 用途：
  - 统计不同源层在重构后如何分布

#### `pbf_render_compatibility`

- 类型：`BASE TABLE`
- 估计行数：`58`
- 关键字段：
  - `source_layer, render_layer, canonical_family, semantic_granularity, style_bound, feature_count, canonical_object_types`
- 用途：
  - 评估重构后数据与旧样式兼容性的分析表

#### `pbf_detection_catalog`

- 类型：`BASE TABLE`
- 估计行数：`359`
- 关键字段：
  - `detection_key, canonical_family, canonical_object_type, geom_type, feature_count, source_layers`
- 用途：
  - 检测视角的对象目录
  - 支撑 detection_key 设计与校验

### 4.4 规则注册与映射层

这组表是现在最重要的“规则中心”，用于收口旧版到新版的映射逻辑。

#### `navsea_rule_bundle`

- 类型：`BASE TABLE`
- 估计行数：`1`
- 关键字段：
  - `bundle_id, bundle_version, status, effective_date, ...`
- 用途：
  - 规则包总表
  - 记录当前使用的是哪一套 taxonomy/render/source-layer/field-value 规则

#### `navsea_source_layer_rules`

- 类型：`BASE TABLE`
- 估计行数：`49`
- 关键字段：
  - `source_layer_jp, source_layer_std, semantic_granularity, canonical_family, render_strategy, ...`
- 用途：
  - 日文 `source-layer` 到标准层名的映射规则
  - 是 source-layer 可逆标准化的正式注册表

#### `navsea_field_name_rules`

- 类型：`BASE TABLE`
- 估计行数：`17`
- 关键字段：
  - `field_name_jp, field_name_std, field_group_name, keep_in_delivery, keep_in_engineering, ...`
- 用途：
  - 旧字段名到标准字段名的映射
  - 同时定义字段在哪种输出中保留

#### `navsea_field_value_rules`

- 类型：`BASE TABLE`
- 估计行数：`20`
- 关键字段：
  - `rule_id, field_name_jp, legacy_value, standardized_field, standardized_value, ...`
- 用途：
  - 旧字段值到新标准字段值的映射
  - 例如灯色、表示位置等值映射

#### `navsea_taxonomy_rules`

- 类型：`BASE TABLE`
- 估计行数：`8`
- 关键字段：
  - `rule_id, priority, enabled, match_scope, match_expr_json, output_json, canonical_family, canonical_object_type, detection_key_template`
- 用途：
  - 正式 taxonomy 规则表
  - 定义 feature 在什么条件下被归成哪个 `canonical_object_type`

#### `navsea_render_rules`

- 类型：`BASE TABLE`
- 估计行数：`9`
- 关键字段：
  - `rule_id, priority, match_expr_json, output_json, chart_render_type, chart_symbol_code, chart_fill_style, ...`
- 用途：
  - 正式渲染语义规则表
  - 定义 feature 应输出哪些 `chart_* / hazard_* / area_*` 字段

#### `navsea_mapping_registry_vw`

- 类型：`VIEW`
- 用途：
  - 统一查看当前各类映射规则
  - 适合人工巡检和管理

#### `navsea_legacy_to_new_mapping_vw`

- 类型：`VIEW`
- 用途：
  - 从旧值查新值
  - 适合排查“旧字段为什么被映射成这个新字段”

#### `navsea_new_to_legacy_mapping_vw`

- 类型：`VIEW`
- 用途：
  - 从新值反查旧值
  - 适合可逆追述和规则审计

### 4.5 NavSea 对象字典与能力表

#### `navsea_object_taxonomy`

- 类型：`BASE TABLE`
- 估计行数：`127`
- 关键字段：
  - `canonical_object_type, object_family, detection_class, description`
- 用途：
  - NavSea 对象字典
  - 定义各 canonical object 的基础说明

#### `navsea_object_capabilities`

- 类型：`BASE TABLE`
- 估计行数：`259`
- 关键字段：
  - `canonical_object_type, capability`
- 用途：
  - 定义对象能力，例如是否用于碰撞、导航参考、缠绕风险等
  - 给下游专题视图提供能力标签

### 4.6 样式分析与渲染审计层

#### `style_layers`

- 类型：`BASE TABLE`
- 估计行数：`113`
- 关键字段：
  - `layer_id, source_layer, icon, line_color, fill_color, layer_type`
- 用途：
  - 解析旧样式后的 layer 清单

#### `style_mapping`

- 类型：`BASE TABLE`
- 估计行数：`42`
- 关键字段：
  - `layer_id, source_layer, layer_type, icon, line_color, fill_color, object_type, geom_type, feature_count`
- 用途：
  - 分析旧样式的 source-layer 消费关系

#### `style_render_equivalence`

- 类型：`BASE TABLE`
- 估计行数：`53`
- 关键字段：
  - `style_layer, feature_count_before, feature_count_after, difference, render_status`
- 用途：
  - 用于分析重构前后样式层渲染覆盖是否等价

#### `navsea_render_audit_run`

- 类型：`BASE TABLE`
- 估计行数：`1`
- 关键字段：
  - `audit_name, original_style_path, engineering_style_path, original_tile_root, engineering_tile_root, result_count, status_counts_json, ...`
- 用途：
  - 存放“最新一次”渲染审计的摘要
  - 当前约定只保留最新一轮结果

#### `navsea_render_audit_result`

- 类型：`BASE TABLE`
- 估计行数：`2357346`
- 关键字段：
  - `audit_name, object_instance_key, object_instance_id, object_id, fid_legacy, tile_z, tile_x, tile_y, source_layer, status, original_components_json, engineering_components_json`
- 用途：
  - 渲染审计结果明细表
  - 可按 `fid_legacy` 追查某个对象在原始样式和工程样式下的渲染差异

### 4.7 业务专题与异常分析层

这组表/视图偏业务消费和专题分析。

#### `navsea_detection_objects`

- 类型：`VIEW`
- 用途：
  - 检测对象总视图
  - 面向 detection 任务使用

#### `navsea_detection_objects_spatial`

- 类型：`VIEW`
- 用途：
  - 检测对象的空间分析视图

#### `navsea_collision_objects`

- 类型：`VIEW`
- 用途：
  - 碰撞相关对象视图

#### `navsea_grounding_objects`

- 类型：`VIEW`
- 用途：
  - 搁浅风险相关对象视图

#### `navsea_entangle_objects`

- 类型：`VIEW`
- 用途：
  - 缠绕风险相关对象视图

#### `navsea_boundary_reference_objects`

- 类型：`VIEW`
- 用途：
  - 边界参考对象视图

#### `navsea_route_reference_objects`

- 类型：`VIEW`
- 用途：
  - 航路参考对象视图

#### `navsea_navigation_mark_objects`

- 类型：`VIEW`
- 用途：
  - 航标专题对象视图

#### `anomaly_navigation_geom`

- 类型：`BASE TABLE`
- 估计行数：`0`
- 用途：
  - 导航相关几何异常对象表

#### `anomaly_reef_geom`

- 类型：`BASE TABLE`
- 估计行数：`13`
- 用途：
  - 鱼礁/礁石类几何异常对象表

#### `spatial_anomalies`

- 类型：`BASE TABLE`
- 估计行数：`693`
- 关键字段：
  - `anomaly_type, affected_feature_count, region_hint, severity`
- 用途：
  - 空间异常摘要

#### `classification_validation`

- 类型：`BASE TABLE`
- 估计行数：`177`
- 用途：
  - 分类结果验证摘要

#### `detection_catalog_integrity`

- 类型：`BASE TABLE`
- 估计行数：`343`
- 用途：
  - 检测目录完整性校验

#### `semantic_validation_summary`

- 类型：`BASE TABLE`
- 估计行数：`1`
- 用途：
  - 语义验证总摘要

### 4.8 密度与覆盖统计层

#### `tile_density`

- 类型：`BASE TABLE`
- 估计行数：`65467`
- 关键字段：
  - `z, x, y, feature_count`
- 用途：
  - 每个 tile 的 feature 密度统计

#### `tile_density_top100`

- 类型：`BASE TABLE`
- 估计行数：`100`
- 用途：
  - feature 最密的 top100 tile

#### `tile_layer_density`

- 类型：`BASE TABLE`
- 估计行数：`207315`
- 关键字段：
  - `z, x, y, vt_layer, feature_count`
- 用途：
  - 按 tile 和 layer 分解的密度统计

## 5. 当前工程最重要的表

如果只看当前构建与审计链路，最重要的是这些：

### 构建时必看

- `pbf_relayer_candidates`
- `navsea_rule_bundle`
- `navsea_source_layer_rules`
- `navsea_field_name_rules`
- `navsea_field_value_rules`
- `navsea_taxonomy_rules`
- `navsea_render_rules`
- `navsea_feature_geometry`

### 审计时必看

- `navsea_render_audit_run`
- `navsea_render_audit_result`
- `style_layers`
- `style_mapping`
- `style_render_equivalence`

### 数据理解时必看

- `object_catalog`
- `pbf_source_object_stats`
- `pbf_detection_catalog`
- `navsea_object_taxonomy`
- `navsea_object_capabilities`

## 6. 当前推荐使用方式

### 想查某个对象为什么被分类成某个新对象

优先查：

- `pbf_relayer_candidates`
- `navsea_taxonomy_rules`
- `navsea_legacy_to_new_mapping_vw`

### 想查某个对象为什么被渲染成某种 `chart_*`

优先查：

- `navsea_render_rules`
- `navsea_mapping_registry_vw`
- 工程版 `pbf` 中对应 feature 的输出字段

### 想查某个对象原始版和工程版渲染是否一致

优先查：

- `navsea_render_audit_result`
- `navsea_render_audit_run`

### 想做碰撞、搁浅、航路专题分析

优先查：

- `navsea_collision_objects`
- `navsea_grounding_objects`
- `navsea_route_reference_objects`
- `navsea_navigation_mark_objects`

## 7. 维护建议

当前数据库里同时有“旧分析表”和“新规则注册表”，后续维护建议如下：

- 正式规则源以 `tasks/pbf/mappings/*.yaml` 为主
- 数据库规则表作为运行时注册中心
- 不要再把同一套逻辑分散写进多个临时分析表
- 新增规则时优先更新：
  - `navsea_rule_bundle`
  - `navsea_source_layer_rules`
  - `navsea_field_name_rules`
  - `navsea_field_value_rules`
  - `navsea_taxonomy_rules`
  - `navsea_render_rules`

## 8. 与 Git 管理的关系

建议把下面这些内容一起纳入项目 Git：

- 本文档
- `tasks/pbf/` 下的规范文档
- `tasks/pbf/mappings/` 下的规则源文件
- `navsea_mapping_registry_sync.py`
- `navsea_tile_builder.py`
- `navsea_render_audit.py`

这样数据库中的规则、代码中的构建逻辑、审计流程就能形成完整闭环。