Zahlungsparser

app/EventPaymentModules/ReadsBankStatements.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace App\EventPaymentModules;
+
+use App\EventPaymentModules\DTO\TransactionMatch;
+use App\Models\EventParticipant;
+use App\ValueObjects\BankTransaction;
+use Illuminate\Support\Collection;
+
+/**
+ * Fähigkeit: Dieses Zahlungsmodul kann Umsätze eines Kontoauszugs verwerten.
+ *
+ * Hier stecken die drei Entscheidungen, die von der Zahlungsart abhängen -- und nur diese:
+ * was zählt, wem es gehört, was nachgetragen wird. Der Ablauf drumherum (Upload, Parsen, Kandidaten
+ * laden, Wasserzeichen, `amount_paid` fortschreiben, Mail) ist zahlartneutral und liegt in der Action.
+ *
+ * Die Überweisung erkennt Gutschriften am Verwendungszweck; eine SEPA-Lastschrift wird später
+ * Belastungen und Rücklastschriften über die Mandatsreferenz erkennen -- gleiche Datei, andere Regeln.
+ */
+interface ReadsBankStatements
+{
+    /** Interessiert dieser Umsatz diese Zahlungsart? */
+    public function isRelevantTransaction(BankTransaction $transaction): bool;
+
+    /**
+     * Zu welcher Anmeldung gehört der Umsatz?
+     *
+     * `null`, wenn keine oder mehrere passen -- ein unsicherer Vorschlag wäre schlimmer als keiner,
+     * weil er in der Prüfansicht bloß durchgewinkt würde.
+     *
+     * @param Collection<int, EventParticipant> $candidates fertig geladen; hier wird nichts abgefragt
+     */
+    public function matchTransaction(BankTransaction $transaction, Collection $candidates): ?TransactionMatch;
+
+    /**
+     * Trägt die zahlartspezifischen Spuren des Umsatzes an der Anmeldung ein.
+     *
+     * Setzt nur die Attribute, **speichert nicht** -- gespeichert wird einmal am Ende durch die Action,
+     * zusammen mit dem Betrag.
+     */
+    public function recordTransaction(EventParticipant $participant, BankTransaction $transaction): void;
+}