# 往来结算领域对象草案

本文档用于承接第二阶段“往来结算深化第 1 步：业务对象与单据关系定盘”的宿主内结构草案。

本文件不表示这些对象已实现，只表示后续实现建议优先沿此结构推进，避免继续把结算逻辑散落在采购、销售、收付款页面里各自演进。

对象关系定盘见：`docs/PHASE2_SETTLEMENT_DEEPENING_STEP1.md`

形成、核销、预收预付规则定盘见：`docs/PHASE2_SETTLEMENT_DEEPENING_STEP2.md`

主线表结构、字段口径与状态流转设计见：`docs/PHASE2_SETTLEMENT_DEEPENING_STEP3.md`

后台菜单、资源页与核心操作链路承载设计见：`docs/PHASE2_SETTLEMENT_DEEPENING_STEP4.md`

## 一、当前已实现对象

当前宿主内已实现的结算基础对象包括：

- DberpSalesOrder：承载应收汇总字段。
- DberpPurchaseOrder：承载应付汇总字段。
- DberpReceiptOrder：承载基础收款单。
- DberpPaymentOrder：承载基础付款单。
- DberpSettlementEntry：承载结算分录留痕。
- ReceivableService / PayableService：负责同步业务单上的应收应付字段。
- ReceiptService / PaymentService：负责收付款单生效与作废。

当前这些对象仍偏第一阶段，尚不足以完整承载核销、预收预付、对账单与账龄深化。

## 二、建议新增或深化的核心对象

### 1. 结算来源对象

建议模型草案：

- DberpSettlementDocument

建议表草案：

- dberp_settlement_documents

用途：

- 统一承载应收/应付来源，不再直接让后续账龄、对账、核销只依附销售单或采购单字段。

建议核心字段：

- code
- settlement_side
- counterparty_type
- counterparty_id
- document_type
- source_type
- source_id
- source_document_no
- business_time
- due_date
- original_amount
- adjusted_amount
- written_off_amount
- remaining_amount
- status
- source_system
- external_business_type
- external_document_no
- external_reference_id
- external_counterparty_mapping_id
- integration_task_status
- remark

主关系：

- 一条结算来源对象对应一个往来对象。
- 可以被多条核销明细分次冲抵。
- 可由销售确认、销售退货、采购确认、采购退货、结算调整等来源生成或更新。

### 2. 收款单与付款单深化

现有对象保留：

- DberpReceiptOrder
- DberpPaymentOrder

建议后续补充字段：

- business_type
- counterparty_type
- primary_source_type
- primary_source_id
- written_off_amount
- available_amount
- source_system
- external_business_type
- external_document_no
- external_reference_id
- external_counterparty_mapping_id
- integration_task_status

用途：

- 从单笔登记升级为资金对象。
- 同时承载普通收付与预收预付。
- 后续通过核销明细与结算来源对象发生多对多关系。

### 3. 核销单头与核销明细

建议模型草案：

- DberpSettlementWriteOff
- DberpSettlementWriteOffLine

建议表草案：

- dberp_settlement_write_offs
- dberp_settlement_write_off_lines

用途：

- 统一承载核销、反核销操作。
- 支持一笔款核多单、多笔款核一单。

建议单头字段：

- code
- settlement_side
- counterparty_type
- counterparty_id
- status
- business_time
- reversed_from_id
- total_amount
- remark

建议明细字段：

- write_off_id
- settlement_document_id
- payment_document_type
- payment_document_id
- write_off_amount
- sort_order
- snapshot_payload

主关系：

- 单头对多条明细。
- 每条明细对应一笔款项与一条结算来源对象的对应关系。

### 4. 结算调整单

建议模型草案：

- DberpSettlementAdjustment

建议表草案：

- dberp_settlement_adjustments

用途：

- 统一承载应收或应付增加、减少的人工调整。
- 不允许继续直接手改销售单、采购单的应收应付字段。

建议字段：

- code
- settlement_side
- counterparty_type
- counterparty_id
- adjustment_direction
- amount
- reason
- status
- business_time
- source_system
- external_business_type
- external_document_no
- external_reference_id
- remark

