using QYZH.InteractiveMagazine.Models.Dto;
using QYZH.InteractiveMagazine.Models.Dto.Points;
using QYZH.InteractiveMagazine.Models.Entity;

namespace QYZH.InteractiveMagazine.IService;

/// <summary>
/// 积分服务接口
/// </summary>
public interface IPointsService : IBaseService<PointsRecord>
{
    // ==================== 带事务版本（独立调用） ====================

    /// <summary>
    /// 增加积分（带事务）
    /// </summary>
    /// <param name="input">增加积分参数</param>
    /// <returns>增加结果</returns>
    Task<AddPointsOutput> AddPointsAsync(AddPointsInput input);

    /// <summary>
    /// 扣除积分（带事务，含余额不足校验）
    /// </summary>
    /// <param name="input">扣除积分参数</param>
    /// <returns>扣除结果</returns>
    Task<DeductPointsOutput> DeductPointsAsync(DeductPointsInput input);

    // ==================== 无事务版本（供外部事务调用） ====================

    /// <summary>
    /// 增加积分（无事务，需在外部事务中调用）
    /// </summary>
    /// <param name="input">增加积分参数</param>
    /// <returns>增加结果</returns>
    Task<AddPointsOutput> AddPointsInTranAsync(AddPointsInput input);

    /// <summary>
    /// 扣除积分（无事务，需在外部事务中调用，含余额不足校验）
    /// </summary>
    /// <param name="input">扣除积分参数</param>
    /// <returns>扣除结果</returns>
    Task<DeductPointsOutput> DeductPointsInTranAsync(DeductPointsInput input);

    // ==================== 查询 ====================

    /// <summary>
    /// 查询用户当前积分余额
    /// </summary>
    /// <param name="userId">用户Id</param>
    /// <returns>当前积分余额</returns>
    Task<int> GetUserPointsAsync(long userId);

    /// <summary>
    /// 获取用户积分概览（当前余额 + 累计收入 + 累计支出）
    /// </summary>
    /// <param name="userId">用户Id</param>
    /// <returns>积分概览</returns>
    Task<PointsSummaryOutput> GetPointsSummaryAsync(long userId);

    /// <summary>
    /// 分页查询积分流水
    /// </summary>
    /// <param name="input">查询参数</param>
    /// <returns>分页流水列表</returns>
    Task<PageListModel<PointsRecordOutput>> GetPointsRecordsAsync(PointsRecordQueryInput input);
}