mivita/app/Services/Payment/Stripe/StripeInvoiceReferenceService.php

<?php

namespace App\Services\Payment\Stripe;

use App\Jobs\SyncStripeInvoiceReference;
use App\Models\ShoppingOrder;
use App\Models\ShoppingPayment;
use App\Models\UserInvoice;
use App\Services\Invoice;
use Illuminate\Support\Facades\Log;

/**
 * Trägt die MIVITA-Rechnungsnummer nachträglich an der Stripe-Zahlung ein
 * (Plan dev/2026-08-26-stripe/, Phase SE3).
 *
 * Warum nachträglich: Die Rechnungsnummer kommt aus einem fortlaufenden
 * Nummernkreis ({@see Invoice::makeNextInvoiceNumber}) und wird
 * erst NACH erfolgreicher Zahlung vergeben. Eine Vorab-Reservierung würde bei
 * jedem abgebrochenen Checkout eine Lücke im Rechnungsnummernkreis erzeugen —
 * das ist buchhalterisch (GoBD) nicht zulässig.
 *
 * Stripe erlaubt es, Metadaten und `description` eines PaymentIntents
 * jederzeit zu ändern. Genau das passiert hier — damit die Buchhaltung die
 * Zahlung im Dashboard über die Rechnungsnummer findet und die Nummer als
 * Spalte in den Bilanz-/Auszahlungsberichten exportieren kann.
 */
class StripeInvoiceReferenceService
{
    public function __construct(private readonly StripeClientWrapper $stripe) {}

    /**
     * Stößt die Übertragung für eine Bestellung an — ohne den Aufrufer zu
     * gefährden. Wird aus dem Paid-Pfad und aus der manuellen
     * Rechnungserstellung im Admin aufgerufen.
     */
    public static function dispatchForOrder(ShoppingOrder $shoppingOrder, ?ShoppingPayment $shoppingPayment = null): void
    {
        try {
            $userInvoice = $shoppingOrder->user_invoice;
            if (! $userInvoice) {
                return;
            }

            $payment = $shoppingPayment ?: $shoppingOrder->shopping_payments()
                ->where('payment_provider', 'stripe')
                ->latest('id')
                ->first();

            if (! self::isSyncable($payment)) {
                return;
            }

            SyncStripeInvoiceReference::dispatch($payment, $userInvoice);
        } catch (\Throwable $e) {
            // Der Paid-Pfad darf hieran niemals scheitern.
            Log::channel('stripe')->warning('Rechnungsnummer-Sync konnte nicht eingeplant werden: '.$e->getMessage(), [
                'shopping_order_id' => $shoppingOrder->id,
            ]);
        }
    }

    /**
     * Nur Stripe-Zahlungen mit bekanntem PaymentIntent lassen sich ergänzen.
     * Solange nur die Session-ID (`cs_…`) bekannt ist, gibt es kein Objekt,
     * an dem die Nummer dauerhaft sichtbar wäre.
     */
    public static function isSyncable(?ShoppingPayment $payment): bool
    {
        return $payment !== null
            && $payment->payment_provider === 'stripe'
            && str_starts_with((string) $payment->external_reference, 'pi_');
    }

    /**
     * Schreibt Rechnungsnummer und -datum in die Metadaten des PaymentIntents
     * und ergänzt die `description` um die Rechnungsnummer.
     *
     * Idempotent: steht die Nummer schon dort, passiert nichts.
     */
    public function sync(ShoppingPayment $shoppingPayment, UserInvoice $userInvoice): bool
    {
        if (! self::isSyncable($shoppingPayment)) {
            return false;
        }

        $client = $this->stripe->client();
        $paymentIntent = $client->paymentIntents->retrieve($shoppingPayment->external_reference);

        $existing = $paymentIntent->metadata?->toArray() ?? [];

        if (($existing['invoice_number'] ?? null) === $userInvoice->full_number) {
            return false;
        }

        $order = $shoppingPayment->shopping_order;

        $client->paymentIntents->update($shoppingPayment->external_reference, [
            'metadata' => StripeMetadataBuilder::withInvoice($existing, $userInvoice),
            'description' => StripeMetadataBuilder::description(
                $order,
                (string) $shoppingPayment->reference,
                $order?->shopping_user,
            ),
        ]);

        Log::channel('stripe')->info('Rechnungsnummer an Stripe übertragen.', [
            'shopping_payment_id' => $shoppingPayment->id,
            'payment_intent' => $shoppingPayment->external_reference,
            'invoice_number' => $userInvoice->full_number,
        ]);

        return true;
    }
}