zsElectric-boot/src/main/java/com/zsElectric/boot/business/service/CouponService.java

package com.zsElectric.boot.business.service;

import com.zsElectric.boot.business.model.entity.Coupon;
import com.zsElectric.boot.business.model.form.CouponForm;
import com.zsElectric.boot.business.model.form.applet.AppGainCouponForm;
import com.zsElectric.boot.business.model.query.CouponQuery;
import com.zsElectric.boot.business.model.query.applet.AppCouponQuery;
import com.zsElectric.boot.business.model.vo.CouponVO;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import com.zsElectric.boot.business.model.vo.applet.AppCouponStatusNumVO;

import java.math.BigDecimal;

/**
 * 优惠劵服务类
 *
 * @author zsElectric
 * @since 2025-12-19 09:58
 */
public interface CouponService extends IService<Coupon> {

    /**
     *优惠劵分页列表
     *
     * @return {@link IPage<CouponVO>} 优惠劵分页列表
     */
    IPage<CouponVO> getCouponPage(CouponQuery queryParams);

    /**
     * 获取优惠劵表单数据
     *
     * @param id 优惠劵ID
     * @return 优惠劵表单数据
     */
     CouponForm getCouponFormData(Long id);

    /**
     * 新增优惠劵
     *
     * @param formData 优惠劵表单对象
     * @return 是否新增成功
     */
    boolean saveCoupon(CouponForm formData);

    /**
     * 修改优惠劵
     *
     * @param id   优惠劵ID
     * @param formData 优惠劵表单对象
     * @return 是否修改成功
     */
    boolean updateCoupon(Long id, CouponForm formData);

    /**
     * 删除优惠劵
     *
     * @param ids 优惠劵ID，多个以英文逗号(,)分割
     * @return 是否删除成功
     */
    boolean deleteCoupons(String ids);

    /**
     * 检查优惠券是否有效
     *
     * @param couponId 优惠券ID
     * @return 是否有效
     */
    boolean isValidCoupon(Long couponId);

    /**
     * 检查优惠券是否可以使用
     *
     * @param couponId 优惠券ID
     * @param orderAmount 订单金额
     * @return 是否可以使用
     */
    boolean canUseCoupon(Long couponId, BigDecimal orderAmount);

    /**
     * 使用优惠券
     *
     * @param couponId 优惠券ID
     * @param orderId 订单ID
     * @param orderAmount 订单金额
     * @return 实际优惠金额
     */
    BigDecimal useCoupon(Long couponId, Long orderId, BigDecimal orderAmount);

    /**
     * 过期优惠券处理
     *
     * @param couponId 优惠券ID
     * @return 是否处理成功
     */
    boolean expireCoupon(Long couponId);

    /**
     * 获取用户指定状态的优惠券列表
     *
     * @param userId 用户ID
     * @param status 优惠券状态
     * @return 优惠券列表
     */
    java.util.List<Coupon> getUserCouponsByStatus(Long userId, Integer status);

    /**
     * 根据模板ID和用户ID获取用户持有的优惠券
     *
     * @param templateId 模板ID
     * @param userId 用户ID
     * @return 优惠券列表
     */
    java.util.List<Coupon> getCouponsByTemplateAndUser(Long templateId, Long userId);

    IPage<CouponVO> getUserCouponPage(AppCouponQuery queryParams);

    AppCouponStatusNumVO getCouponStatusNum(Long userId);

    Boolean gainCoupon(AppGainCouponForm formData);
}