using TakeoutSaaS.Domain.Tenants.Entities;

namespace TakeoutSaaS.Domain.Tenants.Repositories;

/// <summary>
/// 公告已读仓储。
/// </summary>
public interface ITenantAnnouncementReadRepository
{
    /// <summary>
    /// 按公告查询已读记录。
    /// </summary>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="announcementId">公告 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>指定公告的已读列表。</returns>
    Task<IReadOnlyList<TenantAnnouncementRead>> GetByAnnouncementAsync(long tenantId, long announcementId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 批量按公告查询已读记录，可选按用户过滤。
    /// </summary>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="announcementIds">公告 ID 集合。</param>
    /// <param name="userId">用户 ID，空则不按用户筛选。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>匹配条件的已读列表。</returns>
    Task<IReadOnlyList<TenantAnnouncementRead>> GetByAnnouncementAsync(long tenantId, IEnumerable<long> announcementIds, long? userId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 查询指定用户对某公告的已读记录。
    /// </summary>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="announcementId">公告 ID。</param>
    /// <param name="userId">用户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>已读记录，未读返回 null。</returns>
    Task<TenantAnnouncementRead?> FindAsync(long tenantId, long announcementId, long? userId, CancellationToken cancellationToken = default);

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

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