using HoneyBox.Model.Entities;

namespace HoneyBox.Core.Interfaces;

/// <summary>
/// 库存管理接口
/// </summary>
public interface IInventoryManager
{
    /// <summary>
    /// 原子扣减库存
    /// </summary>
    /// <param name="goodsItemId">商品奖品ID</param>
    /// <param name="quantity">扣减数量，默认为1</param>
    /// <returns>是否扣减成功</returns>
    Task<bool> DeductStockAsync(int goodsItemId, int quantity = 1);

    /// <summary>
    /// 带重试的原子库存扣减
    /// </summary>
    /// <param name="goodsItemId">商品奖品ID</param>
    /// <param name="quantity">扣减数量，默认为1</param>
    /// <param name="maxRetries">最大重试次数，默认为3</param>
    /// <returns>是否扣减成功</returns>
    Task<bool> DeductStockWithRetryAsync(int goodsItemId, int quantity = 1, int maxRetries = 3);

    /// <summary>
    /// 检查库存可用性
    /// </summary>
    /// <param name="goodsItemId">商品奖品ID</param>
    /// <returns>是否有库存</returns>
    Task<bool> CheckStockAvailabilityAsync(int goodsItemId);

    /// <summary>
    /// 获取可抽奖品池（排除宝箱内子奖品）
    /// </summary>
    /// <param name="goodsId">商品ID</param>
    /// <param name="num">箱号</param>
    /// <returns>可抽奖品列表</returns>
    Task<List<GoodsItem>> GetAvailablePrizePoolAsync(int goodsId, int num);

    /// <summary>
    /// 获取可抽奖品池（宝箱内子奖品）
    /// </summary>
    /// <param name="goodsId">商品ID</param>
    /// <param name="num">箱号</param>
    /// <param name="parentGoodsListId">父奖品ID（宝箱ID）</param>
    /// <returns>可抽奖品列表</returns>
    Task<List<GoodsItem>> GetAvailableBoxPrizePoolAsync(int goodsId, int num, int parentGoodsListId);

    /// <summary>
    /// 获取商品的总剩余库存
    /// </summary>
    /// <param name="goodsId">商品ID</param>
    /// <param name="num">箱号</param>
    /// <returns>总剩余库存</returns>
    Task<int> GetTotalSurplusStockAsync(int goodsId, int num);

    /// <summary>
    /// 批量检查库存可用性
    /// </summary>
    /// <param name="goodsItemIds">商品奖品ID列表</param>
    /// <returns>有库存的商品奖品ID列表</returns>
    Task<List<int>> CheckBatchStockAvailabilityAsync(List<int> goodsItemIds);

    /// <summary>
    /// 获取奖品剩余库存
    /// </summary>
    /// <param name="goodsItemId">商品奖品ID</param>
    /// <returns>剩余库存数量</returns>
    Task<int> GetSurplusStockAsync(int goodsItemId);
}
