pbf/tasks/pbf/NavSea_Mapping_DB_Registry_v1.md

NavSea 映射关系数据库固化方案 v1

版本：v1
用途：把“旧版原始字段 / 层名 / 取值”和“新版标准化字段 / 语义 / 渲染语义”的关系正式固化到数据库里，作为后续规则审计、问题排查和构建回放的基础。

1 当前落地位置

本版已在 pbf_analysis 中建立以下正式对象：

• navsea_rule_bundle
• navsea_source_layer_rules
• navsea_field_name_rules
• navsea_field_value_rules
• navsea_taxonomy_rules
• navsea_render_rules
• navsea_mapping_registry_vw
• navsea_legacy_to_new_mapping_vw
• navsea_new_to_legacy_mapping_vw

2 规则源文件

数据库中的规则来自以下版本化文件：

• navsea_rule_bundle_v1.yaml
• navsea_source_layer_rules_v1.yaml
• navsea_field_name_rules_v1.yaml
• navsea_field_value_rules_v1.yaml
• navsea_taxonomy_rules_v1.yaml
• navsea_render_rules_v1.yaml

3 同步脚本

同步脚本：

• navsea_mapping_registry_sync.py
• navsea_mapping_registry.py

作用：

• 建表
• 从 YAML 导入 bundle / layer / field / value / taxonomy / render 规则
• 生成统一审计视图
• 在运行时由 builder 直接读取数据库规则，不再在多个文件中重复维护同一份映射常量

4 双向查询口径

旧版查新版：

SELECT *
FROM navsea_legacy_to_new_mapping_vw
WHERE legacy_key = '分類番号' AND legacy_value = '428';

新版查旧版：

SELECT *
FROM navsea_new_to_legacy_mapping_vw
WHERE new_key = 'chart_fill_style' AND new_value = 'fish_reef_area';

5 当前 v1 覆盖内容

• source-layer 日文层名到标准层名
• 旧字段名到标准字段名
• 关键旧字段取值到标准值
• taxonomy 规则
• render 规则

6 当前边界

本版已经把映射关系正式固化到了数据库里，并且 builder 已开始直接消费数据库规则，当前已接入：

• source-layer 标准化
• 旧字段值到新字段值的标准化
• 首批 render 规则

但还没有把 builder 的全部 infer_* 分支完全改造成“只从数据库执行规则”。
当前状态是：

• 规则资产已经固化在数据库
• 代码侧只保留兜底逻辑，数据库规则优先
• 后续可以逐步把执行层切到数据库规则驱动

6.1 未决对象处理规则

本体系中的“兜底”不等于“静默归入一个大筐”。

当前执行约束是：

• 如果没有命中特定 render 规则，不允许把 REN-FALLBACK 当成正常命中结果
• 这类对象会被标记为 trace_status = needs_review
• builder 会在每次构建后自动输出一份 mapping_audit 报告
• 报告中会列出未决对象的来源层、对象类型、几何类型、样本 fid 和原因

这条约束的目的是：

• 不让未覆盖对象悄悄混进“正常渲染”
• 不让规则缺口被一个泛化 fallback 掩盖
• 让后续补规则时有明确的对象清单

7 建议下一步

• 增加 navsea_feature_rule_trace 的数据库写入
• 让 builder 在 engineering 口径记录实际命中的 taxonomy_rule_id / render_rule_id
• 逐步把 infer_* 硬编码分支迁移到规则表执行