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

import cn.iocoder.yudao.framework.common.pojo.CommonResult;
import cn.iocoder.yudao.module.wms.api.inventory.dto.*;

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

/**
 * WMS 库存操作 API 接口
 *
 * 提供给 ERP、MES 等模块调用，实现跨模块库存操作
 *
 * @author 芋道源码
 */
public interface WmsInventoryApi {

    String PREFIX = "/rpc-api/wms/inventory";

    // ==================== 入库操作 ====================

    /**
     * 入库操作
     *
     * @param reqDTO 入库请求
     * @return 入库结果
     */
    CommonResult<WmsReceiptResultDTO> receipt(WmsReceiptReqDTO reqDTO);

    // ==================== 出库操作 ====================

    /**
     * 出库操作
     *
     * @param reqDTO 出库请求
     * @return 出库结果
     */
    CommonResult<WmsShipmentResultDTO> shipment(WmsShipmentReqDTO reqDTO);

    // ==================== 库存预留 ====================

    /**
     * 库存预留（锁库存）
     *
     * @param reqDTO 预留请求
     * @return 预留单号
     */
    CommonResult<String> reserve(WmsReserveReqDTO reqDTO);

    /**
     * 释放库存预留
     *
     * @param reserveNo 预留单号
     */
    CommonResult<Boolean> releaseReserve(String reserveNo);

    /**
     * 使用预留库存（出库时扣减预留）
     *
     * @param reqDTO 使用预留请求
     */
    CommonResult<Boolean> useReserve(WmsUseReserveReqDTO reqDTO);

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

    /**
     * 查询库存
     *
     * @param reqDTO 查询请求
     * @return 库存列表
     */
    CommonResult<List<WmsInventoryRespDTO>> getInventoryList(WmsInventoryQueryReqDTO reqDTO);

    /**
     * 查询可用库存（总库存 - 预留库存）
     *
     * @param skuId SKU 编号
     * @param warehouseId 仓库编号
     * @return 可用库存数量
     */
    CommonResult<BigDecimal> getAvailableQuantity(Long skuId, Long warehouseId);

}