erpnew/docs/STOCK_FLOW_SERVICE.md

StockFlowService 统一出入库服务

背景

随着仓库出入库模式（严谨、宽进宽出、严进严出）增多，业务层（采购、销售等）不应关心底层明细拆分及校验差异。StockFlowService 提供统一的 stock_in / stock_out 方法，将模式分支、字段校验与服务层逻辑封装，保证所有模式均复用已有 create_stock_change_record_* 逻辑。

Items Payload 结构

每个产品条目都支持以下可选字段，由服务内部根据仓库模式挑选所需字段：

字段	说明	适用模式
product_id	产品 ID，必填	所有模式
quantities	严谨模式的数量列表	严谨、严进严出入库、严进严出出库（入库）
value	总数量	宽进宽出
num_of_rolls	单条长度/匹数，默认 1	宽进宽出
consume_detail_ids	被消耗的入库明细 ID 列表	严进严出出库

StockFlowService 根据 warehouse.mode 自动构造对应的服务入参：严谨模式使用 quantity 数组，宽进宽出转换为 {value, unit_count}，严进严出出库转换为 consume_with。

使用示例

service = StockFlowService(merchant=merchant, created_by=user)

# 严谨入库
service.stock_in(
    warehouse_id=warehouse.id,
    source_type=StockChangeSourceEnum.PURCHASE,
    source_id=purchase.id,
    items=[{'product_id': product.id, 'quantities': ['10.5', '5']}],
)

# 宽进宽出出库
service.stock_out(
    warehouse_id=unrestricted.id,
    source_type=StockChangeSourceEnum.SALES,
    source_id=sales.id,
    items=[{'product_id': product.id, 'value': '30.5', 'num_of_rolls': 3}],
)

# 严进严出出库
service.stock_out(
    warehouse_id=restrict_out.id,
    source_type=StockChangeSourceEnum.SALES,
    source_id=sales.id,
    items=[{'product_id': product.id, 'consume_detail_ids': [detail.id]}],
)

方案评价

该构想成功实现了以下目标：

• 隐藏模式细节：业务层仅需关心仓库与产品输入，内部自动匹配严谨/宽进宽出/严进严出逻辑。
• 避免重复实现：底层仍调用现有 create_stock_change_record_with_details、create_stock_change_record_relaxed 等函数，最大化复用。
• 可拓展性：未来新增模式或派生参数，只需扩展 StockFlowService 的 items 解析与私有方法，无需触及业务层。

整体来看，该方案清晰地分离了“业务调用入口”和“模式细节实现”，有助于后续在采购、销售、生产等更高抽象的流程中快速复用库存操作。***