FrameTour-BE/src/main/java/com/ycwl/basic/pricing/service/IVoucherService.java

package com.ycwl.basic.pricing.service;

import com.ycwl.basic.pricing.dto.DiscountDetectionContext;
import com.ycwl.basic.pricing.dto.VoucherInfo;

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

/**
 * 券码服务接口
 */
public interface IVoucherService {
    
    /**
     * 验证并获取券码信息
     * @param voucherCode 券码
     * @param faceId 用户faceId
     * @param scenicId 景区ID
     * @return 券码信息（如果有效）
     */
    VoucherInfo validateAndGetVoucherInfo(String voucherCode, Long faceId, Long scenicId);
    
    /**
     * 获取用户在指定景区的可用券码列表
     * @param faceId 用户faceId
     * @param scenicId 景区ID
     * @return 可用券码列表
     */
    List<VoucherInfo> getAvailableVouchers(Long faceId, Long scenicId);
    
    /**
     * 标记券码为已使用
     * @param voucherCode 券码
     * @param remark 使用备注
     */
    void markVoucherAsUsed(String voucherCode, String remark);
    
    /**
     * 检查用户是否可以在指定景区领取券码
     * @param faceId 用户faceId
     * @param scenicId 景区ID
     * @return 是否可以领取
     */
    boolean canClaimVoucher(Long faceId, Long scenicId);
    
    /**
     * 计算券码优惠金额
     * @param voucherInfo 券码信息
     * @param context 检测上下文
     * @return 优惠金额
     */
    BigDecimal calculateVoucherDiscount(VoucherInfo voucherInfo, DiscountDetectionContext context);
    
    /**
     * 获取最优的券码（如果用户有多个可用券码）
     * @param faceId 用户faceId
     * @param scenicId 景区ID
     * @param context 检测上下文
     * @return 最优券码信息
     */
    VoucherInfo getBestVoucher(Long faceId, Long scenicId, DiscountDetectionContext context);
}