# NavSea 可逆标准化规则 v1

版本：v1 Draft  
用途：定义 NavSea 在“日文原始数据 -> 标准化字段/层名/渲染语义”过程中必须遵循的可逆标准化规则，确保转换严谨、可追溯、可回退、可重复执行。

## 1 目标

NavSea 的标准化不是“清洗掉旧数据”，而是：

- 保留原始信息
- 新增标准化结果
- 记录完整映射过程
- 允许从标准化结果反查原始值

一句话原则：

> 标准化只能增加表达层，不能破坏原始信息层。

## 2 适用范围

本规则适用于以下对象：

- 日文 `source-layer`
- 原始日文字段名
- 原始日文字段值
- taxonomy 标准化字段
- render 语义字段
- 输出 `pbf`
- SQL 规则表与 trace 表

## 3 核心原则

### 3.1 原始值不可丢

所有参与标准化的关键输入都必须有原始保留位。

包括但不限于：

- 原始 `source-layer`
- 原始字段名
- 原始字段值
- 原始 `at`
- 原始 `fid`

### 3.2 标准化结果必须新增，不可覆盖原值

禁止直接把原值物理改写成标准值后不留痕迹。

正确做法：

- 原值保留
- 标准值新增
- 二者由规则表与 trace 表关联

### 3.3 每一步标准化都必须有规则来源

任何标准化结果都必须能回答：

- 是哪条规则做的
- 规则版本是什么
- 使用了哪些原始字段

### 3.4 每一步标准化都必须可逆

可逆的含义不是“自动完全恢复所有原始结构”，而是：

- 能从标准值回查原始值
- 能从 feature 回查到规则和版本
- 能重演同一批输入得到同一批输出

### 3.5 delivery 可以简化，engineering 不可失真

delivery `pbf` 可以只暴露必要字段。  
但 engineering `pbf` / SQL 审计表必须保留足够信息，支持回查。

## 4 不可做的事

以下操作在 v1 规则下视为禁止：

- 直接删除原始 `source-layer`，且不保留 `source_layer_jp`
- 直接删除原始字段值，且不保留原值副本
- 在 SQL 里手工改结果，不回写规则文件
- 在代码里加临时 if 分支，不形成规则 ID 和版本
- 只保留标准化结果，不保留 trace

## 5 字段分层

NavSea 标准化后，字段应分成三层。

### 5.1 原始层

职责：完整保留输入信息。

建议字段：

- `source_layer_jp`
- `original_properties_json`
- `at_raw`
- `fid`
- 原始 `分類番号`
- 原始 `形状分類番号`
- 原始 `表示用番号`
- 原始 `名称`
- 原始 `日本語地名`

### 5.2 标准化层

职责：输出结构化、可消费的标准字段。

建议字段：

- `source_layer_std`
- `canonical_family`
- `canonical_object_type`
- `detection_key`
- `chart_render_type`
- `chart_symbol_family`
- `chart_symbol_code`
- `chart_line_style`
- `chart_fill_style`
- `chart_text_style`

### 5.3 trace 层

职责：连接“原始层”和“标准化层”。

建议字段：

- `normalization_bundle_id`
- `source_layer_rule_id`
- `taxonomy_rule_id`
- `render_rule_id`
- `rule_revision`
- `source_fields_used_json`
- `trace_status`

## 6 可逆标准化对象

## 6.1 `source-layer` 标准化

建议采用双字段：

- `source_layer_jp`
- `source_layer_std`

示例：

- `source_layer_jp = P錨泊地等`
- `source_layer_std = anchorage_area`

要求：

- 原始日文层名不可直接丢弃
- 标准层名必须来自规则表，不得手工散落在代码里

## 6.1.1 `fid` 标准化

NavSea 不应直接对外继续使用旧版原始 `fid` 作为最终对象 ID。

规则要求：

- `delivery` / `engineering` 对外主 `fid` 使用 NavSea 自有 `fid`
- NavSea 自有 `fid` 由旧版 `fid` 经 `tasks/pbf/fiddecode.md` 中的可逆算法生成
- 生成结果使用 16 进制字符串表达

建议定义：

- `fid_legacy_raw`：旧版原始整数 `fid`
- `fid_navsea_int`：经过可逆加密后的非负整数
- `fid`：最终对外使用的 16 进制字符串，例如固定宽度大写 HEX
- `fid_algo_id`：例如 `feistel32_aes_cyclewalk_v1`
- `fid_key_id`：用于标识采用了哪把密钥

建议生成规则：

1. 读取旧版 `fid`
2. 使用 `fiddecode.md` 中的 `encrypt_number` 算法生成 `fid_navsea_int`
3. 将 `fid_navsea_int` 编码为固定宽度 16 进制字符串
4. 在 engineering / trace 中保留 `fid_legacy_raw`

