# Dictionary: REV-004 第一批次编码转换字典 v1

## 1. 目标

本字典用于补齐第一批次试迁中最容易导致字段映射失真的编码转换规则。

当前仅覆盖三类核心编码：

- `PriceListId`
- `PriceCode`
- `PriceItemId`

它们分别影响：

- 账单主表中的调价号 / 调价快照承接
- 账单主表与明细中的用水性质 / 价格模板承接
- 明细中的费用组成承接

## 2. 使用原则

- 本字典当前是 v1 规划字典，不假定所有旧编码与新编码已经一一建立物理映射表。
- 若当前 backend 已存在稳定编码主数据，应优先落到现有主数据对象。
- 若当前尚未确认稳定编码表，则先保留“旧值 + 映射占位 + 追溯字段”，不要在脚本里硬编码不可验证的转换结果。

## 3. 编码转换规则总览

| 旧字段 | 旧语义 | 新承接字段 | 当前转换方式 | 当前状态 | 备注 |
| --- | --- | --- | --- | --- | --- |
| `PriceListId` | 调价号 / 水价调整编号 | `adjustmentSnapCode` | `legacy int -> new string code` | `needs-mapping` | 需要形成调价号到快照编码的转换字典 |
| `PriceCode` | 用水性质 / 价格类别编码 | `priceTemplateCode` | `legacy int -> new string template code` | `needs-mapping` | 需要形成旧用水性质到新价格模板编码的转换字典 |
| `PriceItemId` | 费用组成 ID | `costComponentCode` | `legacy int -> new string component code` | `needs-mapping` | 需要形成旧费用项到新费用组成编码的转换字典 |

## 4. `PriceListId` 转换字典

### 4.1 承接目标

| 旧字段 | 新字段 | 说明 |
| --- | --- | --- |
| `AT_CHARGES.PriceListId` | `biz_charge.adjustmentSnapCode` | 账单主表调价快照编码 |
| `AT_CHARGE_DETAILS.PriceListId` | `biz_charge_detail.adjustmentSnapCode` | 账单明细调价快照编码 |

### 4.2 当前转换策略

在未建立完整字典前，建议采用两段式处理：

1. 迁移脚本先保留原值到映射层
2. 主表字段使用可验证的新编码规则转换，若无法确定则标记待补

### 4.3 推荐映射结构

| 字段 | 说明 |
| --- | --- |
| `legacyPriceListId` | 旧调价号 |
| `targetAdjustmentSnapCode` | 新调价快照编码 |
| `mappingSource` | 来源：主数据 / 规则推导 / 手工补录 |
| `mappingStatus` | `planned / verified / unresolved` |
| `remark` | 备注 |

### 4.4 当前脚本建议

- 若存在稳定调价快照表和唯一编码，可直接转换。
- 若不存在稳定映射来源：
  - `adjustmentSnapCode` 可先按约定规则生成占位值
  - 同时必须写入 `legacyPriceListId`
  - `mappingStatus` 标记为 `unresolved`

## 5. `PriceCode` 转换字典

### 5.1 承接目标

| 旧字段 | 新字段 | 说明 |
| --- | --- | --- |
| `AT_CHARGES.PriceCode` | `biz_charge.priceTemplateCode` | 账单主表价格模板编码 |
| `AT_CHARGE_DETAILS.PriceCode` | `biz_charge_detail.priceTemplateCode` | 账单明细价格模板编码 |

### 5.2 当前转换策略

`PriceCode` 在旧模型里是整数型“用水性质”，在新模型里更接近字符串型模板编码。

因此本轮不建议简单字符串化后直接当正式编码使用，而应采用：

- `legacyPriceCode` 保留旧值
- `targetPriceTemplateCode` 记录新值
- 明确映射来源

### 5.3 推荐映射结构

| 字段 | 说明 |
| --- | --- |
| `legacyPriceCode` | 旧用水性质编码 |
| `targetPriceTemplateCode` | 新价格模板编码 |
| `priceCategoryName` | 可选，用于人工核对 |
| `mappingSource` | 来源：价格模板表 / 规则推导 / 手工补录 |
| `mappingStatus` | `planned / verified / unresolved` |

### 5.4 当前脚本建议

- 若已有价格模板主数据且存在旧编码字段，优先按主数据表映射。
- 若无稳定映射来源，暂不把脚本写成“旧值转字符串”这种伪映射。
- 所有无法确认的值必须落差异清单。

## 6. `PriceItemId` 转换字典

### 6.1 承接目标

| 旧字段 | 新字段 | 说明 |
| --- | --- | --- |
| `AT_CHARGE_DETAILS.PriceItemId` | `biz_charge_detail.costComponentCode` | 明细费用组成编码 |

### 6.2 当前转换策略

`PriceItemId` 旧模型是费用组成主键，当前新模型更偏编码型字段 `costComponentCode`。

这类转换比 `PriceListId` 和 `PriceCode` 更敏感，因为它直接影响费用构成、统计汇总和开票明细。

### 6.3 推荐映射结构

| 字段 | 说明 |
| --- | --- |
| `legacyPriceItemId` | 旧费用组成 ID |
| `targetCostComponentCode` | 新费用组成编码 |
| `targetCostComponentName` | 新费用组成名称 |
| `mappingSource` | 来源：费用组成主数据 / 手工字典 |
| `mappingStatus` | `planned / verified / unresolved` |

### 6.4 当前脚本建议

- 没有稳定费用组成字典前，不要直接迁移到正式 `costComponentCode`。
- 可先写入映射表，待字典确认后再回填主表。
- 对无法映射的费用项必须记录差异，不能静默丢弃。

## 7. 第一批次最小字典表建议

后续如果进入脚本实施，建议至少准备三张字典或等价数据集：

| 字典名称 | 用途 |
| --- | --- |
| `legacy_price_list_mapping` | `PriceListId -> adjustmentSnapCode` |
| `legacy_price_code_mapping` | `PriceCode -> priceTemplateCode` |
| `legacy_price_item_mapping` | `PriceItemId -> costComponentCode` |

每张字典至少包含：

- `legacyCode`
- `targetCode`
- `targetName`
- `mappingSource`
- `mappingStatus`
- `remark`

## 8. 当前 v1 的直接结论

### 8.1 可以先不阻塞试迁的项

- `PriceListId`
- `PriceCode`

前提是：

- 原值必须保留
- 差异必须可追踪
- 未确认映射不得伪造正式编码

### 8.2 不能随便糊过去的项

- `PriceItemId`

因为它直接影响：

- 费用组成
- 开票明细
- 金额汇总
- 后续统计与审计

所以 `PriceItemId` 的字典确认优先级高于前两者。

## 9. 后续动作

本字典之后，建议继续补：

1. 第一批次枚举值对照表  
   重点是 `PayState`、`FeeState`、`AccountState`

2. 第一批次差异清单模板  
   专门记录编码映射缺口、无法确认项和人工补录项