erpnew/business/ARCHITECTURE.md

business 模块结构与设计说明

本文档记录业务模块当前的结构、关键约定以及未来演进需要遵循的决策背景，防止在迭代中遗失设计意图。

1. 模块职责

business 负责“业务单据”领域，目前包含采购单（PurchaseOrder）与销售单（SalesOrder），同时保留可扩展至退货单等更多对象的通用框架。核心职责：

• 聚合与校验业务明细数据
• 通过服务层触发库存（stock）、财务等下游模块
• 统一处理审批、作废等状态流转

2. 模型抽象

2.1 OrderItemsAggregationMixin

封装订单明细聚合逻辑，默认访问 items 关联，可通过 order_items_accessor 指定其他关联名。提供：

• get_total_amount()
• get_total_quantity()
• get_total_diff_quantity()

这些方法仅关心明细结构，不关心订单方向。

2.2 OrderDirectionMixin

用于获取带方向的金额，约定：

• get_direction() 返回 1（正向/入库）或 -1（负向/出库）
• get_signed_total_amount() 在内部调用 get_total_amount() 并乘以方向

任何需要“正负金额”的业务（财务统计、库存红冲）都应依赖此能力，而不是重复编写正负逻辑。

2.3 OrderCounterpartyMixin

对外暴露统一的 get_counterparty() 接口，通过 get_counterparty_field_name()（或 counterparty_field_name 属性）确定具体业务主体字段。这样采购单/销售单分别返回 Supplier 与 Customer，但调用方只需面对一个接口。

2.4 订单类型

当前业务对象覆盖：

• PurchaseOrder（采购单）：direction=1，counterparty=supplier，含库存明细。
• SalesOrder（销售单）：direction=-1，counterparty=customer，含库存明细；严进严出模式需记录 consume_detail_ids。
• PurchaseReturnOrder（采购退货单）：direction=-1，counterparty=supplier，仓库出库、供应商欠款减少，可选关联原采购单。
• SalesReturnOrder（销售退货单）：direction=1，counterparty=customer，仓库入库、客户欠款减少，可选关联原销售单。
• PaymentOrder（付款单）：direction=-1，counterparty=supplier，仅金额字段，不触发库存。
• ReceiptOrder（收款单）：direction=-1，counterparty=customer，仅金额字段，不触发库存。
• SupplierBalance / CustomerBalance：实时维护供应商应付、客户应收余额，所有审批通过的带金额单据都会写入，供查询接口和报表使用。
• BalanceChangeRecord（余额变动记录）：仿照 stock.StockSnapshot 的“流水 + 快照”模式，记录每一次余额写入的来源、方向、前后余额与可能的冲抵关系，为财务审计与未来的红冲能力提供依据。

通过 mixin，所有单据都具备：

• 统一的金额聚合与方向计算（资金/库存可共用 get_signed_total_amount()）
• 一致的业务主体接口（供应商/客户）
• 可扩展的服务与序列化模式（有无库存由具体模型决定）

3. 服务层约定

• business.services 负责 orchestration，与 API 解耦。审批、作废、触发库存等流程必须先在服务层实现，再暴露给 API。
• 作废统一实现：_cancel_order_impl() 是所有单据作废的单一入口，通过参数化 order_model_cls / approved_status / cancelled_status / stock_source_type 适配不同模型，将 APPROVED 检查统一在 select_for_update 锁内完成。
• 任何涉及库存的逻辑都必须通过 stock.services.StockFlowService，不得直接操作库存模型，保持模块边界清晰。
• 红冲/对冲等高级动作应由业务模块提供入口（例如 PurchaseOrder 红冲），但最终仍调用库存服务完成实际库存变动。

4. 未来演进建议

1. 新增单据：若未来出现调拨单、退货单或更多资金类单据，优先复用 OrderDirectionMixin + OrderCounterpartyMixin（如有明细再叠加 OrderItemsAggregationMixin），仅通过 get_direction() / get_counterparty_field_name() 区别方向与主体，减少重复实现。
2. 审批/状态机：作废逻辑已通过 _cancel_order_impl() 统一实现，新增单据的作废只需委托该函数并传入对应参数，无需复制逻辑。
3. 统计与报表：财务/库存统计应依赖 get_signed_total_amount() / get_direction()，确保采购/销售、退货/正向都能通过统一接口处理。
4. 余额审计：任何会写入 Supplier/CustomerBalance 的流程必须通过 BalanceService，以便自动生成 BalanceChangeRecord。审批通过后禁止作废，若未来需要冲销，必须新建红冲记录并维护 offset_to/offset_id 链路。
5. 文档同步：新增单据或服务时必须更新本文件，描述新增模型如何复用 mixin、如何影响下游模块，保持设计透明。

以上约定的目标是：保持各类业务单据的独立性，同时通过 mixin/服务层抽象复用绝大多数公共逻辑。如需变更此架构，请在评估后更新本文件，说明原因与迁移方案。