using TakeoutSaaS.Domain.Tenants.Entities;

namespace TakeoutSaaS.Domain.Tenants.Repositories;

/// <summary>
/// 租户套餐仓储。
/// </summary>
public interface ITenantPackageRepository
{
    /// <summary>
    /// 按套餐 ID 查询套餐。
    /// </summary>
    /// <param name="id">套餐 ID（雪花算法）。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>匹配的套餐实体，未找到返回 null。</returns>
    Task<TenantPackage?> FindByIdAsync(long id, CancellationToken cancellationToken = default);

    /// <summary>
    /// 按关键词与启用状态搜索套餐。
    /// </summary>
    /// <param name="keyword">名称或描述关键字，空则不按关键字过滤。</param>
    /// <param name="isActive">启用状态，空则不按状态过滤。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>符合条件的套餐列表。</returns>
    Task<IReadOnlyList<TenantPackage>> SearchAsync(string? keyword, bool? isActive, CancellationToken cancellationToken = default);

    /// <summary>
    /// 查询公共可选购套餐（仅返回：已发布 + 对外可见 + 允许新购 + 启用）。
    /// </summary>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>公共可选购套餐列表。</returns>
    Task<IReadOnlyList<TenantPackage>> SearchPublicPurchasableAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增套餐。
    /// </summary>
    /// <param name="package">套餐实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddAsync(TenantPackage package, CancellationToken cancellationToken = default);

    /// <summary>
    /// 更新套餐。
    /// </summary>
    /// <param name="package">套餐实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task UpdateAsync(TenantPackage package, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除套餐。
    /// </summary>
    /// <param name="id">套餐 ID（雪花算法）。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task DeleteAsync(long id, CancellationToken cancellationToken = default);

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