# Matrix: REV-004 第一批次真实迁移映射矩阵细化版 v1

## 1. 目标

本矩阵用于把第一批次迁移对象细化到“可以直接指导脚本设计”的程度。

第一批次范围限定为：

- `AT_CHARGES`
- `AT_CHARGE_DETAILS`
- `CT_ACCOUNTS`

本版重点不是覆盖旧表所有字段，而是先锁定：

- 主键与核心业务标识
- 核心业务字段
- 关键状态字段
- 必要关系字段
- 映射落库要求

## 2. 第一批次总原则

- 账单主明细和账户对象属于在线主模型优先承接范围。
- 旧主键和旧业务标识必须进入映射层，不允许只保留新主键。
- 当前不能稳定落入主表的旧字段，先进入映射层或历史只读层，不强行污染主对象。
- 第一批次试迁后必须能回答：原账单是谁、原账户是谁、新对象是谁、金额和状态是否一致。

## 3. 表级落位总览

| 旧表 | 目标主对象 | 目标映射对象 | 当前 backend 证据 | 当前结论 |
| --- | --- | --- | --- | --- |
| `AT_CHARGES` | `biz_charge` | `legacy_charge_mapping` | `ChargeDO.java` | 可直接作为第一批次主对象 |
| `AT_CHARGE_DETAILS` | `biz_charge_detail` | `legacy_charge_detail_mapping` | `ChargeDetailDO.java` | 可直接作为第一批次明细对象 |
| `CT_ACCOUNTS` | `biz_account` | `legacy_account_mapping` | `AccountDO.java` | 可直接作为第一批次账户对象 |

## 4. `AT_CHARGES -> biz_charge` 细化映射

### 4.1 主键与标识

| 旧字段 | 新字段/位置 | 策略 | 备注 |
| --- | --- | --- | --- |
| `FeeId` | `biz_charge.id` | 直接承接或保留旧值映射 | 是否复用旧主键需由迁移脚本策略决定，但映射表必须保留 |
| `FeeId` | `legacy_charge_mapping.legacyId` | 必填 | 新旧账单主线标识 |
| 原账单号（如存在） | `legacy_charge_mapping.legacyBizNo` | 必填 | 若旧表无独立账单号，可用 `FeeId` 兼任 |
| 新账单号（如生成） | `legacy_charge_mapping.targetBizNo` | 选填 | 若新系统仅用主键，可暂为空 |

### 4.2 核心业务字段

| 旧字段 | 新字段 | 策略 | 备注 |
| --- | --- | --- | --- |
| `RecordId` | `recordId` | 直接映射 | 抄表记录引用 |
| `BillMonth` | `billMonth` | 直接映射 | 核心账期字段 |
| `OrgId` | `deptId` | 转换映射 | 旧站点字段名与新部门字段名不同 |
| `BookId` | `bookId` | 直接映射 | 册本引用 |
| `BookSortIndex` | `bookSortIndex` | 直接映射 | 册内顺序 |
| `CustId` | `custId` | 直接映射 | 客户主键 |
| `CustCode` | `custCode` | 直接映射 | 客户编号 |
| `CustName` | `custName` | 直接映射 | 客户名称 |
| `CustAddress` | `custAddress` | 直接映射 | 客户地址 |
| `Populine` | `population` | 字段改名映射 | 旧字段拼写与新字段不同 |
| `PayMethod` | `payMethod` | 直接/枚举转换 | 需核对枚举值是否一致 |
| `LastReading` | `lastReading` | 类型转换映射 | 旧 `int` 到新 `BigDecimal` |
| `LastChildReading` | `lastChildReading` | 类型转换映射 | 同上 |
| `LastReadWater` | `lastReadWater` | 类型转换映射 | 同上 |
| `LastReadDate` | `lastReadDate` | 直接映射 | 时间字段 |
| `LastReadStateId` | `lastReadStateId` | 直接映射 | 状态引用 |
| `Reading` | `reading` | 类型转换映射 | 旧 `int` 到新 `BigDecimal` |
| `ChildReading` | `childReading` | 类型转换映射 | 同上 |
| `ReadWater` | `readWater` | 类型转换映射 | 同上 |
| `ReadDate` | `readDate` | 直接映射 | 时间字段 |
| `ReadStateId` | `readStateId` | 直接映射 | 状态引用 |
| `ReadTimes` | `readTimes` | 直接映射 | 抄次 |
| `MeterReaderId` | `meterReaderId` | 直接映射 | 抄表员 |
| `PriceListId` | `adjustmentSnapCode` 或扩展映射 | 暂按转换映射 | 旧调价号是 `int`，新对象用 `String adjustmentSnapCode` |
| `PriceCode` | `priceTemplateCode` | 转换映射 | 旧用水性质编码映射到新价格模板编码 |
| `TotalWater` | `totalWater` | 类型转换映射 | 旧 `int` 到新 `BigDecimal` |
| `ReplaceWater` | `replaceWater` | 类型转换映射 | 同上 |
| `BillWater` | `billWater` | 类型转换映射 | 同上 |
| `BillAmount` | `billAmount` | 直接映射 | 金额核心字段 |
| `ExtendedAmount` | `extendedAmount` | 直接映射 | 应收金额核心字段 |
| `LastChange` | `lastChange` | 直接映射 | 零头字段 |
| `Change` | `change` | 直接映射 | 零头字段 |
| `BillerId` | `billerId` | 直接映射 | 开账人 |
| `BillDate` | `billDate` | 直接映射 | 开账时间 |
| `LateFeeBeginDate` | `lateFeeBeginDate` | 直接映射 | 滞纳金起算日 |
| `LateFee` | `lateFee` | 直接映射 | 核心金额字段 |
| `CashierId` | `cashierId` | 直接映射 | 收费员 |
| `PayDate` | `payDate` | 直接映射 | 收费时间 |
| `CheckoutDate` | `checkoutDate` | 直接映射 | 结账时间 |
| `ChargeMethod` | `chargeMethod` | 直接/枚举转换 | 需核对枚举 |
| `ChargeWay` | `chargeWay` | 直接/枚举转换 | 需核对枚举 |

