Initial import of NavSea pbf project

PBF_ANALYSIS_DATABASE_TABLES.md

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