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

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