package com.jeesharp.business.modules.coupon.service;

import com.jeesharp.business.modules.coupon.entity.CouponTemplate;
import com.jeesharp.business.modules.coupon.vo.CouponTemplateQueryVO;
import com.jeesharp.framework.mybatis.core.service.BaseInterface;

/**
 * 优惠券模板领域服务。
 *
 * @author jeesharp
 * @since 2026-05-07
 */
public interface CouponTemplateService extends BaseInterface<CouponTemplate, CouponTemplateQueryVO> {

    /**
     * 新增优惠券模板（仅插入；主键由框架生成策略写入）。
     */
    CouponTemplate createCouponTemplate(CouponTemplate template);

    /**
     * 更新优惠券模板（按主键更新已存在行）。
     */
    void updateCouponTemplate(CouponTemplate template);

    /**
     * 在仍有配额时增加已发放数量。
     *
     * @param id 模板主键
     * @return 是否成功占用 1 个名额
     */
    boolean increaseIssuedIfQuotaAllows(String id);

    /**
     * 支付核销成功后增加模板已使用数量。
     */
    void increaseUsedCount(String id);

    /**
     * 退款退券时减少模板已使用数量（不低于 0）。
     */
    void decreaseUsedCountIfPositive(String id);

    /**
     * 按优惠券编码查询（可选租户隔离）。
     */
    CouponTemplate findByCouponCode(String couponCode, String tenantId);

    /**
     * 更新领券太阳码 scene 与图片 URL。
     */
    void updateClaimQrcode(String id, String claimWxScene, String claimQrcodeUrl);
}
