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

    /**
     * Options-Schema dieses Moduls (welche Konfigurationsfelder es benötigt).
     *
     * @return array<int, array{name: string, label: string, type: string, required: bool}>
     */
    public function getOptions(): 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;
}