tangweijie/fujian_water_biz_doc

Fork 0

tangweijie 5f20c5794c docs: add rev-004 legacy finance migration planning artifacts

2026-03-27 10:12:34 +08:00

12 KiB

Raw Blame History

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. 当前仍待补的小项

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

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

12 KiB Raw Blame History

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

1. 目标

2. 第一批次总原则

3. 表级落位总览

4. AT_CHARGES -> biz_charge 细化映射

4.1 主键与标识

4.2 核心业务字段

4.3 状态与结果字段

4.4 关系和追溯字段

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

5. AT_CHARGE_DETAILS -> biz_charge_detail 细化映射

5.1 主键与关系

5.2 核心业务字段

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

6. CT_ACCOUNTS -> biz_account 细化映射

6.1 主键与关系

6.2 核心业务字段

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

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

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

9. 当前仍待补的小项

12 KiB

Raw Blame History

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

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

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

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

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

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