<?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;
}