using System.Data.Common;
using GB5Shared.DTO.Framework.Login;
using GoodBooks.PAY.PAYDAL.DTO.Order;

namespace GoodBooks.PAY.PAYDAL.CustomCode.Order
{
    public interface IPayOrderDAL
    {
        Task<string> GetPayOrder(int payOrderId, LoginDTO loginDTO);

        /// <summary>
        /// Returns a typed DTO (not JSON) for use in webhook processing where the order is
        /// looked up by the gateway-assigned order ID rather than the internal PayOrderId.
        /// </summary>
        Task<PayOrderDTO?> GetPayOrderByGatewayOrderId(string gatewayOrderId, LoginDTO loginDTO);

        Task<string> GetPayOrderList(int pageOffset, int pageSize, LoginDTO loginDTO);

        /// <summary>
        /// Entitlement↔Payment loose coupling (Docs/Platform-Architecture-Integration-
        /// Reference.md §9.1) — every order ever created for one (SourceDocType, SourceDocId)
        /// pair, newest first. Backs both a caller's own payment-history view (e.g.
        /// Entitlement's client-portal Billing screen) and a reconciliation job checking
        /// whether a specific subscription's payment ever resolved.
        /// </summary>
        Task<string> GetPayOrdersBySourceDoc(int sourceDocType, int sourceDocId, LoginDTO loginDTO);

        /// <summary>
        /// Returns the count of TPAYORDER rows for the given source document with an active
        /// order status (Pending=1, Processing=2, Paid=3). Used to prevent duplicate payment
        /// order creation for the same source document.
        /// </summary>
        Task<int> CountActiveOrdersForSourceDoc(int sourceDocType, int sourceDocId, LoginDTO loginDTO);

        Task<int> InsertPayOrder(PayOrderDTO dto, LoginDTO loginDTO, DbTransaction? tx = null);

        /// <summary>
        /// Targeted status update — updates ORDERSTATUS, GATEWAYPAYORDERID, PAIDAMT, and audit fields only.
        /// Used by webhook callback handler and payment return endpoint.
        /// </summary>
        Task<int> UpdatePayOrderStatus(int payOrderId, int orderStatus, string? gatewayPayOrderId, decimal paidAmt, LoginDTO loginDTO, DbTransaction? tx = null);

        /// <summary>
        /// Updates the VoucherId on a pay order after the Finance module posts the receipt voucher.
        /// </summary>
        Task<int> UpdatePayOrderVoucherId(int payOrderId, int voucherId, LoginDTO loginDTO, DbTransaction? tx = null);
    }
}