package cn.iocoder.yudao.module.wms.api.stock;

import cn.iocoder.yudao.module.wms.api.stock.dto.*;

import java.math.BigDecimal;
import java.util.List;
import java.util.Map;

/**
 * WMS 库存服务 API 接口
 *
 * 提供给 ERP、MES 等模块调用，实现跨模块库存操作
 * 使用统一的物料ID（md_item.id）
 *
 * @author 芋道源码
 */
public interface WmsStockApi {

    // ==================== 库存记录操作 ====================

    /**
     * 创建库存记录（入库）
     *
     * @param dto 库存记录创建请求
     * @return 库存记录ID
     */
    Long createStockRecord(StockRecordCreateDTO dto);

    /**
     * 批量创建库存记录
     *
     * @param dtoList 库存记录创建请求列表
     * @return 库存记录ID列表
     */
    List<Long> createStockRecordBatch(List<StockRecordCreateDTO> dtoList);

    // ==================== 库存锁定 ====================

    /**
     * 锁定库存
     *
     * @param itemId 物料ID
     * @param warehouseId 仓库ID
     * @param quantity 锁定数量
     * @return 锁定单号
     */
    String lockStock(Long itemId, Long warehouseId, BigDecimal quantity);

    /**
     * 批量锁定库存
     *
     * @param itemId 物料ID
     * @param warehouseId 仓库ID
     * @param quantity 锁定数量
     * @param bizType 业务类型
     * @param bizId 业务单据ID
     * @return 锁定单号
     */
    String lockStockWithBiz(Long itemId, Long warehouseId, BigDecimal quantity, Integer bizType, Long bizId);

    /**
     * 解锁库存
     *
     * @param lockNo 锁定单号
     */
    void unlockStock(String lockNo);

    // ==================== 库存查询 ====================

    /**
     * 查询可用库存
     *
     * @param itemId 物料ID
     * @param warehouseId 仓库ID
     * @return 可用库存数量
     */
    BigDecimal getAvailableStock(Long itemId, Long warehouseId);

    /**
     * 批量查询库存
     *
     * @param itemIds 物料ID列表
     * @param warehouseId 仓库ID
     * @return 物料ID -> 可用库存数量
     */
    Map<Long, BigDecimal> getAvailableStockMap(List<Long> itemIds, Long warehouseId);

    /**
     * 查询所有仓库的库存
     *
     * @param itemId 物料ID
     * @return 仓库ID -> 可用库存数量
     */
    Map<Long, BigDecimal> getAvailableStockByWarehouse(Long itemId);

    // ==================== 库存校验 ====================

    /**
     * 校验库存充足
     *
     * @param itemId 物料ID
     * @param warehouseId 仓库ID
     * @param quantity 需求数量
     * @return true=充足, false=不足
     */
    boolean validateStockEnough(Long itemId, Long warehouseId, BigDecimal quantity);

    /**
     * 校验库存充足（不足时抛出异常）
     *
     * @param itemId 物料ID
     * @param warehouseId 仓库ID
     * @param quantity 需求数量
     * @throws cn.iocoder.yudao.framework.common.exception.ServiceException 库存不足时抛出异常
     */
    void checkStockEnough(Long itemId, Long warehouseId, BigDecimal quantity);

    // ==================== 库存扣减 ====================

    /**
     * 扣减库存（出库）
     *
     * @param itemId 物料ID
     * @param warehouseId 仓库ID
     * @param quantity 扣减数量
     * @param bizType 业务类型
     * @param bizId 业务单据ID
     * @param bizNo 业务单据号
     */
    void deductStock(Long itemId, Long warehouseId, BigDecimal quantity, Integer bizType, Long bizId, String bizNo);

    /**
     * 增加库存（入库）
     *
     * @param itemId 物料ID
     * @param warehouseId 仓库ID
     * @param quantity 增加数量
     * @param bizType 业务类型
     * @param bizId 业务单据ID
     * @param bizNo 业务单据号
     */
    void addStock(Long itemId, Long warehouseId, BigDecimal quantity, Integer bizType, Long bizId, String bizNo);

}