fujian_water_biz_doc/specs/001-rev004-accounting/data-model.md

Data Model: REV-004 账务处理一期

建模原则

• 以逻辑实体 + 物理承接对象双层表达，避免把未确认能力误写为已落地独立表。
• 在线主模型优先复用 biz_charge*、biz_operat_log*、bk_transaction*。
• 审批相关内容仅保留能力位，不展开完整 BPM 流程模型。

实体一：AccountingRequest（账务处理申请）

作用

统一承接 IF-REV-007 的五类场景输入：水量调整、金额调整、退款、冲正、坏账申请。

核心字段

字段	类型	说明
requestNo	String	申请编号/调整业务编号
adjustType	Enum	USAGE / AMOUNT / REFUND / REVERSE / BAD_DEBT
chargeId	Long	目标账单 ID
sourceTradeNo	String	原交易流水号，退款/冲正场景使用
adjustAmount	Decimal	调整金额
adjustUsage	Decimal	调整水量
reasonCode	String	调整原因编码
remark	String	调整说明
attachmentList	Array	依据附件
operatorId	Long	操作人 ID
requestedAt	DateTime	发起时间

校验规则

• chargeId、adjustType、reasonCode、operatorId 必填。
• REFUND / REVERSE 场景必须具备 sourceTradeNo。
• adjustAmount 与 adjustUsage 按场景二选一或组合使用，不允许无意义空提交。

状态

submitted → accepted / rejected → processed / failed

实体二：AccountingResult（账务处理结果）

作用

统一承接处理结果、回写结果与是否需要审批。

核心字段

字段	类型	说明
adjustmentNo	String	调整业务编号
chargeId	Long	目标账单 ID
resultStatus	Enum	SUCCESS / PENDING_APPROVAL / FAIL
writeBackStatus	Enum	SUCCESS / IGNORE_REPEAT / FAIL
approvalRequired	Boolean	是否进入审批
msg	String	处理说明
processedAt	DateTime	处理时间

状态关系

• resultStatus 表示业务处理结果。
• writeBackStatus 表示账单回写结果。
• approvalRequired=true 时允许 resultStatus=PENDING_APPROVAL。

实体三：ChargeAggregate（账单聚合对象）

作用

作为 REV-004 调整、退款、冲正的主要业务承接对象。

物理承接

• biz_charge
• biz_charge_detail

核心字段

字段	来源	说明
chargeId	biz_charge.id	账单主键
chargeStatus	biz_charge	账单状态
receivableAmount	biz_charge / biz_charge_detail	应收金额
paidAmount	业务汇总	已收金额
remainAmount	业务汇总	剩余待支付金额
detailItems	biz_charge_detail	费用明细集合

关键关系

• 1 个 ChargeAggregate 对应多条 biz_charge_detail。
• 1 个 AccountingRequest 必须定位到 1 个 ChargeAggregate。

实体四：Transaction（原交易流水）

作用

为退款、冲正等场景提供原交易事实依据。

物理承接

• bk_transaction
• 关联扩展：bk_transaction_callback（异步回调结果核对）
• 关联扩展：bk_transaction_exception（异常处理状态核对）

核心字段

字段	说明
tradeNo	渠道交易流水号
tradeStatus	原交易状态
tradeAmount	原交易金额
channelCode	渠道编码
occurredAt	交易发生时间

关键规则

• REFUND / REVERSE 必须关联 tradeNo。
• 原交易状态必须满足“可退款/可冲正”业务前提。
• 原交易校验应同时覆盖交易主状态、回调结果与异常处理状态，不得只校验交易主表存在性。

实体五：OperationLog（操作留痕）

作用

记录账务处理前后变化、处理依据与责任归属。

物理承接

• biz_operat_log
• biz_operat_log_detail

核心字段

字段	说明
bizType	业务类型
bizId	业务对象 ID
operateUser	操作人
operateTime	操作时间
remark	处理说明
beforeValue	调整前值
afterValue	调整后值
fieldName	字段级差异项

关键规则

• 所有 REV-004 一期场景都必须写入主日志。
• 涉及金额/水量/状态变化时应写入字段级差异明细。

实体六：AccountingEvidence（处理依据）

作用

统一描述原账单、原交易、附件、文字说明等处理依据。

核心字段

字段	说明
evidenceType	原账单 / 原交易 / 附件 / 说明
sourceRef	依据引用标识
snapshotRef	快照引用
attachmentList	附件集合

说明

该实体是逻辑约束，不要求本阶段新增物理表；由既有对象引用、附件系统与日志共同承接。

关系总览

AccountingRequest --> ChargeAggregate
AccountingRequest --> Transaction (REFUND/REVERSE only)
AccountingRequest --> AccountingEvidence
AccountingRequest --> AccountingResult
AccountingRequest --> OperationLog
ChargeAggregate --> biz_charge_detail (1:N)
OperationLog --> biz_operat_log_detail (1:N)

状态与边界说明

• 一期仅保留审批能力位，不定义完整审批状态机。
• 旧系统精细账务对象如预存退款明细、价差调整明细、分账调整明细等，不作为一期新增实体表；仅保留业务场景、历史只读与日志承接口径。