Идемпотентность — что это и как обеспечивать?

// Не идемпотентно
await db.Database.ExecuteSqlAsync($"UPDATE stock SET qty = qty - {msg.Qty} WHERE sku = {msg.Sku}");

// Идемпотентно: переход состояния только из ожидаемого + запись факта с уникальным ключом
var reserved = await db.Database.ExecuteSqlAsync($"""
    INSERT INTO reservations (order_id, sku, qty) VALUES ({msg.OrderId}, {msg.Sku}, {msg.Qty})
    ON CONFLICT (order_id, sku) DO NOTHING
    """);
if (reserved == 1)
    await db.Database.ExecuteSqlAsync($"UPDATE stock SET qty = qty - {msg.Qty} WHERE sku = {msg.Sku}");
// (оба оператора — в одной транзакции)

public void MarkPaid(PaymentId paymentId)
{
    if (Status == OrderStatus.Paid && PaymentId == paymentId) return;     // уже оплачено этим платежом — ок
    if (Status != OrderStatus.Placed) throw new DomainException($"Нельзя оплатить заказ в статусе {Status}");
    Status = OrderStatus.Paid;
    PaymentId = paymentId;
}

public sealed class IdempotencyFilter(IIdempotencyStore store) : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext ctx, EndpointFilterDelegate next)
    {
        var http = ctx.HttpContext;
        if (!http.Request.Headers.TryGetValue("Idempotency-Key", out var key) || !Guid.TryParse(key, out var id))
            return Results.BadRequest("Требуется заголовок Idempotency-Key");

        var existing = await store.TryGetAsync(id, http.RequestAborted);
        if (existing is { IsCompleted: true }) return Results.Json(existing.Body, statusCode: existing.StatusCode);
        if (existing is { IsCompleted: false }) return Results.Conflict("Запрос с этим ключом ещё обрабатывается");

        if (!await store.TryReserveAsync(id, requestHash: Hash(ctx.Arguments), http.RequestAborted))  // атомарно: INSERT ... ON CONFLICT
            return Results.Conflict("Параллельный запрос с тем же ключом");

        var result = await next(ctx);
        await store.CompleteAsync(id, result, http.RequestAborted);
        return result;
    }
}

public sealed class ReserveStockConsumer(ShopDbContext db) : IConsumer<OrderPlaced>
{
    public async Task Consume(ConsumeContext<OrderPlaced> context)
    {
        var messageId = context.MessageId ?? throw new InvalidOperationException("Нет MessageId");
        await using var tx = await db.Database.BeginTransactionAsync(context.CancellationToken);

        db.InboxMessages.Add(new InboxMessage(messageId, nameof(ReserveStockConsumer), DateTime.UtcNow));
        try
        {
            await db.SaveChangesAsync(context.CancellationToken);       // PK (message_id, consumer) — дубль упадёт здесь
        }
        catch (DbUpdateException ex) when (ex.IsUniqueViolation())
        {
            return;                                                      // уже обработано — просто подтвердить
        }

        await ReserveAsync(context.Message, context.CancellationToken);  // бизнес-эффект
        await db.SaveChangesAsync(context.CancellationToken);
        await tx.CommitAsync(context.CancellationToken);                 // Inbox и эффект — атомарно
    }
}