using TakeoutSaaS.Domain.Tenants.Entities;
using TakeoutSaaS.Domain.Tenants.Enums;

namespace TakeoutSaaS.Domain.Tenants.Repositories;

/// <summary>
/// 租户公告仓储。
/// </summary>
public interface ITenantAnnouncementRepository
{
    /// <summary>
    /// 查询公告列表（包含平台公告 TenantId=0），按类型、状态与生效时间筛选。
    /// </summary>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="status">公告状态。</param>
    /// <param name="type">公告类型。</param>
    /// <param name="isActive">启用状态。</param>
    /// <param name="effectiveFrom">生效开始时间筛选。</param>
    /// <param name="effectiveTo">生效结束时间筛选。</param>
    /// <param name="effectiveAt">生效时间点，为空不限制。</param>
    /// <param name="orderByPriority">是否按优先级降序和生效时间降序排序，默认 false。</param>
    /// <param name="limit">限制返回数量，为空不限制。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>公告集合。</returns>
    Task<IReadOnlyList<TenantAnnouncement>> SearchAsync(
        long tenantId,
        AnnouncementStatus? status,
        TenantAnnouncementType? type,
        bool? isActive,
        DateTime? effectiveFrom,
        DateTime? effectiveTo,
        DateTime? effectiveAt,
        bool orderByPriority = false,
        int? limit = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 按 ID 获取公告（包含平台公告 TenantId=0）。
    /// </summary>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="announcementId">公告 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>公告实体或 null。</returns>
    Task<TenantAnnouncement?> FindByIdInScopeAsync(long tenantId, long announcementId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 查询未读公告（包含平台公告 TenantId=0）。
    /// </summary>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="userId">用户 ID。</param>
    /// <param name="status">公告状态。</param>
    /// <param name="isActive">启用状态。</param>
    /// <param name="effectiveAt">生效时间点，为空不限制。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>未读公告集合。</returns>
    Task<IReadOnlyList<TenantAnnouncement>> SearchUnreadAsync(
        long tenantId,
        long? userId,
        AnnouncementStatus? status,
        bool? isActive,
        DateTime? effectiveAt,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 按 ID 获取公告。
    /// </summary>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="announcementId">公告 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>公告实体或 null。</returns>
    Task<TenantAnnouncement?> FindByIdAsync(long tenantId, long announcementId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增公告。
    /// </summary>
    /// <param name="announcement">公告实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddAsync(TenantAnnouncement announcement, CancellationToken cancellationToken = default);

    /// <summary>
    /// 更新公告。
    /// </summary>
    /// <param name="announcement">公告实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task UpdateAsync(TenantAnnouncement announcement, CancellationToken cancellationToken = default);

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

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