using TakeoutSaaS.Domain.Dictionary.Entities;
using TakeoutSaaS.Domain.Dictionary.Enums;

namespace TakeoutSaaS.Domain.Dictionary.Repositories;

/// <summary>
/// 参数字典仓储契约。
/// </summary>
public interface IDictionaryRepository
{
    /// <summary>
    /// 依据 ID 获取分组。
    /// </summary>
    /// <param name="id">分组 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>分组实体或 null。</returns>
    Task<DictionaryGroup?> FindGroupByIdAsync(long id, CancellationToken cancellationToken = default);

    /// <summary>
    /// 依据编码获取分组。
    /// </summary>
    /// <param name="code">分组编码。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>分组实体或 null。</returns>
    Task<DictionaryGroup?> FindGroupByCodeAsync(string code, CancellationToken cancellationToken = default);

    /// <summary>
    /// 搜索分组，可按作用域过滤。
    /// </summary>
    /// <param name="scope">作用域。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>分组集合。</returns>
    Task<IReadOnlyList<DictionaryGroup>> SearchGroupsAsync(DictionaryScope? scope, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增分组。
    /// </summary>
    /// <param name="group">分组实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddGroupAsync(DictionaryGroup group, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除分组。
    /// </summary>
    /// <param name="group">分组实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task RemoveGroupAsync(DictionaryGroup group, CancellationToken cancellationToken = default);

    /// <summary>
    /// 依据 ID 获取字典项。
    /// </summary>
    /// <param name="id">字典项 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>字典项或 null。</returns>
    Task<DictionaryItem?> FindItemByIdAsync(long id, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取某分组下的所有字典项。
    /// </summary>
    /// <param name="groupId">分组 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>字典项集合。</returns>
    Task<IReadOnlyList<DictionaryItem>> GetItemsByGroupIdAsync(long groupId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 按分组编码集合获取字典项（可包含系统参数）。
    /// </summary>
    /// <param name="codes">分组编码集合。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="includeSystem">是否包含系统分组。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>字典项集合。</returns>
    Task<IReadOnlyList<DictionaryItem>> GetItemsByCodesAsync(IEnumerable<string> codes, long tenantId, bool includeSystem, CancellationToken cancellationToken = default);

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

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

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