# 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`。

## 使用示例

```python
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` 解析与私有方法，无需触及业务层。

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