fujian_water_biz_doc/specs/008-rev004-legacy-finance-migration/contracts/rev004-field-mapping-matrix-v1.md

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. 新旧标识 映射矩阵

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