遗留系统数据迁移实战（九）：区域编码迁移与补偿接口设计

为什么区域迁移复杂

区域看起来只是一个字段，实际影响很多业务：

设备归属
抄表册选表
抄表任务范围
数据权限
统计报表
页面树形展示

如果区域迁错，数据可能还能落库，但业务使用会出问题。

老系统和新系统的差异

遗留系统常见区域字段是长编码，例如：

text 复制代码

国家 + 城市 + 区域 + 小区 + 楼栋

新系统可能有自己的区域表：

text 复制代码

region_id
parent_id
region_code
level
tenant_id

两边不一定一一对应。

为什么需要补偿接口

一开始可以在主流程中直接转换区域，但后来发现不够灵活。

原因是：

区域数据可能先迁，也可能后修
某些非核心区域在新系统里没有映射
WalkBy 册子区域关系和设备区域关系不完全一样
历史数据可能存在脏区域

所以最终采用：

text 复制代码

主迁移流程先落库
区域补偿接口后修正

这样主流程更稳，区域问题可以单独处理和验证。

补偿接口做什么

区域补偿主要处理几类数据：

text 复制代码

dev_device_instance.region_code
rm_record.region_code
rm_record_hi.region_code
rm_rela_book_region
province_id / city_id / region_id

核心目标是：

text 复制代码

把老系统区域编码转换成新系统区域编码
并修复依赖区域的业务关系

非核心区域无法映射怎么办

迁移中经常遇到源库区域无法映射到目标区域。

这不一定是失败。

需要区分：

核心业务区域无法映射
非核心历史区域无法映射

如果是非核心历史区域，可能只影响历史册子记录，不影响当前设备和业务使用，可以作为 non_core_unmapped_region_codes 返回。

这样接口返回更清楚：

text 复制代码

core_unmapped_region_codes = []
non_core_unmapped_region_codes = [...]
business_region_ready = true

这比简单返回"有 unmapped"更容易验收。

为什么不强行创建区域

自动创建区域看起来方便，但风险很高。

区域是权限和业务范围的基础数据。如果自动创建错层级、错租户、错父级，会导致更严重的问题。

更稳妥的做法是：

text 复制代码

核心区域必须提前准备好
迁移只做映射和补偿
找不到的区域显式返回
由人工确认是否需要补区域

省市区层级字段怎么补

有些业务表不仅有 region_code，还有：

text 复制代码

province_id
city_id
region_id

补偿时可以通过当前区域向上递归父级：

text 复制代码

当前区域 -> parent_id -> parent_id -> ...

找到 level 为 1、2、3 的节点后，分别回写到对应字段。

如果某一级找不到，不应该清空原字段，而是保留原值。

为什么保留原值

区域补偿应该尽量是低风险操作。

如果某一级找不到就清空，可能把原本正确的数据破坏掉。保留原值意味着：

text 复制代码

能补的补
不能补的不破坏

这更适合生产迁移。

总结

区域补偿接口的核心设计原则是：

text 复制代码

主流程不被区域细节阻塞
核心区域必须正确
非核心区域显式返回
能补则补，不能补不破坏