using TakeoutSaaS.Domain.SystemParameters.Entities;

namespace TakeoutSaaS.Domain.SystemParameters.Repositories;

/// <summary>
/// 系统参数仓储接口：提供基础 CRUD 与查询能力。
/// </summary>
public interface ISystemParameterRepository
{
    /// <summary>
    /// 根据标识获取系统参数。
    /// </summary>
    /// <param name="id">参数 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>系统参数或 null。</returns>
    Task<SystemParameter?> FindByIdAsync(long id, CancellationToken cancellationToken = default);

    /// <summary>
    /// 根据键获取系统参数（当前租户）。
    /// </summary>
    /// <param name="key">参数键。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>系统参数或 null。</returns>
    Task<SystemParameter?> FindByKeyAsync(string key, CancellationToken cancellationToken = default);

    /// <summary>
    /// 查询系统参数列表。
    /// </summary>
    /// <param name="keyword">关键字。</param>
    /// <param name="isEnabled">启用状态。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>参数列表。</returns>
    Task<IReadOnlyList<SystemParameter>> SearchAsync(string? keyword, bool? isEnabled, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增系统参数。
    /// </summary>
    /// <param name="parameter">参数实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddAsync(SystemParameter parameter, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除系统参数。
    /// </summary>
    /// <param name="parameter">参数实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task RemoveAsync(SystemParameter parameter, CancellationToken cancellationToken = default);

    /// <summary>
    /// 更新系统参数。
    /// </summary>
    /// <param name="parameter">参数实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task UpdateAsync(SystemParameter parameter, CancellationToken cancellationToken = default);

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