using TakeoutSaaS.Domain.Payments.Entities;
using TakeoutSaaS.Domain.Payments.Enums;

namespace TakeoutSaaS.Domain.Payments.Repositories;

/// <summary>
/// 支付记录仓储契约。
/// </summary>
public interface IPaymentRepository
{
    /// <summary>
    /// 依据标识获取支付记录。
    /// </summary>
    /// <param name="paymentId">支付记录 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>支付记录或 null。</returns>
    Task<PaymentRecord?> FindByIdAsync(long paymentId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 依据订单标识获取支付记录。
    /// </summary>
    /// <param name="orderId">订单 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>支付记录或 null。</returns>
    Task<PaymentRecord?> FindByOrderIdAsync(long orderId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取支付对应的退款记录。
    /// </summary>
    /// <param name="paymentId">支付记录 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>退款记录列表。</returns>
    Task<IReadOnlyList<PaymentRefundRecord>> GetRefundsAsync(long paymentId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增支付记录。
    /// </summary>
    /// <param name="payment">支付实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddPaymentAsync(PaymentRecord payment, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增退款记录。
    /// </summary>
    /// <param name="refund">退款实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddRefundAsync(PaymentRefundRecord refund, CancellationToken cancellationToken = default);

    /// <summary>
    /// 持久化变更。
    /// </summary>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task SaveChangesAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// 按状态筛选支付记录。
    /// </summary>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="status">支付状态。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>支付记录列表。</returns>
    Task<IReadOnlyList<PaymentRecord>> SearchAsync(long tenantId, PaymentStatus? status, CancellationToken cancellationToken = default);

    /// <summary>
    /// 更新支付记录。
    /// </summary>
    /// <param name="payment">支付实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task UpdatePaymentAsync(PaymentRecord payment, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除支付记录及关联退款。
    /// </summary>
    /// <param name="paymentId">支付记录 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task DeletePaymentAsync(long paymentId, long tenantId, CancellationToken cancellationToken = default);
}
