using TakeoutSaaS.Domain.Merchants.Entities;
using TakeoutSaaS.Domain.Merchants.Enums;

namespace TakeoutSaaS.Domain.Merchants.Repositories;

/// <summary>
/// 商户聚合仓储契约，提供基础 CRUD 与查询能力。
/// </summary>
public interface IMerchantRepository
{
    /// <summary>
    /// 依据标识获取商户。
    /// </summary>
    /// <param name="merchantId">商户 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>商户实体或 null。</returns>
    Task<Merchant?> FindByIdAsync(long merchantId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 按状态筛选商户列表。
    /// </summary>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="status">状态过滤。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>商户集合。</returns>
    Task<IReadOnlyList<Merchant>> SearchAsync(long tenantId, MerchantStatus? status, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取指定商户的员工列表。
    /// </summary>
    /// <param name="merchantId">商户 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>员工集合。</returns>
    Task<IReadOnlyList<MerchantStaff>> GetStaffAsync(long merchantId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取指定门店的员工列表。
    /// </summary>
    Task<IReadOnlyList<MerchantStaff>> GetStaffByStoreAsync(long storeId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 依据标识获取员工。
    /// </summary>
    Task<MerchantStaff?> FindStaffByIdAsync(long staffId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取指定商户的合同列表。
    /// </summary>
    /// <param name="merchantId">商户 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>合同集合。</returns>
    Task<IReadOnlyList<MerchantContract>> GetContractsAsync(long merchantId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 根据合同 ID 获取合同详情。
    /// </summary>
    /// <param name="merchantId">商户 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="contractId">合同 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>合同实体或 null。</returns>
    Task<MerchantContract?> FindContractByIdAsync(long merchantId, long tenantId, long contractId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取指定商户的资质文件列表。
    /// </summary>
    /// <param name="merchantId">商户 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>资质文件列表。</returns>
    Task<IReadOnlyList<MerchantDocument>> GetDocumentsAsync(long merchantId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 根据文件 ID 获取资质文件详情。
    /// </summary>
    /// <param name="merchantId">商户 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="documentId">文件 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>资质文件实体或 null。</returns>
    Task<MerchantDocument?> FindDocumentByIdAsync(long merchantId, long tenantId, long documentId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增商户主体。
    /// </summary>
    /// <param name="merchant">商户实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddMerchantAsync(Merchant merchant, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增商户员工。
    /// </summary>
    /// <param name="staff">员工实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddStaffAsync(MerchantStaff staff, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增商户合同。
    /// </summary>
    /// <param name="contract">合同实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddContractAsync(MerchantContract contract, CancellationToken cancellationToken = default);

    /// <summary>
    /// 更新商户合同。
    /// </summary>
    /// <param name="contract">合同实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步操作任务。</returns>
    Task UpdateContractAsync(MerchantContract contract, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增商户资质文件。
    /// </summary>
    /// <param name="document">资质文件实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddDocumentAsync(MerchantDocument document, CancellationToken cancellationToken = default);

    /// <summary>
    /// 更新商户资质文件。
    /// </summary>
    /// <param name="document">资质文件实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步操作任务。</returns>
    Task UpdateDocumentAsync(MerchantDocument document, CancellationToken cancellationToken = default);

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

    /// <summary>
    /// 更新商户信息。
    /// </summary>
    /// <param name="merchant">商户实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task UpdateMerchantAsync(Merchant merchant, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除商户。
    /// </summary>
    /// <param name="merchantId">商户 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task DeleteMerchantAsync(long merchantId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除员工。
    /// </summary>
    Task DeleteStaffAsync(long staffId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 记录审核日志。
    /// </summary>
    /// <param name="log">审核日志实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddAuditLogAsync(MerchantAuditLog log, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取审核日志。
    /// </summary>
    /// <param name="merchantId">商户 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>审核日志列表。</returns>
    Task<IReadOnlyList<MerchantAuditLog>> GetAuditLogsAsync(long merchantId, long tenantId, CancellationToken cancellationToken = default);
}
