<?php

namespace App\EventPaymentModules;

use App\EventPaymentModules\DTO\CreateInvoiceRequest;
use App\EventPaymentModules\DTO\CreateInvoiceResponse;
use App\EventPaymentModules\DTO\DoPaymentRequest;
use App\EventPaymentModules\DTO\DoPaymentResponse;
use App\EventPaymentModules\DTO\GetRefundDataRequest;
use App\EventPaymentModules\DTO\GetRefundDataResponse;
use App\EventPaymentModules\DTO\RegistrationSummaryRequest;
use App\EventPaymentModules\DTO\RegistrationSummaryResponse;

/**
 * Vertrag eines Zahlungsmoduls. Jede Zahlungsart (Überweisung, künftig SEPA-Lastschrift, PayPal, ...)
 * kapselt ihr Verhalten in einer eigenen Implementierung. Aufgelöst wird ein Modul über seinen Slug
 * via {@see EventPaymentModuleRegistry}.
 *
 * Die operativen Methoden (doPayment/createInvoice/registrationSummary) arbeiten mit geteilten
 * Request/Response-DTOs -- das Modul stellt die polymorphe "Command"-Logik; schwere Arbeit
 * (PayPal-API, SEPA-XML) wird später an reguläre Domain-Actions delegiert.
 */
interface EventPaymentModule
{
    /** Eindeutiger Slug der Zahlungsart (entspricht payment_methods.slug). */
    public static function slug(): string;

    /** Standard-Anzeigename beim Anlegen der Tenant-Instanz. */
    public function defaultName(): string;

    /** Standard-Beschreibung beim Anlegen der Tenant-Instanz. */
    public function defaultDescription(): ?string;

    /**
     * Standard-Konfiguration beim Anlegen der Tenant-Instanz (z.B. Default-Symbol). Standard: leer.
     *
     * @return array<string, mixed>
     */
    public function defaultConfiguration(): array;

    /**
     * Admin-Options-Schema dieses Moduls (welche Konfigurationsfelder der/die Veranstalter\*in pflegt).
     *
     * @return array<int, array{name: string, label: string, type: string, required: bool}>
     */
    public function getOptions(): array;

    /**
     * Teilnehmer-Eingaben, die diese Zahlungsart beim Anmelden abfragt (payer-seitig; Standard: keine).
     *
     * @return array<int, array{name: string, label: string, type: string, required: bool}>
     */
    public function getParticipantOptions(): array;

    /**
     * Liefert den zahlungsspezifischen Teil der Anmelde-Zusammenfassung.
     * (In dieser Iteration nur als Stub vorhanden.)
     */
    public function registrationSummary(RegistrationSummaryRequest $request): RegistrationSummaryResponse;

    /**
     * Stößt die Zahlung an (bzw. beschreibt, was zu tun ist -- z.B. Redirect, Lastschrift, manuelle Überweisung).
     * (In dieser Iteration nur als Stub vorhanden.)
     */
    public function doPayment(DoPaymentRequest $request): DoPaymentResponse;

    /**
     * Erzeugt die Rechnung/Zahlungsaufforderung. Der gemeinsame Rumpf kommt aus der Basisklasse,
     * nur der Schlusssatz variiert je Modul.
     * (In dieser Iteration nur als Stub vorhanden.)
     */
    public function createInvoice(CreateInvoiceRequest $request): CreateInvoiceResponse;

    /**
     * Auf welches Konto wäre zu erstatten -- und wissen wir es überhaupt?
     *
     * Gehört ins Kern-Interface und nicht in ein Fähigkeits-Interface, weil jede Zahlungsart eine
     * Antwort darauf hat; sie fällt nur unterschiedlich aus. Barzahlung: keine. Überweisung: das
     * Konto, von dem der Beitrag kam. SEPA-Lastschrift später: das Konto des Mandats.
     *
     * Standard ist „nicht bekannt" -- dann läuft die Erstattung wie gehabt über die Angaben des
     * Teilis bzw. der Aktionsleitung.
     */
    public function getRefundData(GetRefundDataRequest $request): GetRefundDataResponse;
}