feat(payments): Anbieter-Gerüst core/payments mit PayPal Orders v2

- ProviderInterface/AbstractProvider: Vorgang mit Uhrzeit+Session (payment_transactions), Mail und Warenkorb erst nach Zahlung, idempotentes markPaid, Betragsabgleich, shop_event + PG payment_log - Secrets verschluesselt (libsodium) in MySQL, Schluessel ausserhalb Docroot - Cashdesk: ?payment_return/?payment_cancel, Pending-Riegel, zahlung_erst_spaeter() - Backend Zahlart-Editor: Einstellungen speichern (war ohne Empfaenger), Secret-Felder - payment_webhook.php (Standalone), cli.php (init-key, secret, reconcile, status) - PayPal-v2-Blaupause vom Juli entfernt
2026-09-13 19:51:52 +02:00
parent af81e8f63a
commit 397fb5944a
30 changed files with 2002 additions and 1104 deletions
@@ -0,0 +1,70 @@
+<?php
+declare(strict_types=1);
+
+namespace Payments;
+
+/**
+ * Vertrag fuer Zahlungsanbieter mit Weiterleitung (PayPal v2, spaeter Amazon Pay,
+ * Mollie, Klarna Payments ...).
+ *
+ * Lebenszyklus einer Zahlung:
+ *   1. Cashdesk legt die Shop-Bestellung an (Zahlstatus offen).
+ *   2. start()      -> Zahlung beim Anbieter anlegen, Kunde per 302 weiterleiten.
+ *   3. onReturn()   -> Kunde kommt zurueck: Zahlung abschliessen, Bestellung bezahlt setzen.
+ *      onCancel()   -> Kunde hat abgebrochen: Bestellung stornieren, Warenkorb bleibt.
+ *   4. onWebhook()  -> Anbieter meldet serverseitig (unabhaengig vom Kunden).
+ *   5. reconcile()  -> Cron: haengende Vorgaenge beim Anbieter nachfragen.
+ *
+ * Alles, was fuer alle Anbieter gleich ist (Mail erst nach Zahlung, Warenkorb erst
+ * nach Zahlung, Ereignisprotokoll, Betragsabgleich), lebt in AbstractProvider.
+ */
+interface ProviderInterface
+{
+    /** Technischer Name = payment_methods.module = Konfigurationsgruppe, z.B. 'paypal_v2'. */
+    public function module(): string;
+
+    /** Anzeigename fuers Backend und Protokoll. */
+    public function label(): string;
+
+    /** true: die Bestellung ist erst nach Rueckkehr vom Anbieter bezahlt (Mail/Warenkorb warten). */
+    public function paysAfterRedirect(): bool;
+
+    /**
+     * Zahlung anlegen und Weiterleitungs-URL liefern.
+     *
+     * @param  int   $orderId   Shop-Bestellung (orders.id)
+     * @param  float $amount    zu zahlender Bruttobetrag (nach Gutschein)
+     * @return string           URL, zu der der Kunde geschickt wird
+     * @throws \RuntimeException wenn der Anbieter nicht erreichbar ist oder ablehnt
+     */
+    public function start(int $orderId, float $amount): string;
+
+    /**
+     * Rueckkehr des Kunden vom Anbieter.
+     * @param  array<string,mixed> $query  $_GET der Rueckkehr-URL
+     */
+    public function onReturn(array $query): Result;
+
+    /** @param array<string,mixed> $query */
+    public function onCancel(array $query): Result;
+
+    /**
+     * Server-zu-Server-Nachricht des Anbieters.
+     * @param  array<string,string> $headers  Request-Header, Schluessel kleingeschrieben
+     * @return int HTTP-Status, den der Endpunkt zurueckgeben soll (2xx = angenommen)
+     */
+    public function onWebhook(array $headers, string $rawBody): int;
+
+    /**
+     * Haengende Vorgaenge nachziehen (Cron). Liefert eine kurze Zusammenfassung je Vorgang.
+     * @return list<string>
+     */
+    public function reconcile(bool $dryRun = true): array;
+
+    /**
+     * Felder fuer den Zahlart-Editor im Backend, die NICHT in `configuration` liegen,
+     * sondern verschluesselt (Secrets). name => Beschriftung.
+     * @return array<string,string>
+     */
+    public function secretFields(): array;
+}