# Matrix: REV-004 旧字段到新字段映射矩阵 v1

## 1. 说明

本矩阵用于在“旧对象 -> 新对象”映射基础上，进一步明确关键字段如何承接、转换和保留。

本版只覆盖迁移中最关键的字段：

- 主键与业务标识
- 账期与客户标识
- 金额 / 水量 / 滞纳金
- 退款 / 冲正 / 坏账相关核心字段
- 账户余额与流水字段
- 发票状态与票据标识字段
- 历史追溯必须保留的流程痕迹字段

## 2. 字段级承接策略说明

- `direct`：可直接映射到现有新字段
- `transform`：需要转换、重算或状态归并
- `mapping-only`：不进入在线主对象，仅写入映射层
- `readonly-retain`：只在历史只读层保留
- `tbd`：当前需要进一步核对 backend 真实字段或实现

## 3. 字段映射矩阵

| 旧表 | 旧字段 | 字段语义 | 新对象 | 新字段 / 承接位置 | 承接策略 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `AT_CHARGES` | `FeeId` | 账单主键 | `ChargeAggregate` | `biz_charge.id` + `legacy_charge_mapping.legacyId` | `direct` + `mapping-only` | 新旧账单主键必须双保留 |
| `AT_CHARGES` | `BillMonth` | 账务年月 | `ChargeAggregate` | `biz_charge.billMonth` | `direct` | 核心账期字段直接承接 |
| `AT_CHARGES` | `CustId` | 客户 ID | `ChargeAggregate` | `biz_charge.custId` | `direct` | 与客户主数据联动 |
| `AT_CHARGES` | `CustCode` | 客户编号 | `ChargeAggregate` | `biz_charge.custCode` | `direct` | 用于查询和迁移验收 |
| `AT_CHARGES` | `BillWater` | 开账水量 | `ChargeAggregate` | `biz_charge.billWater` | `direct` | 核心业务量字段 |
| `AT_CHARGES` | `BillAmount` | 开账金额 | `ChargeAggregate` | `biz_charge.billAmount` | `direct` | 与应收金额共同校验 |
| `AT_CHARGES` | `ExtendedAmount` | 应收金额 | `ChargeAggregate` | `biz_charge.extendedAmount` | `direct` | 迁移金额核对核心字段 |
| `AT_CHARGES` | `LateFee` | 滞纳金 | `ChargeAggregate` | `biz_charge.lateFee` | `direct` | 需与减免对象联动核查 |
| `AT_CHARGES` | `PayState` | 收费状态 | `ChargeAggregate` | `biz_charge.payState` + 状态映射表 | `transform` | 需与新收费状态语义核对 |
| `AT_CHARGES` | `InvoiceState` | 开票状态 | `ChargeAggregate` / `InvoiceRelation` | `biz_charge.invoiceState` + `legacy_invoice_mapping` | `transform` | 账单侧状态与发票主对象需联动校验 |
| `AT_CHARGES` | `ParentFeeId` | 调整原始 FeeId | `CompatibilityMappingRecord` | `legacy_charge_mapping.sourceFeeId` | `mapping-only` | 是迁移后追溯原账单的关键字段 |
| `AT_CHARGES` | `ContrastFeeId` | 对应费用编号 | `CompatibilityMappingRecord` | `legacy_charge_mapping.relatedFeeId` | `mapping-only` | 用于比对调整前后关系 |
| `AT_CHARGES` | `AdjustType` | 调整类型 | `AccountingEvidence` / 映射层 | `tracePayload.adjustType` | `transform` | 当前新模型统一挂场景，不建议原样主表承接 |
| `AT_CHARGES` | `RefundWater` | 退补水量 | `AccountingEvidence` | `tracePayload.refundWater` | `mapping-only` | 与退款/调整场景相关，保留追溯值 |
| `AT_CHARGE_DETAILS` | `FeeId` | 账单外键 | `ChargeAggregate` | `biz_charge_detail.chargeId` | `direct` | 必须保持主明细关系 |
| `AT_CHARGE_DETAILS` | `PriceItemId` | 费用组成 | `ChargeAggregate` | `biz_charge_detail.priceItemId` | `direct` | 核心费用项映射 |
| `AT_CHARGE_DETAILS` | `Water` | 应收水量 | `ChargeAggregate` | `biz_charge_detail.water` | `direct` | 明细层水量 |
| `AT_CHARGE_DETAILS` | `Money` | 明细金额 | `ChargeAggregate` | `biz_charge_detail.money` | `direct` | 明细层金额 |
| `AT_CHARGE_DETAILS` | `InvoicedState` | 明细开票状态 | `InvoiceRelation` / 映射层 | `legacy_invoice_mapping.detailInvoiceState` | `mapping-only` | 明细开票状态优先保留关系层 |
| `CT_ACCOUNTS` | `AccountId` | 账户主键 | `AccountBalance` | `biz_account.id` + `legacy_account_log_mapping.accountLegacyId` | `direct` + `mapping-only` | 账户主键双保留 |
| `CT_ACCOUNTS` | `CustId` | 客户 ID | `AccountBalance` | `biz_account.custId` | `direct` | 账户与客户绑定核心字段 |
| `CT_ACCOUNTS` | `Deposit` | 预存余额 | `AccountBalance` | `biz_account.deposit` | `direct` / `tbd` | 需最终确认 backend 账户表字段命名 |
| `CT_ACCOUNTS` | `UnCheckMoney` | 未到账金额 | `AccountBalance` | `biz_account.unCheckMoney` 或扩展字段 | `tbd` | 需确认新系统是否有对应字段 |
| `CT_ACCOUNTS` | `Overdraft` | 透支额度 | `AccountBalance` | `biz_account.overdraft` 或扩展字段 | `tbd` | 需核实现有表结构 |
| `CT_ACCOUNT_LOGS` | `AccLogId` | 账户流水主键 | `CompatibilityMappingRecord` | `legacy_account_log_mapping.legacyId` | `mapping-only` | 流水主键必须可追溯 |
| `CT_ACCOUNT_LOGS` | `PayDetailId` | 来源编号 | `CompatibilityMappingRecord` | `legacy_account_log_mapping.sourceDetailId` | `mapping-only` | 用于关联收费或退款来源 |
| `CT_ACCOUNT_LOGS` | `AccLogType` | 暂收类型 | `HistoricalReadonlyRecord` | `legacy_account_log_mapping.legacyType` | `readonly-retain` | 新模型当前未显式在线承接该分类 |
| `CT_ACCOUNT_LOGS` | `AccInOut` | 进出标志 | `HistoricalReadonlyRecord` | `legacy_account_log_mapping.inOutFlag` | `readonly-retain` | 作为账户流水查询语义保留 |
| `CT_ACCOUNT_LOGS` | `LastDeposit` | 上次余额 | `HistoricalReadonlyRecord` | `summarySnapshot.lastDeposit` | `readonly-retain` | 用于迁移验收对账 |
| `CT_ACCOUNT_LOGS` | `InOutMoney` | 收支金额 | `HistoricalReadonlyRecord` / `Transaction` | `summarySnapshot.inOutMoney` | `readonly-retain` / `tbd` | 需结合新交易对象最终判定 |
| `CT_ACCOUNT_LOGS` | `Deposit` | 本次余额 | `HistoricalReadonlyRecord` | `summarySnapshot.deposit` | `readonly-retain` | 用于余额核对 |
| `PM_ACCOUNT_RECORD_DETAILS` | `CustId` | 客户 ID | `AccountingEvidence` | `tracePayload.custId` | `mapping-only` | 退款详情应保留客户维度 |
| `PM_ACCOUNT_RECORD_DETAILS` | `RefundDeposit` | 退款金额 | `AccountingEvidence` / `Transaction` | `tracePayload.refundAmount` + 交易对象金额 | `transform` | 核心退款金额，需和新交易金额对齐 |
| `PM_ACCOUNT_RECORD_DETAILS` | `Deposit` | 原预存金额 | `AccountingEvidence` | `tracePayload.originalDeposit` | `mapping-only` | 用于退款前后余额审计 |
| `PM_ACCOUNT_RECORD_DETAILS` | `AccountLogId` | 被调整流水记录 | `CompatibilityMappingRecord` | `legacy_account_log_mapping.sourceAccountLogId` | `mapping-only` | 退款场景断链风险最高字段之一 |
| `PM_ACCOUNT_RECORD_DETAILS` | `TargetAccountLogId` | 目标流水记录 | `CompatibilityMappingRecord` | `legacy_account_log_mapping.targetAccountLogId` | `mapping-only` | 用于转退款 / 转销账链路追溯 |
| `PM_ACCOUNT_RECORD_DETAILS` | `ProcType` | 处理方式 | `AccountingResult` / 映射层 | `tracePayload.procType` | `transform` | 当前新模型只保留统一结果位，原处理方式需保留映射 |
| `PM_AMOUNT_RECORD_DETAILS` | `FeeId` | 原账单 ID | `CompatibilityMappingRecord` | `legacy_charge_mapping.sourceFeeId` | `mapping-only` | 调整前账单引用 |
| `PM_AMOUNT_RECORD_DETAILS` | `NewFeeId` | 新账单 ID | `CompatibilityMappingRecord` | `legacy_charge_mapping.targetFeeId` | `mapping-only` | 调整后账单引用 |
| `PM_AMOUNT_RECORD_DETAILS` | `ExtendedAmount` | 调整前账单金额 | `AccountingEvidence` | `tracePayload.beforeExtendedAmount` | `mapping-only` | 核心差异字段 |
| `PM_AMOUNT_RECORD_DETAILS` | `NewExtendedAmount` | 调整后账单金额 | `AccountingEvidence` | `tracePayload.afterExtendedAmount` | `mapping-only` | 核心差异字段 |
| `PM_AMOUNT_RECORD_DETAILS` | `BillWater` | 调整前开账水量 | `AccountingEvidence` | `tracePayload.beforeBillWater` | `mapping-only` | 水量调整场景核心字段 |
| `PM_AMOUNT_RECORD_DETAILS` | `NewBillWater` | 调整后开账水量 | `AccountingEvidence` | `tracePayload.afterBillWater` | `mapping-only` | 水量调整场景核心字段 |
| `PM_AMOUNT_RECORD_DETAILS` | `Reading` | 原底码 | `AccountingEvidence` | `tracePayload.beforeReading` | `mapping-only` | 旧抄表依据必须保留 |
| `PM_AMOUNT_RECORD_DETAILS` | `NewReading` | 新底码 | `AccountingEvidence` | `tracePayload.afterReading` | `mapping-only` | 调整后依据必须保留 |
| `PM_PAYMENT_RECORD_DETAILS` | `FeeId` | 原账单 ID | `CompatibilityMappingRecord` | `legacy_charge_mapping.sourceFeeId` | `mapping-only` | 已销调整/冲正场景核心引用 |
| `PM_PAYMENT_RECORD_DETAILS` | `NewFeeId` | 新账单 ID | `CompatibilityMappingRecord` | `legacy_charge_mapping.targetFeeId` | `mapping-only` | 如有重构账单必须保留 |
| `PM_PAYMENT_RECORD_DETAILS` | `ActualMoney` | 实收金额 | `Transaction` | `bk_transaction.amount` 或扩展金额字段 | `transform` | 需与原交易金额比对 |
| `PM_PAYMENT_RECORD_DETAILS` | `DeductionAmount` | 抵扣金额 | `AccountingEvidence` | `tracePayload.deductionAmount` | `mapping-only` | 当前新模型未见统一在线字段 |
| `PM_PAYMENT_RECORD_DETAILS` | `AccountLogId` | 被调整流水记录 | `CompatibilityMappingRecord` | `legacy_account_log_mapping.sourceAccountLogId` | `mapping-only` | 冲正场景关键追溯字段 |
| `PM_PAYMENT_RECORD_DETAILS` | `TargetAccountLogId` | 目标流水记录 | `CompatibilityMappingRecord` | `legacy_account_log_mapping.targetAccountLogId` | `mapping-only` | 冲正后目标记录追溯 |
| `PM_KNOTTY_RECORD_DETAILS` | `FeeId` | 账单 ID | `CompatibilityMappingRecord` | `legacy_charge_mapping.sourceFeeId` | `mapping-only` | 坏账与账单关系必须保留 |
| `PM_KNOTTY_RECORD_DETAILS` | `BillMonth` | 账务年月 | `AccountingEvidence` | `tracePayload.billMonth` | `mapping-only` | 用于坏账账龄与核对 |
| `PM_KNOTTY_RECORD_DETAILS` | `ExtendedAmount` | 账单应收金额 | `AccountingEvidence` | `tracePayload.extendedAmount` | `mapping-only` | 与坏账金额核对 |
| `PM_KNOTTY_RECORD_DETAILS` | `ProcType` | 处理方式 | `AccountingResult` / 映射层 | `tracePayload.procType` | `transform` | 坏账类型和结果需映射 |
| `IV_INVOICE_INFOS` | `Id` | 发票主键 | `InvoiceRecord` | `biz_invoice.id` + `legacy_invoice_mapping.legacyInvoiceId` | `direct` + `mapping-only` | 发票主键双保留 |
| `IV_INVOICE_INFOS` | `FeeId` | 费用 ID | `InvoiceRelation` | `legacy_invoice_mapping.sourceFeeId` | `mapping-only` | 账单与发票主关系核心字段 |
| `IV_INVOICE_INFOS` | `SerialNo` | 交易流水号 | `InvoiceRecord` / `Transaction` | `biz_invoice.sysRequestNo` 或关系映射 | `transform` | 需与当前发票协同请求号核对 |
| `IV_INVOICE_INFOS` | `InvoiceState` | 发票状态 | `InvoiceRecord` | `biz_invoice.invoiceState` + 状态映射表 | `transform` | 必做旧状态到新状态映射 |
| `IV_INVOICE_INFOS` | `InvoiceCode` | 发票代码 | `InvoiceRecord` | `biz_invoice.invoiceCode` | `direct` | 核心票据标识 |
| `IV_INVOICE_INFOS` | `InvoiceNumber` | 发票号码 | `InvoiceRecord` | `biz_invoice.invoiceNumber` | `direct` | 核心票据标识 |
| `IV_INVOICE_INFOS` | `InvoiceDate` | 发票日期 | `InvoiceRecord` | `biz_invoice.invoiceDate` | `direct` | 核心票据时间 |
| `IV_INVOICE_INFOS` | `InvoicePath` | 电子票地址 | `InvoiceRecord` | `biz_invoice.fileUrl` 或等价字段 | `transform` | 需核对当前 DO/VO 字段名 |
| `IV_INVOICE_INFOS` | `CndnCode` | 原发票代码 | `InvoiceRecord` | `biz_invoice.originalInvoiceCode` 或扩展字段 | `tbd` | 当前新系统存在类似字段，但需最终核实命名 |
| `IV_INVOICE_INFOS` | `CndnNumber` | 原发票号码 | `InvoiceRecord` | `biz_invoice.originalInvoiceNumber` 或扩展字段 | `tbd` | 与红冲、作废场景强关联 |
| `IV_INVOICE_INFOS` | `LastTryTime` | 最后查询时间 | `InvoiceRecord` | `biz_invoice.lastTryTime` | `direct` | 当前 REV-005 已引入类似重试字段 |
| `IV_INVOICE_INFOS` | `NextTryTime` | 下一次查询时间 | `InvoiceRecord` | `biz_invoice.nextTryTime` | `direct` | 当前 REV-005 已引入类似重试字段 |
| `IV_INVOICE_INFOS` | `TryCount` | 查询次数 | `InvoiceRecord` | `biz_invoice.tryCount` | `direct` | 当前 REV-005 已引入类似字段 |

