fujian_water_biz_doc/specs/008-rev004-legacy-finance-migration/contracts/rev004-batch1-code-conversion-dictionary-v1.md

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. 第一批次差异清单模板
   专门记录编码映射缺口、无法确认项和人工补录项