补充口径：

- `fid` 可逆算法沿用 `fiddecode.md` 中的 Feistel + AES cycle-walking 方案
- 为保证对真实历史数据全覆盖，工程实现应采用 `signed int32` 全域
- 不应把示例文档中的局部样本范围误当成生产限制

要求：

- `fid` 必须可逆回查到 `fid_legacy_raw`
- 不允许只保留新 `fid`，却丢失旧 `fid`
- 不允许直接把旧 `fid` 原样转成 HEX 当作“新 `fid`”

## 6.2 原始字段名标准化

对原始字段名建议也采用双字段表达。

例如：

- `field_name_jp = 形状分類番号`
- `field_name_std = shape_class_code`

注意：

- 这里只是定义映射关系
- 不代表 delivery `pbf` 必须立刻把所有原字段名换掉

## 6.3 原始字段值标准化

例如：

- `灯色 = 1` -> `light_color_code = white`
- `形状分類番号 = 335` -> `nav_mark_variant = vais`

要求：

- 原值保留
- 标准值新增
- 必须记录规则 ID

## 7 保留策略

## 7.1 必须保留的原始日文内容

以下属于“内容型日文”，不能因为标准化就删除：

- `名称`
- `名称補助`
- `日本語地名`
- `灯略記`
- 其他对展示、检索、业务解释有价值的原始说明文本

## 7.2 可标准化但需保留原值的结构型日文

以下属于“结构型日文”，可以标准化，但必须保留原值：

- 日文 `source-layer`
- 原始字段名
- `at` 中的结构型键值
- 旧样式直接消费的技术性编码字段

## 7.3 delivery 可隐藏，engineering 必保留

对结构型日文建议：

- delivery `pbf` 可以只暴露标准字段
- engineering `pbf` / SQL 审计表必须保留原值和映射关系

## 8 规则文件要求

为保证可逆与可重复，以下规则必须文件化：

- `source-layer` 标准化规则
- taxonomy 规则
- render 规则
- 字段名标准化规则
- 字段值标准化规则

建议目录：

```text
tasks/pbf/mappings/
  navsea_fid_rules_v1.yaml
  navsea_source_layer_rules_v1.yaml
  navsea_taxonomy_rules_v1.yaml
  navsea_render_rules_v1.yaml
  navsea_field_name_rules_v1.yaml
  navsea_field_value_rules_v1.yaml
  navsea_rule_bundle_v1.yaml
```

## 9 SQL 结构要求

为保证可逆与可查询，建议至少有以下表：

- `navsea_rule_bundle`
- `navsea_source_layer_rules`
- `navsea_taxonomy_rules`
- `navsea_render_rules`
- `navsea_field_name_rules`
- `navsea_field_value_rules`
- `navsea_feature_rule_trace`

## 10 feature trace 最低要求

每个被标准化的 feature 至少应记录：

- `feature_id`
- `fid`
- `fid_legacy_raw`
- `fid_navsea_int`
- `fid_algo_id`
- `fid_key_id`
- `source_layer_jp`
- `source_layer_std`
- `normalization_bundle_id`
- `source_layer_rule_id`
- `taxonomy_rule_id`
- `render_rule_id`
- `source_fields_used_json`
- `trace_status`

## 11 delivery / engineering 输出要求

## 11.1 delivery pbf

目的：给前端渲染和检索使用。

要求：

- 可适度简化字段
- 但不能影响业务使用
- 若隐藏原值，必须仍可通过 SQL trace 回查

## 11.2 engineering pbf

目的：审计、复盘、问题定位。

要求：

- 保留原值
- 保留标准值
- 保留规则 ID
- 保留 bundle 版本

## 12 可逆性验收条件

只有同时满足以下条件，才可称为“可逆标准化”：

1. 能从标准值回查原始值
2. 能从 feature 回查规则 ID 和版本
3. 能重放同一批输入并得到同一批输出
4. 原始内容型日文未被误删
5. delivery 的简化不影响 engineering 的回查能力

## 13 v1 落地建议

第一阶段建议先做到：

1. 所有日文 `source-layer` 增加 `source_layer_std`
2. `fid` 改为 NavSea 自有 16 进制 `fid`
3. 新增 `fid` 规则文件和 `fid` trace 字段
4. 新增 `source-layer` 规则文件
5. 在 trace 表中记录 `source_layer_rule_id`
6. 保留原始内容型日文字段
7. 严禁在没有 trace 的情况下直接删除原始结构字段

## 14 结论

NavSea 的标准化必须是：

- 可逆的
- 可追溯的
- 可重复执行的
- 区分原始层、标准化层和 trace 层的

换句话说，标准化不是“替换”，而是“带证据的映射”。