### 4.3 状态与结果字段

| 旧字段 | 新字段/位置 | 策略 | 备注 |
| --- | --- | --- | --- |
| `PayState` | `biz_charge.payState` | 状态转换 | 必须按状态矩阵归并 |
| `FeeState` | `biz_charge.feeState` 或 `legacyState` | 状态转换 + 保留旧值 | 若新字段无法完整表达，保留旧值 |
| `InvoiceState` | `biz_charge.invoiceState` + 发票映射层 | 状态转换 | 需与发票主对象一致 |
| `InvoiceError` | `biz_charge.invoiceError` | 直接映射 | 开票失败原因 |
| `PrintState` | `biz_charge.printState` | 直接映射 | 打印状态 |
| `PrintTimes` | `biz_charge.printTimes` | 直接映射 | 打印次数 |
| `LockNum` | `biz_charge.lockNum` | 直接映射 | 锁定编号 |
| `LockoutEndTime` | `biz_charge.lockoutEndTime` | 直接映射 | 锁定时间 |

### 4.4 关系和追溯字段

| 旧字段 | 新字段/位置 | 策略 | 备注 |
| --- | --- | --- | --- |
| `AdjustType` | `biz_charge.adjustType` + `tracePayload.adjustType` | 直接映射 + 追溯保留 | 当前新对象已有该字段 |
| `ContrastFeeId` | `biz_charge.contrastFeeId` + `legacy_charge_mapping.relatedFeeId` | 直接映射 + 映射保留 | 调整前后关系 |
| `ParentFeeId` | `legacy_charge_mapping.sourceFeeId` | 追溯保留 | 新 `ChargeDO` 未见同名字段，必须进映射层 |
| `InvoiceCode` | `biz_charge.invoiceCode` | 直接映射 | 发票代码 |
| `InvoiceDate` | `biz_charge.invoiceDate` | 直接映射 | 开票日期 |
| `InvoiceNumber` | `biz_charge.invoiceNumber` | 直接映射 | 发票号码 |
| `RefundWater` | `biz_charge.refundWater` + `tracePayload.refundWater` | 直接映射 + 追溯保留 | 当前新对象已有该字段 |

### 4.5 第一批次对 `AT_CHARGES` 的直接建议

- `AT_CHARGES` 可直接作为第一批次最优先迁移主表。
- 需要额外设计：
  - `PriceListId -> adjustmentSnapCode`
  - `PriceCode -> priceTemplateCode`
  - `ParentFeeId` 的映射层保留
  - `PayState / FeeState / InvoiceState` 的状态归并规则

## 5. `AT_CHARGE_DETAILS -> biz_charge_detail` 细化映射

### 5.1 主键与关系

| 旧字段 | 新字段/位置 | 策略 | 备注 |
| --- | --- | --- | --- |
| 明细主键 `Id` | `biz_charge_detail.id` | 直接承接或映射保留 | 视脚本主键策略决定 |
| `FeeId` | `biz_charge_detail.feeId` | 直接映射 | 必须保持主明细关系 |
| 明细主键 | `legacy_charge_detail_mapping.legacyId` | 必填 | 保留旧明细主键 |

### 5.2 核心业务字段