### 5. 对账单与快照明细

建议模型草案：

- DberpSettlementStatement
- DberpSettlementStatementItem

建议表草案：

- dberp_settlement_statements
- dberp_settlement_statement_items

用途：

- 承载对象期间内的往来快照。
- 支持确认、打印、导出与后续争议追溯。

建议单头字段：

- code
- settlement_side
- counterparty_type
- counterparty_id
- statement_from
- statement_until
- opening_balance
- period_increase_amount
- period_decrease_amount
- closing_balance
- status
- confirmed_at
- printed_at
- remark

建议明细字段：

- statement_id
- item_type
- source_type
- source_id
- source_document_no
- business_time
- amount
- balance_after
- snapshot_payload
- sort_order

### 6. 账龄分析

建议先作为服务与查询对象，不单独强制建主表：

- SettlementAgingAnalysisService
- SettlementAgingQuery 或等价查询层对象

来源规则：

- 基于 dberp_settlement_documents.remaining_amount > 0
- 起算日期优先 due_date，缺失时回落 business_time
- 默认分桶：未到期、0-30、31-60、61-90、90 以上

## 三、建议补充枚举草案

建议后续增加这些枚举，不直接把英文值暴露给业务页面：

- SettlementDocumentType
- SettlementBusinessType
- SettlementWriteOffStatus
- SettlementAdjustmentDirection
- SettlementStatementStatus
- AgingBucketType

## 四、迁移草案清单

后续可按以下顺序推进迁移：

1. create_dberp_settlement_documents_table
2. alter_dberp_receipt_orders_for_settlement_deepening
3. alter_dberp_payment_orders_for_settlement_deepening
4. create_dberp_settlement_write_off_tables
5. create_dberp_settlement_adjustments_table
6. create_dberp_settlement_statements_tables

说明：

- 现有 dberp_settlement_entries 保留为留痕与查询兼容对象，不急于删除。
- 现有 sales_order / purchase_order 上的 receivable_* / payable_* 字段继续保留，后续由统一服务回写。
- 收款单、付款单对单一业务单的强绑定关系，后续可调整为可空主引用，不在本步直接改表。

## 五、后续实现顺序建议

为控制成本，建议按以下顺序推进：

1. 先落结算来源对象与核销结构。
2. 再深化收款单、付款单与预收预付。
3. 再落结算调整单。
4. 再落对账单对象。
5. 最后补账龄分析与页面收口。

这个顺序的目标是先把返工成本最高的“对象关系”定住，再逐步接页面与查询，而不是先铺很多页面后回头推翻数据结构。

## 六、规则落位提示

在后续真正落库前，建议统一遵守这些规则约束：

- 形成规则：只在可结算业务确认后形成来源对象，不在草稿阶段形成。
- 核销规则：必须通过独立核销单头与核销明细承载，不得仅靠余额回写代替。
- 反核销规则：必须保留原记录，并新增反向留痕，不做物理删除。
- 预收预付规则：与普通收付款共用资金单据对象，但必须分业务类型与余额语义。
- 退货与调整规则：只能通过正式业务对象冲减或修正，不得直接改来源对象净额。

## 七、结构落位提示

在后续真正落库前，建议按第 3 步结构设计把对象拆开承载：

- 应收记录与应付记录分表，不继续只挂在销售单、采购单兼容字段上。
- 收款单与付款单保留现有主表，但扩展文档状态、核销状态、可用金额与主引用字段。
- 核销必须采用单头与明细两层结构。
- 预收预付建议采用余额账户与动作流水两层结构。
- 对账单建议采用主表与明细快照两层结构。
- 审计日志继续复用现有底座，复杂动作另外补快照承载。

## 八、后台承载提示

后续页面落地时，建议按第 4 步文档继续拆分：

- 收款、付款、核销、对账、调整优先走标准 Resource。
- 应收、应付、账龄、往来过程优先走聚合页或分析页。
- 强业务动作优先走独立操作页，不要只依赖列表行按钮。
- RelationManager 必须显式设置中文标题，避免回退英文关系名。