TakeoutSaaS.AdminApi/src/Domain/TakeoutSaaS.Domain/Orders/Repositories/IOrderRepository.cs

using TakeoutSaaS.Domain.Orders.Entities;
using TakeoutSaaS.Domain.Orders.Enums;
using TakeoutSaaS.Domain.Payments.Enums;

namespace TakeoutSaaS.Domain.Orders.Repositories;

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

    /// <summary>
    /// 依据标识获取订单（跨租户）。
    /// </summary>
    /// <param name="orderId">订单 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>订单实体或 null。</returns>
    Task<Order?> FindByIdAsync(long orderId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 依据订单号获取订单。
    /// </summary>
    /// <param name="orderNo">订单号。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>订单实体或 null。</returns>
    Task<Order?> FindByOrderNoAsync(string orderNo, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 按状态筛选订单列表。
    /// </summary>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="status">订单状态。</param>
    /// <param name="paymentStatus">支付状态。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>订单集合。</returns>
    Task<IReadOnlyList<Order>> SearchAsync(long tenantId, OrderStatus? status, PaymentStatus? paymentStatus, CancellationToken cancellationToken = default);

    /// <summary>
    /// 按状态筛选订单列表（可选租户过滤）。
    /// </summary>
    /// <param name="tenantId">租户 ID（可选，空表示跨租户查询）。</param>
    /// <param name="status">订单状态。</param>
    /// <param name="paymentStatus">支付状态。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>订单集合。</returns>
    Task<IReadOnlyList<Order>> SearchAsync(long? tenantId, OrderStatus? status, PaymentStatus? paymentStatus, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取订单明细行。
    /// </summary>
    /// <param name="orderId">订单 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>订单明细集合。</returns>
    Task<IReadOnlyList<OrderItem>> GetItemsAsync(long orderId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取订单状态流转记录。
    /// </summary>
    /// <param name="orderId">订单 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>状态变更记录列表。</returns>
    Task<IReadOnlyList<OrderStatusHistory>> GetStatusHistoryAsync(long orderId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取订单退款申请。
    /// </summary>
    /// <param name="orderId">订单 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>退款申请列表。</returns>
    Task<IReadOnlyList<RefundRequest>> GetRefundsAsync(long orderId, long tenantId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增订单。
    /// </summary>
    /// <param name="order">订单实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddOrderAsync(Order order, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增订单明细。
    /// </summary>
    /// <param name="items">明细集合。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddItemsAsync(IEnumerable<OrderItem> items, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增订单状态记录。
    /// </summary>
    /// <param name="history">状态记录。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddStatusHistoryAsync(OrderStatusHistory history, CancellationToken cancellationToken = default);

    /// <summary>
    /// 新增退款申请。
    /// </summary>
    /// <param name="refund">退款申请实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task AddRefundAsync(RefundRequest refund, CancellationToken cancellationToken = default);

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

    /// <summary>
    /// 更新订单。
    /// </summary>
    /// <param name="order">订单实体。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task UpdateOrderAsync(Order order, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除订单。
    /// </summary>
    /// <param name="orderId">订单 ID。</param>
    /// <param name="tenantId">租户 ID。</param>
    /// <param name="cancellationToken">取消标记。</param>
    /// <returns>异步任务。</returns>
    Task DeleteOrderAsync(long orderId, long tenantId, CancellationToken cancellationToken = default);
}