# 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 / SalesOrder
两类订单模型均继承上述三个 Mixin：

- 采购单：`get_direction()` 返回 `1`，`get_counterparty_field_name()` 返回 `supplier`
- 销售单：`get_direction()` 返回 `-1`，`get_counterparty_field_name()` 返回 `customer`
- 其余字段（`merchant/warehouse/operator/status/items`）保持一致，便于服务、序列化与统计逻辑复用

通过 mixin，两个模型天然具备：
- 金额聚合与带方向金额计算
- 统一的业务主体读取接口
- 与库存/财务交互时一致的 `StockFlowService` payload

## 3. 服务层约定

- `business.services` 负责 orchestration，与 API 解耦。审批、作废、触发库存等流程必须先在服务层实现，再暴露给 API。
- 任何涉及库存的逻辑都必须通过 `stock.services.StockFlowService`，不得直接操作库存模型，保持模块边界清晰。
- 红冲/对冲等高级动作应由业务模块提供入口（例如 `PurchaseOrder` 红冲），但最终仍调用库存服务完成实际库存变动。

## 4. 未来演进建议

1. **新增单据**：若未来出现调拨单、退货单等，优先继承 `OrderItemsAggregationMixin + OrderDirectionMixin + OrderCounterpartyMixin`，仅通过 `get_direction()` / `get_counterparty_field_name()` 区别方向与主体，减少重复实现。
2. **审批/状态机**：采购与销售如需共享状态流转，可提炼状态机或 service 层 mixin，而无需在模型层合并。
3. **统计与报表**：财务/库存统计应依赖 `get_signed_total_amount()` / `get_direction()`，确保采购/销售、退货/正向都能通过统一接口处理。
4. **文档同步**：新增单据或服务时必须更新本文件，描述新增模型如何复用 mixin、如何影响下游模块，保持设计透明。

以上约定的目标是：**保持采购单与未来销售单等业务对象的独立性，同时通过 mixin/服务层抽象复用绝大多数公共逻辑**。如需变更此架构（例如重新合并模型或修改核心 mixin 行为），请在评估后更新本文件，明确变化原因与迁移方案。