package com.jeesharp.business.modules.member.api;

import com.jeesharp.business.modules.member.dto.MemberPointsDeductDTO;
import com.jeesharp.business.modules.member.dto.MemberPointsGrantDTO;
import com.jeesharp.business.modules.member.dto.MemberPointsGrantResultDTO;
import com.jeesharp.business.modules.member.dto.MemberPointsRevokeDTO;
import com.jeesharp.business.modules.member.dto.MemberPointsTrialDTO;
import com.jeesharp.business.modules.member.dto.MemberPointsTrialResultDTO;

/**
 * 会员积分对外 API：跨模块统一发放、试算、扣减与冲正入口。
 *
 * @author jeesharp
 * @since 2026-06-23
 */
public interface MemberPointsApi {

    /**
     * 试算预计可得积分（不落库）。
     */
    MemberPointsTrialResultDTO trial(MemberPointsTrialDTO dto);

    /**
     * 按场景规则发放积分（幂等）。
     */
    MemberPointsGrantResultDTO grant(MemberPointsGrantDTO dto);

    /**
     * 按场景扣减积分（幂等，用于兑换等纯扣减场景）。
     */
    MemberPointsGrantResultDTO deduct(MemberPointsDeductDTO dto);

    /**
     * 冲正已发放积分（如订单取消）。
     */
    void revoke(MemberPointsRevokeDTO dto);

    /**
     * 新会员注册赠送积分（幂等）。
     */
    MemberPointsGrantResultDTO grantRegisterPoints(String memberId);
}
