package com.erp.inventory.service;

import com.erp.inventory.dto.*;
import com.erp.inventory.entity.Stock;
import com.erp.inventory.entity.StockLog;

import java.util.List;
import com.erp.common.core.model.PageResponse;

/**
 * 库存盘点服务接口
 * 对应PHP StockController + StockService的盘点相关功能
 * 
 * 功能覆盖：
 * 1. 库存列表查询（分页、搜索、筛选）
 * 2. 库存详情查询
 * 3. 库存盘点调整（盘点校准）
 * 4. 手动入库/出库
 * 5. 残次品入库
 * 6. 库存流水查询
 * 7. 预警阈值管理
 * 8. 库存预警列表
 * 9. 库存一致性检查
 * 
 * @author ERP Migration
 */
public interface StockCheckService {

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

    /**
     * 库存列表（分页，支持搜索、仓库筛选、预警筛选）
     * 对应PHP StockController::index
     */
    PageResponse<StockListItemDTO> listStocks(StockQueryDTO query);

    /**
     * 库存详情（按仓库+SKU）
     * 对应PHP StockController::show
     */
    StockDetailDTO getStockDetail(String skuCode, Long warehouseId);

    // ==================== 库存盘点调整 ====================

    /**
     * 库存盘点校准（手动调整库存）
     * 对应PHP StockController::adjust
     * 
     * @param request 调整请求
     * @return 调整后的库存信息
     */
    StockAdjustResponse adjustStock(StockAdjustRequest request);

    // ==================== 手动入库/出库 ====================

    /**
     * 手动入库
     * 对应PHP StockController::manualInbound
     */
    Stock adjustForInbound(StockInboundRequest request);

    /**
     * 手动出库
     * 对应PHP StockController::manualOutbound
     */
    Stock adjustForOutbound(StockOutboundRequest request);

    /**
     * 残次品入库
     * 对应PHP StockController::defectiveInbound
     */
    void defectiveInbound(DefectiveInboundRequest request);

    // ==================== 库存流水 ====================

    /**
     * 库存流水列表
     * 对应PHP StockController::logs
     */
    PageResponse<StockLogDTO> listStockLogs(StockLogQueryDTO query);

    // ==================== 预警管理 ====================

    /**
     * 更新库存预警阈值
     * 对应PHP StockController::updateThreshold
     */
    Stock updateThreshold(UpdateThresholdRequest request);

    /**
     * 库存预警列表
     * 对应PHP StockController::warning
     */
    PageResponse<StockWarningDTO> listStockWarnings(Long warehouseId, Integer page, Integer limit);

    // ==================== 锁定/解锁 ====================

    /**
     * 锁定库存（审核订单时调用）
     * 对应PHP StockService::lock
     */
    Stock lockStock(String skuCode, Long warehouseId, Integer quantity, Long orderId);

    /**
     * 解锁库存（驳回订单时调用）
     * 对应PHP StockService::unlockStock
     */
    Stock unlockStock(String skuCode, Long warehouseId, Integer quantity, Long orderId);

    /**
     * 检查可用库存
     * 对应PHP StockService::checkStock
     */
    Integer checkAvailableStock(String skuCode, Long warehouseId);

    // ==================== 预扣库存（两阶段模式） ====================

    /**
     * 预扣库存（冻结库存，两阶段模式第一阶段）
     * 对应PHP StockService::reserveStock
     */
    StockReserveResponse reserveStock(String skuCode, Long warehouseId, Integer quantity, Long orderId);

    /**
     * 确认预扣（两阶段模式第二阶段：确认出库）
     * 对应PHP StockService::confirmReserve
     */
    Stock confirmReserve(String reserveToken, Long orderId, String trackingNo);

    /**
     * 取消预扣（两阶段模式第二阶段：取消释放）
     * 对应PHP StockService::cancelReserve
     */
    Stock cancelReserve(String reserveToken, Long orderId);

    // ==================== 发货出库 ====================

    /**
     * 发货出库（扣减锁定库存）
     * 对应PHP StockService::ship
     */
    Stock shipStock(String skuCode, Long warehouseId, Integer quantity, Long orderId, String trackingNo);

    // ==================== 数据一致性检查 ====================

    /**
     * 库存数据一致性检查与修复
     * 对应PHP DataConsistencyService::checkAndFixStockConsistency
     */
    ConsistencyCheckResult checkAndFixStockConsistency();

    /**
     * 内部：计算指定SKU在仓库的实际库存（基于库存日志）
     */
    Integer calculateActualQuantity(String skuCode, Long warehouseId);

    // ==================== 辅助方法 ====================

    /**
     * 获取或创建库存记录
     */
    Stock getOrCreateStock(String skuCode, Long warehouseId);

    /**
     * 创建库存流水记录
     */
    StockLog createStockLog(String skuCode, Long warehouseId, Integer changeQuantity, 
                           String type, Long orderId, String remark);

    // ==================== 响应DTO ====================

    /**
     * 预扣库存响应
     */
    record StockReserveResponse(Stock stock, String reserveToken) {}

    /**
     * 一致性检查结果
     */
    record ConsistencyCheckResult(int checked, int fixed, List<String> errors) {}
}
