using TakeoutSaaS.Domain.Tenants.Entities;

namespace TakeoutSaaS.Domain.Tenants.Repositories;

/// <summary>
/// 租户支付记录仓储。
/// </summary>
public interface ITenantPaymentRepository
{
    /// <summary>
    /// 分页查询支付记录。
    /// </summary>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="from">开始时间（UTC）。</param>
    /// <param name="to">结束时间（UTC）。</param>
    /// <param name="page">页码（从 1 开始）。</param>
    /// <param name="pageSize">每页条数。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>分页结果（数据与总数）。</returns>
    Task<(IReadOnlyList<TenantPayment> Items, int Total)> SearchPagedAsync(
        long tenantId,
        DateTime from,
        DateTime to,
        int page,
        int pageSize,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 查询指定账单的支付记录列表。
    /// </summary>
    /// <param name="billingStatementId">账单 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>支付记录集合。</returns>
    Task<IReadOnlyList<TenantPayment>> GetByBillingIdAsync(long billingStatementId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 计算指定账单的累计已支付金额。
    /// </summary>
    /// <param name="billingStatementId">账单 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>累计已支付金额。</returns>
    Task<decimal> GetTotalPaidAmountAsync(long billingStatementId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 按 ID 获取支付记录。
    /// </summary>
    /// <param name="paymentId">支付记录 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>支付记录实体或 null。</returns>
    Task<TenantPayment?> FindByIdAsync(long paymentId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 按交易号获取支付记录。
    /// </summary>
    /// <param name="transactionNo">交易号。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>支付记录实体或 null。</returns>
    Task<TenantPayment?> GetByTransactionNoAsync(string transactionNo, CancellationToken cancellationToken = default);

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

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

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