| 旧字段 | 新字段 | 策略 | 备注 |
| --- | --- | --- | --- |
| `PriceListId` | `adjustmentSnapCode` | 转换映射 | 与主账一致，需要调价号转换 |
| `PriceCode` | `priceTemplateCode` | 转换映射 | 与主账一致 |
| `PriceDetailId` | `costAdjustmentId` 或扩展字段 | `tbd` | 需进一步确认新字段语义是否等价 |
| `PriceItemId` | `costComponentCode` | 转换映射 | 旧费用组成 ID 到新费用组成编码 |
| `CalcMode` | `calcMode` | 直接映射 | 计费方式 |
| `LevelType` | `levelType` | 直接映射 | 阶梯模式 |
| `LevelIndex` | `levelIndex` | 直接映射 | 阶梯级别 |
| `StartMonth` | `startMonth` | 直接映射 | 开始月份 |
| `EndMonth` | `endMonth` | 直接映射 | 结束月份 |
| `StartWater` | `startWater` | 类型转换映射 | 旧 `int` 到新 `BigDecimal` |
| `EndWater` | `endWater` | 类型转换映射 | 同上 |
| `SettleMethod` | `settleMethod` | 直接映射 | 分摊方式 |
| `SettleValues` | `settleValues` | 类型转换映射 | 旧 `float` 到新 `BigDecimal` |
| `Price` | `price` | 直接映射 | 单价 |
| `Water` | `water` | 类型转换映射 | 应收水量 |
| `DiscountWater` | `discountWater` | 类型转换映射 | 优惠水量 |
| `WaterNum` | `waterNum` | 直接映射 | 水量系数 |
| `Money` | `money` | 直接映射 | 明细金额 |
| `State` | `state` | 状态转换 | 明细状态需核对枚举 |
| `IsPreferential` | `isPreferential` | 直接映射 | 是否优惠 |
| `BasicNumber` | `basicNumber` | 直接映射 | 基数 |
| `InvoicedState` | `invoicedState` | 状态转换 | 开票状态 |
| `DiscountMoney` | `discountMoney` | 直接映射 | 优惠金额 |
| `OriginalMoney` | `originalMoney` | 直接映射 | 优惠前金额 |
| `IsWaterOver` | `isWaterOver` | 直接映射 | 是否超计划 |
| `ItemInvoiceError` | `itemInvoiceError` | 直接映射 | 明细开票错误 |
| `ItemInvoiceState` | `itemInvoiceState` | 直接映射 | 明细开票状态 |
| `ItemInvoiceType` | `itemInvoiceType` | 直接映射 | 明细开票类型 |

### 5.3 第一批次对 `AT_CHARGE_DETAILS` 的直接建议

- 明细对象整体与 `ChargeDetailDO` 对应度较高，可以直接进入第一批次。
- 主要需要额外确认的点：
  - `PriceDetailId -> costAdjustmentId` 是否语义等价
  - `PriceItemId -> costComponentCode` 的编码转换规则

## 6. `CT_ACCOUNTS -> biz_account` 细化映射

### 6.1 主键与关系

| 旧字段 | 新字段/位置 | 策略 | 备注 |
| --- | --- | --- | --- |
| `AccountId` | `biz_account.id` | 直接承接或映射保留 | 是否复用旧主键由脚本策略决定 |
| `AccountId` | `legacy_account_mapping.legacyId` | 必填 | 账户迁移主线 |
| 原账户编号 | `legacy_account_mapping.legacyBizNo` | 选填 | 若旧系统无独立业务账户号，可用主键兼任 |
| `CustId` | `biz_account.custId` | 直接映射 | 账户与客户关系核心字段 |

### 6.2 核心业务字段

| 旧字段 | 新字段 | 策略 | 备注 |
| --- | --- | --- | --- |
| `Deposit` | `deposit` | 直接映射 | 预存余额 |
| `UnCheckMoney` | `uncheckMoney` | 直接映射 | 未到账金额 |
| `Overdraft` | `overdraft` | 直接映射 | 透支额度 |
| `AccountState` | `status` | 状态转换 | 旧账户状态需与新 `status` 枚举核对 |

### 6.3 第一批次对 `CT_ACCOUNTS` 的直接建议

- `CT_ACCOUNTS` 与 `AccountDO` 的字段匹配度较高，可以直接进入第一批次。
- 关键点不在字段缺失，而在于：
  - `AccountState -> status` 的枚举值核对
  - 账户与客户主数据的一致性校验

## 7. 第一批次试迁时必须同步落库的映射对象

建议至少同时生成以下映射记录：

| 映射对象 | 作用 |
| --- | --- |
| `legacy_charge_mapping` | 保留旧账单到新账单关系 |
| `legacy_charge_detail_mapping` | 保留旧账单明细到新明细关系 |
| `legacy_account_mapping` | 保留旧账户到新账户关系 |

每条映射记录最少包括：

- `legacyTable`
- `legacyId`
- `legacyBizNo`
- `targetDomain`
- `targetId`
- `targetBizNo`
- `migrationBatchNo`
- `mappingStatus`

## 8. 第一批次最小脚本出口条件

在进入实际试迁脚本开发前，第一批次至少应满足：

- `AT_CHARGES` 字段映射规则已稳定
- `AT_CHARGE_DETAILS` 字段映射规则已稳定
- `CT_ACCOUNTS` 字段映射规则已稳定
- 三类主对象的状态映射规则已确认
- 三类主对象的标识映射结构已确认

## 9. 当前仍待补的小项

本版之后，第一批次还建议继续补两项：

1. `PriceListId / PriceCode / PriceItemId` 的编码转换字典
2. `PayState / FeeState / AccountState` 的枚举值对照表