# 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](/root/weather/tasks/pbf/mappings/navsea_rule_bundle_v1.yaml)
- [navsea_source_layer_rules_v1.yaml](/root/weather/tasks/pbf/mappings/navsea_source_layer_rules_v1.yaml)
- [navsea_field_name_rules_v1.yaml](/root/weather/tasks/pbf/mappings/navsea_field_name_rules_v1.yaml)
- [navsea_field_value_rules_v1.yaml](/root/weather/tasks/pbf/mappings/navsea_field_value_rules_v1.yaml)
- [navsea_taxonomy_rules_v1.yaml](/root/weather/tasks/pbf/mappings/navsea_taxonomy_rules_v1.yaml)
- [navsea_render_rules_v1.yaml](/root/weather/tasks/pbf/mappings/navsea_render_rules_v1.yaml)

## 3 同步脚本

同步脚本：

- [navsea_mapping_registry_sync.py](/root/weather/navsea_mapping_registry_sync.py)
- [navsea_mapping_registry.py](/root/weather/navsea_mapping_registry.py)

作用：

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

## 4 双向查询口径

旧版查新版：

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

新版查旧版：

```sql
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_*` 硬编码分支迁移到规则表执行
