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

import cn.iocoder.yudao.module.wms.api.dto.WmsPurchaseInboundReqDTO;
import cn.iocoder.yudao.module.wms.api.dto.WmsSalesOutboundReqDTO;
import cn.iocoder.yudao.module.wms.api.dto.WmsStockDetailRespDTO;
import cn.iocoder.yudao.module.wms.api.dto.WmsStockQueryReqDTO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;

import jakarta.validation.Valid;
import java.math.BigDecimal;
import java.util.List;

/**
 * WMS 库存 API 接口
 *
 * 提供跨模块库存操作能力，包括：
 * - 采购入库/采购退货出库（ERP采购模块调用）
 * - 销售出库/销售退货入库（ERP销售模块调用）
 * - 库存查询（通用查询接口）
 */
@Tag(name = "WMS 库存 API")
public interface WmsStockApi {

    // ========== 采购相关 ==========

    @Operation(summary = "采购入库")
    Long purchaseInbound(@Valid WmsPurchaseInboundReqDTO reqDTO);

    @Operation(summary = "采购退货出库")
    Long purchaseReturnOutbound(@Valid WmsPurchaseInboundReqDTO reqDTO);

    // ========== 销售相关 ==========

    @Operation(summary = "销售出库")
    Long salesOutbound(@Valid WmsSalesOutboundReqDTO reqDTO);

    @Operation(summary = "销售退货入库")
    Long salesReturnInbound(@Valid WmsSalesOutboundReqDTO reqDTO);

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

    @Operation(summary = "查询库存数量")
    @Parameter(name = "itemId", description = "物料ID", required = true)
    @Parameter(name = "warehouseId", description = "仓库ID", required = true)
    BigDecimal getStockQuantity(Long itemId, Long warehouseId);

    @Operation(summary = "查询库存明细")
    WmsStockDetailRespDTO getStockDetail(@Valid WmsStockQueryReqDTO reqDTO);

    @Operation(summary = "查询库存明细列表")
    List<WmsStockDetailRespDTO> getStockDetailList(@Valid WmsStockQueryReqDTO reqDTO);
}