## 4. 当前 v1 的直接落地建议

### 4.1 可直接进入字段级迁移设计的对象

- `AT_CHARGES`
- `AT_CHARGE_DETAILS`
- `IV_INVOICE_INFOS`

这些对象的核心字段与当前新模型最接近，可以优先进入试迁字段设计。

### 4.2 必须补“映射层字段”的对象

- `CT_ACCOUNT_LOGS`
- `PM_ACCOUNT_RECORD_DETAILS`
- `PM_AMOUNT_RECORD_DETAILS`
- `PM_PAYMENT_RECORD_DETAILS`
- `PM_KNOTTY_RECORD_DETAILS`

这些对象的关键价值不在于在线主字段一一映射，而在于：

- 原账单引用
- 原流水引用
- 前后差异值
- 处理方式
- 原始处理痕迹

### 4.3 当前仍需进一步核实的字段

以下字段建议进入下一轮字段核实清单：

- `CT_ACCOUNTS.Deposit / UnCheckMoney / Overdraft` 在当前 backend 的精确落点
- `PM_PAY_DETAILS.ActualMoney` 到 `bk_transaction*` 的最终字段承接方式
- `IV_INVOICE_INFOS.SerialNo` 与当前发票协同请求号 / 受理号的对应关系
- `IV_INVOICE_INFOS.CndnCode / CndnNumber` 在当前新模型中的正式字段名

## 5. 后续动作

后续建议继续补两张矩阵：

1. `旧状态 -> 新状态` 映射矩阵
2. `新旧标识` 映射矩阵

字段级矩阵完成后，才适合正式设计迁移脚本的字段转换逻辑。