package com.dora.service;

import com.dora.exception.InsufficientPointsException;

public interface PointsService {

    /**
     * 为AI任务扣除积分。
     *
     * @param userId      用户ID
     * @param amount      要扣除的积分数量 (必须为正数)
     * @param taskNo      关联的AI任务编号
     * @param description 扣除原因
     * @throws InsufficientPointsException 如果用户积分不足
     */
    void deductPoints(Long userId, Integer amount, String taskNo, String description) throws InsufficientPointsException;

    /**
     * 为AI任务退还积分。
     *
     * @param userId      用户ID
     * @param amount      要退还的积分数量 (必须为正数)
     * @param taskNo      关联的AI任务编号
     * @param description 退款原因
     */
    void refundPoints(Long userId, Integer amount, String taskNo, String description);

    /**
     * 管理员调整用户积分。
     *
     * @param userId      用户ID
     * @param amount      调整的积分数量 (可正可负)
     * @param description 调整原因
     * @param adminId     操作的管理员ID
     */
    void adminAdjustPoints(Long userId, Integer amount, String description, Long adminId);

    /**
     * 发放积分（用于注册奖励、邀请奖励等）。
     *
     * @param userId      用户ID
     * @param amount      要发放的积分数量 (必须为正数)
     * @param description 发放原因
     */
    void grantPoints(Long userId, Integer amount, String description);
}
