using TakeoutSaaS.Domain.Deliveries.Entities;
using TakeoutSaaS.Domain.Deliveries.Enums;

namespace TakeoutSaaS.Domain.Deliveries.Repositories;

/// <summary>
/// 配送聚合仓储契约。
/// </summary>
public interface IDeliveryRepository
{
    /// <summary>
    /// 依据标识获取配送单。
    /// </summary>
    /// <param name="deliveryOrderId">配送单 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>配送单实体或 null。</returns>
    Task<DeliveryOrder?> FindByIdAsync(long deliveryOrderId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 依据订单标识获取配送单。
    /// </summary>
    /// <param name="orderId">订单 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>配送单实体或 null。</returns>
    Task<DeliveryOrder?> FindByOrderIdAsync(long orderId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取配送事件轨迹。
    /// </summary>
    /// <param name="deliveryOrderId">配送单 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>配送事件列表。</returns>
    Task<IReadOnlyList<DeliveryEvent>> GetEventsAsync(long deliveryOrderId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增配送单。
    /// </summary>
    /// <param name="deliveryOrder">配送单实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddDeliveryOrderAsync(DeliveryOrder deliveryOrder, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增配送事件。
    /// </summary>
    /// <param name="deliveryEvent">配送事件。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddEventAsync(DeliveryEvent deliveryEvent, CancellationToken cancellationToken = default);

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

    /// <summary>
    /// 按状态查询配送单。
    /// </summary>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="status">配送状态。</param>
    /// <param name="orderId">订单 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>配送单列表。</returns>
    Task<IReadOnlyList<DeliveryOrder>> SearchAsync(long tenantId, DeliveryStatus? status, long? orderId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 更新配送单。
    /// </summary>
    /// <param name="deliveryOrder">配送单实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task UpdateDeliveryOrderAsync(DeliveryOrder deliveryOrder, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除配送单及事件。
    /// </summary>
    /// <param name="deliveryOrderId">配送单 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task DeleteDeliveryOrderAsync(long deliveryOrderId, long tenantId, CancellationToken cancellationToken = default);
}