package com.ycwl.basic.pricing.service;

import com.ycwl.basic.pricing.dto.CouponInfo;
import com.ycwl.basic.pricing.dto.CouponUseRequest;
import com.ycwl.basic.pricing.dto.CouponUseResult;
import com.ycwl.basic.pricing.dto.CouponClaimRequest;
import com.ycwl.basic.pricing.dto.CouponClaimResult;
import com.ycwl.basic.pricing.dto.ProductItem;
import com.ycwl.basic.pricing.dto.resp.UserCouponResp;
import com.ycwl.basic.pricing.entity.PriceCouponConfig;

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

/**
 * 优惠券服务接口
 */
public interface ICouponService {
    
    /**
     * 自动选择最优优惠券
     * 
     * @param userId 用户ID
     * @param products 商品列表
     * @param totalAmount 总金额
     * @return 最优优惠券信息，如果没有可用优惠券则返回null
     */
    CouponInfo selectBestCoupon(Long userId, List<ProductItem> products, BigDecimal totalAmount);
    
    /**
     * 计算优惠券优惠金额
     * 
     * @param coupon 优惠券配置
     * @param products 商品列表
     * @param totalAmount 总金额
     * @return 优惠金额
     */
    BigDecimal calculateCouponDiscount(PriceCouponConfig coupon, List<ProductItem> products, BigDecimal totalAmount);
    
    /**
     * 验证优惠券是否可用
     * 
     * @param coupon 优惠券配置
     * @param products 商品列表
     * @param totalAmount 总金额
     * @return 是否可用
     */
    boolean isCouponApplicable(PriceCouponConfig coupon, List<ProductItem> products, BigDecimal totalAmount);
    
    /**
     * 使用优惠券
     * 
     * @param request 优惠券使用请求
     * @return 使用结果
     */
    CouponUseResult useCoupon(CouponUseRequest request);
    
    /**
     * 查询用户可用优惠券（包含领取记录信息）
     *
     * @param userId 用户ID
     * @param scenicId 景区ID，传入时仅返回该景区可用的优惠券，NULL时返回全部
     * @return 用户优惠券列表（包含领取记录+优惠券配置）
     */
    List<UserCouponResp> getUserAvailableCoupons(Long userId, String scenicId);
    
    /**
     * 领取优惠券（内部调用方法）
     * 
     * @param request 领取请求
     * @return 领取结果
     */
    CouponClaimResult claimCoupon(CouponClaimRequest request);
}