7.3 KiB
7.3 KiB
Matrix: REV-004 新旧标识映射矩阵 v1
1. 说明
本矩阵用于定义迁移后必须保留的新旧标识关系，确保以下能力不丢失：
- 迁移验收对账
- 历史明细追溯
- 审计与问题定位
- 旧单据到新业务对象的关系恢复
如果没有这张矩阵，即使数据迁过去，后续也很容易出现“查得到结果，但找不回原单据链”的问题。
2. 标识映射原则
- 每一类核心业务对象都必须保留“旧主键 + 旧业务单号 + 新主键 + 新业务单号”的最小映射能力。
- 对于账单、流水、申请单、发票号等强业务标识，不允许只保留新值不保留旧值。
- 若新系统不存在完全等价的新业务单号，至少保留新主键和映射批次号。
- 新旧标识映射对象必须可按批次、对象类型和映射状态查询。
3. 映射矩阵
| 旧对象 | 旧主键 | 旧业务标识 | 新对象 | 新主键 | 新业务标识 | 映射承接层 | 最低保留要求 | 说明 |
|---|---|---|---|---|---|---|---|---|
| 营业账 | FeeId |
原账单号 / 历史账单编号 | biz_charge |
chargeId |
新账单号或业务编号 | mapping-layer |
legacyId、targetId、legacyBizNo、targetBizNo |
账单是迁移核查主线之一 |
| 营业账明细 | Id 或明细主键 |
无统一业务单号时可为空 | biz_charge_detail |
chargeDetailId |
可选 | mapping-layer |
legacyId、targetId、sourceFeeId |
明细至少能挂回主账单 |
| 账户 | AccountId |
原账户编号 | 账户承接对象 | accountId |
新账户编号 | mapping-layer |
legacyId、targetId、legacyBizNo、targetBizNo |
预存余额迁移核查主线 |
| 账户流水 | AccLogId |
原流水号 / 原暂收流水号 | 账户流水承接对象或只读映射 | accountLogId 或映射主键 |
新流水号 | mapping-layer + history-readonly |
legacyId、legacyBizNo、targetId/targetBizNo |
退款、冲正、转预存必须依赖该链路 |
| 收费汇总 | CollectId |
结账批次号 / 汇总编号 | 收费汇总承接对象 | collectId |
新汇总编号 | mapping-layer + history-readonly |
legacyId、targetId、批次号 |
汇总核对主线 |
| 收费小计 | SubtotalId |
原小计编号 | 小计承接对象或只读映射 | subtotalId |
新小计编号 | history-readonly |
legacyId、targetId |
一般不作为主业务单号，但需追溯 |
| 收费明细 | DetailId |
TradeCode / ThirdPartyNum / 第三方流水号 |
交易对象 / 收费明细承接对象 | transactionId 或映射主键 |
新交易流水号 | mapping-layer |
legacyId、legacyBizNo、targetId、targetBizNo |
收费、退款、冲正核查关键链路 |
| 退款账 | RefundId |
原退款单号 | 退款场景映射对象 | 映射主键 | 新调整单号 / 新退款单号 | mapping-layer |
legacyId、targetBizNo |
若新系统无独立退款主键，至少保留新业务单号 |
| 预存退款汇总 | Id |
原申请单号 | 退款申请映射对象 | 映射主键 | 新调整单号 | mapping-layer + history-readonly |
legacyId、legacyBizNo、targetBizNo |
旧申请单是历史审批追溯主线 |
| 预存退款详情 | Id |
原详情单号 | 退款明细映射对象 | 映射主键 | 新明细引用 | mapping-layer + history-readonly |
legacyId、sourceAccountLogId、targetAccountLogId |
重点保留原流水到目标流水关系 |
| 调整减免汇总 | Id |
原调整申请单号 | 调整场景映射对象 | 映射主键 | 新调整单号 | mapping-layer + history-readonly |
legacyId、legacyBizNo、targetBizNo |
金额/水量调整的历史入口 |
| 调整减免明细 | Id |
无统一业务单号 | 调整明细映射对象 | 映射主键 | 新账单引用 / 新明细引用 | mapping-layer |
legacyId、sourceFeeId、targetFeeId |
前后账单链必须保留 |
| 价差调整汇总 | Id |
原价差调整申请单号 | 价差调整映射对象 | 映射主键 | 新调整单号 | mapping-layer + history-readonly |
legacyId、legacyBizNo、targetBizNo |
若不单独在线化，也必须保留申请号映射 |
| 已销调整汇总 | Id |
原已销调整申请单号 | 冲正/调整映射对象 | 映射主键 | 新调整单号 | mapping-layer + history-readonly |
legacyId、legacyBizNo、targetBizNo |
与收费结果链强关联 |
| 坏账汇总 | Id |
原坏账申请单号 | 坏账申请映射对象 | 映射主键 | 新调整单号 / 新申请单号 | mapping-layer + history-readonly |
legacyId、legacyBizNo、targetBizNo |
坏账审批与生效查询主线 |
| 坏账明细 | Id |
无统一业务单号 | 坏账明细映射对象 | 映射主键 | 新账单引用 | mapping-layer |
legacyId、sourceFeeId |
保证坏账记录能追到原账单 |
| 发票主表 | Id / InvoiceInfoId |
InvoiceCode + InvoiceNumber / OrderNo / SerialNo |
biz_invoice |
invoiceId |
新申请单号 / 新受理号 / 新发票号 | mapping-layer |
legacyId、legacyBizNo、targetId、targetBizNo |
发票查询、补打和对账主线 |
| 发票明细 | Id |
无统一业务单号 | 发票明细承接对象或只读映射 | invoiceDetailId |
可选 | mapping-layer + history-readonly |
legacyId、targetId、invoiceId |
明细至少挂回发票主对象 |
| 营业账开票映射 | Id |
账单号 + 发票号组合 | 发票关系映射对象 | 映射主键 | 新账单号 + 新发票号组合 | mapping-layer |
sourceFeeId、targetChargeId、legacyInvoiceNo、targetInvoiceNo |
发票关系迁移验收的核心对象 |
4. 映射记录建议字段
建议统一的标识映射记录至少包含：
| Field | Description |
|---|---|
mappingId |
映射记录主键 |
legacySystem |
原系统标识 |
legacyTable |
旧表名 |
legacyId |
旧主键 |
legacyBizNo |
旧业务单号 / 流水号 / 发票号 |
targetDomain |
新领域名称 |
targetId |
新主键 |
targetBizNo |
新业务单号 / 受理号 / 发票号 |
sourceLegacyId |
源旧主键（用于前后关系对象） |
sourceTargetId |
源新主键 |
mappingStatus |
planned / migrated / verified / failed |
migrationBatchNo |
迁移批次号 |
verifiedAt |
校验时间 |
remark |
备注 |
5. 当前 v1 的直接结论
5.1 必须优先落映射的主线标识
以下标识是迁移最容易断链、也最必须优先保留的：
FeeIdAccLogId- 收费流水号 / 第三方流水号
- 旧调整申请单号
- 旧坏账申请单号
- 发票代码 + 发票号码
- 发票申请单号 / 订单号 / 受理号
5.2 最容易被忽略但必须保留的关系标识
ParentFeeIdContrastFeeIdAccountLogIdTargetAccountLogId- 账单与发票映射关系中的组合标识
这些字段如果不在迁移时显式保留，后续几乎无法恢复“调整前后”“退款前后”“原交易与后续交易”“原账单与新账单”的链路。
5.3 对后续脚本设计的直接约束
迁移脚本设计时，不允许只写“插入新表”逻辑，还必须同步写：
- 标识映射入库逻辑
- 关系标识补链逻辑
- 批次号和映射状态回写逻辑
6. 后续动作
在对象、字段、状态、标识四张矩阵都具备后，下一步建议进入：
- 试迁校验清单
- 差异分类与复迁规则
- 批次化执行与回滚方案