using TakeoutSaaS.Domain.Dictionary.Entities;

namespace TakeoutSaaS.Domain.Dictionary.Repositories;

/// <summary>
/// 字典项仓储契约。
/// </summary>
public interface IDictionaryItemRepository
{
    /// <summary>
    /// 根据 ID 获取字典项。
    /// </summary>
    /// <param name="itemId">字典项 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>字典项或 null。</returns>
    Task<DictionaryItem?> GetByIdAsync(long itemId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取分组下字典项列表。
    /// </summary>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="groupId">分组 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>字典项集合。</returns>
    Task<IReadOnlyList<DictionaryItem>> GetByGroupIdAsync(long tenantId, long groupId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取合并后的系统/租户字典项。
    /// </summary>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="systemGroupId">系统分组 ID。</param>
    /// <param name="includeOverrides">是否包含租户覆盖。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>字典项集合。</returns>
    Task<IReadOnlyList<DictionaryItem>> GetMergedItemsAsync(long tenantId, long systemGroupId, bool includeOverrides, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增字典项。
    /// </summary>
    /// <param name="item">字典项实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    Task AddAsync(DictionaryItem item, CancellationToken cancellationToken = default);

    /// <summary>
    /// 更新字典项。
    /// </summary>
    /// <param name="item">字典项实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    Task UpdateAsync(DictionaryItem item, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除字典项。
    /// </summary>
    /// <param name="item">字典项实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    Task RemoveAsync(DictionaryItem item, CancellationToken cancellationToken = default);

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