using System.Collections.Generic;
using System.Data.Common;
using System.Threading.Tasks;
using GB5Shared.DTO.Framework.Login;
using GoodBooks.PAY.PAYDAL.DTO.Loyalty;

namespace GoodBooks.PAY.PAYDAL.CustomCode.Loyalty
{
    /// <summary>
    /// Data-access contract for TLOYALTYLEDGER — append-only points ledger.
    /// CRITICAL: No UPDATE methods are defined here.
    /// To reverse or expire points, insert a new compensating row with negative POINTS value.
    /// Any modification to existing rows would break the audit trail and balance integrity.
    /// </summary>
    public interface ILoyaltyLedgerDAL
    {
        /// <summary>
        /// Appends a new ledger entry. LOYALTYLEDGERID must be supplied by the caller.
        /// Returns rows affected.
        /// </summary>
        Task<int> InsertLedgerEntry(LoyaltyLedgerDTO dto, LoginDTO login, DbTransaction? tx);

        /// <summary>
        /// Returns the live sum of non-expired points for an enrollment.
        /// Executes directly against TLOYALTYLEDGER — never cached.
        /// </summary>
        Task<decimal> GetAvailablePoints(int enrollmentId, LoginDTO login);

        /// <summary>
        /// Returns a paged JSON list of ledger entries for an enrollment, newest first.
        /// Includes the PayOrderNo from TPAYORDER for display.
        /// </summary>
        Task<string> GetLoyaltyLedger(int enrollmentId, int pageOffset, int pageSize, LoginDTO login);

        /// <summary>
        /// Returns enrollments that have Earn-type points (ENTRYTYPE=1) expiring today.
        /// Used by the daily points-expiry background job to know which enrollments to process.
        /// The job then inserts compensating negative-points rows for each returned enrollment.
        /// </summary>
        Task<IEnumerable<(int EnrollmentId, decimal PointsExpiring)>> GetExpiringPoints(LoginDTO login);
    }
}