# 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` 这样数据库中的规则、代码中的构建逻辑、审计流程就能形成完整闭环。