using Dpz.Core.MessageQueue.Models;

namespace Dpz.Core.MessageQueue.Abstractions;

/// <summary>
/// 消息 Outbox 存储接口，用于持久化消息投递状态，实现发布和消费的数据库兜底。
/// </summary>
public interface IMessageOutboxStore
{
    /// <summary>
    /// 创建一条 Outbox 记录，在消息发布前调用，初始状态为"待发布"。
    /// </summary>
    /// <param name="messageId">消息唯一标识</param>
    /// <param name="messageType">消息类型的完全限定名</param>
    /// <param name="exchange">目标 Exchange 名称</param>
    /// <param name="routingKey">路由键</param>
    /// <param name="payload">JSON 序列化的消息体</param>
    /// <param name="source">消息来源标识，可为空</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task CreateAsync(
        string messageId,
        string messageType,
        string exchange,
        string routingKey,
        string payload,
        string? source,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 将消息标记为已成功发布到 RabbitMQ，累加发布尝试次数，状态变为"已发布"，
    /// 并记录本次尝试时间和发布时间。
    /// </summary>
    /// <param name="messageId">消息唯一标识</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task MarkSentAsync(string messageId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 将消息标记为发布失败，累加发布尝试次数并按指数退避计算下次重试时间，
    /// 状态变为"发布失败"。
    /// </summary>
    /// <param name="messageId">消息唯一标识</param>
    /// <param name="error">失败原因描述</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task MarkPublishFailedAsync(
        string messageId,
        string error,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 将消息标记为已成功消费，累加消费尝试次数，状态变为"已消费"，
    /// 并记录本次尝试时间和消费时间。
    /// </summary>
    /// <param name="messageId">消息唯一标识</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task MarkConsumedAsync(string messageId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 记录一次消费失败尝试，累加消费尝试次数并记录错误，但不改变消息当前状态。
    /// 用于消费者仍会立即重发消息体的短重试路径。
    /// </summary>
    /// <param name="messageId">消息唯一标识</param>
    /// <param name="error">失败原因描述</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task RecordConsumeAttemptFailedAsync(
        string messageId,
        string error,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 将消息标记为消费失败，累加消费尝试次数并按指数退避计算下次重试时间，
    /// 状态变为"消费失败"。
    /// </summary>
    /// <param name="messageId">消息唯一标识</param>
    /// <param name="error">失败原因描述</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task MarkConsumeFailedAsync(
        string messageId,
        string error,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 获取当前可进行发布重试的 Outbox 条目（状态为"发布失败"且退避时间已到）。
    /// </summary>
    /// <param name="batchSize">每批最大条数</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>待重试的 Outbox 条目列表</returns>
    Task<IReadOnlyList<MessageOutboxEntry>> GetPendingPublishRetryAsync(
        int batchSize,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 获取当前可进行消费重试的 Outbox 条目（状态为"消费失败"且退避时间已到）。
    /// </summary>
    /// <param name="batchSize">每批最大条数</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>待重试的 Outbox 条目列表</returns>
    Task<IReadOnlyList<MessageOutboxEntry>> GetPendingConsumeRetryAsync(
        int batchSize,
        CancellationToken cancellationToken = default
    );
}