<?php

namespace App\Services\Billing\Concerns;

use Closure;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Facades\DB;

/**
 * Gemeinsame Idempotenz-Grundform der Stripe-Verarbeitung (at-least-once):
 * innerhalb einer Transaktion die betroffene Zeile per Primärschlüssel neu
 * laden und sperren, bevor der Idempotenz-Guard geprüft und die Mutation
 * ausgeführt wird. So serialisieren parallele Webhook-Zustellungen, statt beide
 * denselben „noch nicht verarbeitet"-Zustand zu lesen.
 *
 * Deckt die häufige Form ab (Entity per Key sperren). Pfade mit abweichender
 * Sperrstrategie (z. B. Lock auf der User-Zeile oder Unique-Constraint-Catch)
 * bleiben bewusst eigenständig.
 */
trait LocksModelForUpdate
{
    /**
     * @template TModel of Model
     * @template TReturn
     *
     * @param  TModel  $model
     * @param  Closure(TModel): TReturn  $callback
     * @return TReturn|null Ergebnis des Callbacks, oder null, wenn die Zeile
     *                      zwischenzeitlich verschwunden ist.
     */
    protected function withLockedByKey(Model $model, Closure $callback): mixed
    {
        return DB::transaction(function () use ($model, $callback) {
            $locked = $model->newQuery()
                ->whereKey($model->getKey())
                ->lockForUpdate()
                ->first();

            if ($locked === null) {
                return null;
            }

            return $callback($locked);
        });
    }
}