# 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 必须优先落映射的主线标识

以下标识是迁移最容易断链、也最必须优先保留的：

- `FeeId`
- `AccLogId`
- 收费流水号 / 第三方流水号
- 旧调整申请单号
- 旧坏账申请单号
- 发票代码 + 发票号码
- 发票申请单号 / 订单号 / 受理号

### 5.2 最容易被忽略但必须保留的关系标识

- `ParentFeeId`
- `ContrastFeeId`
- `AccountLogId`
- `TargetAccountLogId`
- 账单与发票映射关系中的组合标识

这些字段如果不在迁移时显式保留，后续几乎无法恢复“调整前后”“退款前后”“原交易与后续交易”“原账单与新账单”的链路。

### 5.3 对后续脚本设计的直接约束

迁移脚本设计时，不允许只写“插入新表”逻辑，还必须同步写：

1. 标识映射入库逻辑
2. 关系标识补链逻辑
3. 批次号和映射状态回写逻辑

## 6. 后续动作

在对象、字段、状态、标识四张矩阵都具备后，下一步建议进入：

1. 试迁校验清单
2. 差异分类与复迁规则
3. 批次化执行与回滚方案