Creating Participation refunds

app/Models/DocumentTemplate.php

@@ -19,13 +19,15 @@ class DocumentTemplate extends CommonModel
 {
     public const string TYPE_PARTICIPANT_INVOICE = 'participant_invoice';
 
+    public const string TYPE_PARTICIPANT_REFUND = 'participant_refund';
+
     /** Seitengerüst -- enthält die `{block:...}`-Platzhalter und bestimmt damit die Anordnung. */
     public const string BLOCK_LAYOUT = 'layout';
 
     /** CSS des Dokuments. */
     public const string BLOCK_STYLE = 'style';
 
-    /** Der generierte Teil (Positionstabelle, Summen, Schlusssatz) -- nicht editierbar. */
+    /** Der Inhaltsblock. Bei der Rechnung generiert und gesperrt, beim Erstattungsbeleg pflegbar. */
     public const string BLOCK_BODY = 'body';
 
     protected $table = 'document_templates';

app/Models/DocumentTypeCatalog.php

@@ -0,0 +1,125 @@
+<?php
+
+namespace App\Models;
+
+use App\Domains\ParticipantInvoice\ParticipantInvoiceTokens;
+use App\Domains\ParticipantRefund\ParticipantRefundTokens;
+
+/**
+ * Was die Vorlagen-Verwaltung über eine Dokumentart wissen muss: wie sie heißt, welche Platzhalter es
+ * gibt und wie die Blöcke im Formular beschriftet sind.
+ *
+ * Die eine Stelle, an der eine neue Dokumentart eingetragen wird -- Controller und Formular lesen von
+ * hier und kennen selbst keine Dokumentart mehr.
+ */
+final class DocumentTypeCatalog
+{
+    /** Blöcke, die Layout-HTML bzw. CSS enthalten und deshalb im Quelltext-Editor gepflegt werden. */
+    public const array SOURCE_BLOCKS = [
+        DocumentTemplate::BLOCK_LAYOUT,
+        DocumentTemplate::BLOCK_STYLE,
+    ];
+
+    /**
+     * Die Beschriftungen der Blöcke, die jede Dokumentart hat -- Seitengerüst, Gestaltung und der
+     * Briefkopf des Verbands.
+     *
+     * @var array<string, string>
+     */
+    private const array COMMON_BLOCK_LABELS = [
+        DocumentTemplate::BLOCK_LAYOUT => 'Seitengerüst',
+        DocumentTemplate::BLOCK_STYLE => 'Gestaltung (CSS)',
+        'header_sender_return' => 'Rücksendezeile',
+        'header_recipient' => 'Empfängeranschrift',
+        'emblem' => 'Emblem',
+        'logo' => 'Logo',
+        'sender_data' => 'Absenderangaben',
+        'subject' => 'Betreff und Referenzdaten',
+    ];
+
+    /**
+     * @return array<string, array{label: string, tokens: class-string, blockLabels: array<string, string>}>
+     */
+    public static function all(): array
+    {
+        return [
+            DocumentTemplate::TYPE_PARTICIPANT_INVOICE => [
+                'label' => 'Teilnahmerechnung',
+                'tokens' => ParticipantInvoiceTokens::class,
+                'blockLabels' => self::COMMON_BLOCK_LABELS + [
+                    DocumentTemplate::BLOCK_BODY => 'Rechnungsinhalt',
+                    'footer' => 'Grußformel und Fußnote',
+                ],
+            ],
+            DocumentTemplate::TYPE_PARTICIPANT_REFUND => [
+                'label' => 'Erstattungsbeleg',
+                'tokens' => ParticipantRefundTokens::class,
+                'blockLabels' => self::COMMON_BLOCK_LABELS + [
+                    DocumentTemplate::BLOCK_BODY => 'Erklärung und Angaben zur Erstattung',
+                    'footer' => 'Fußbereich',
+                ],
+            ],
+        ];
+    }
+
+    public static function has(string $documentType): bool
+    {
+        return array_key_exists($documentType, self::all());
+    }
+
+    /** Die Dokumentart, oder null wenn sie nicht im Katalog steht. */
+    public static function get(string $documentType): ?array
+    {
+        return self::all()[$documentType] ?? null;
+    }
+
+    public static function default(): string
+    {
+        return DocumentTemplate::TYPE_PARTICIPANT_INVOICE;
+    }
+
+    public static function blockLabel(string $documentType, string $block): string
+    {
+        return self::get($documentType)['blockLabels'][$block] ?? $block;
+    }
+
+    /**
+     * Platzhalter-Gruppen der Dokumentart -- für die Liste im Formular.
+     *
+     * @return array<string, array<string, mixed>>
+     */
+    public static function tokenGroups(string $documentType): array
+    {
+        $tokens = self::get($documentType)['tokens'] ?? null;
+
+        return $tokens === null ? [] : $tokens::groups();
+    }
+
+    /**
+     * Beispielwerte der Dokumentart -- für die Vorschau.
+     *
+     * @return array<string, string>
+     */
+    public static function sampleTokens(string $documentType): array
+    {
+        $tokens = self::get($documentType)['tokens'] ?? null;
+
+        return $tokens === null ? [] : $tokens::sample();
+    }
+
+    /**
+     * Die Auswahl für den Umschalter im Formular.
+     *
+     * @return array<int, array{value: string, label: string}>
+     */
+    public static function options(): array
+    {
+        $options = [];
+
+        foreach (self::all() as $type => $definition) {
+            $options[] = ['value' => $type, 'label' => $definition['label']];
+        }
+
+        return $options;
+    }
+}

app/Models/ParticipantRefund.php

@@ -0,0 +1,105 @@
+<?php
+
+namespace App\Models;
+
+use App\Casts\AmountCast;
+use App\Enumerations\RefundReason;
+use App\Scopes\InstancedModel;
+use App\ValueObjects\Amount;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * Ein Erstattungsvorgang zu einer Anmeldung.
+ *
+ * @property int $id
+ * @property string $tenant
+ * @property int $event_id
+ * @property int $event_participant_id
+ * @property string $token
+ * @property string $status
+ * @property Amount|null $amount
+ * @property string|null $reason
+ * @property string|null $reason_note
+ * @property string|null $account_owner
+ * @property string|null $account_iban
+ * @property int|null $released_by
+ * @property \Illuminate\Support\Carbon|null $released_at
+ * @property \Illuminate\Support\Carbon|null $accepted_at
+ * @property \Illuminate\Support\Carbon|null $cancelled_at
+ */
+class ParticipantRefund extends InstancedModel
+{
+    /** Freigegeben, wartet auf die Bankverbindung des Teilis. */
+    public const string STATUS_PENDING = 'pending';
+
+    /** Der Teili hat bestätigt, der Beleg ist erstellt. Ab hier unveränderlich. */
+    public const string STATUS_ACCEPTED = 'accepted';
+
+    /** Von der Aktionsleitung abgebrochen, bevor der Teili bestätigt hat. */
+    public const string STATUS_CANCELLED = 'cancelled';
+
+    protected $table = 'participant_refunds';
+
+    protected $fillable = [
+        'tenant',
+        'event_id',
+        'event_participant_id',
+        'token',
+        'status',
+        'amount',
+        'reason',
+        'reason_note',
+        'account_owner',
+        'account_iban',
+        'released_by',
+        'released_at',
+        'accepted_at',
+        'cancelled_at',
+    ];
+
+    protected $casts = [
+        'amount' => AmountCast::class,
+        'released_at' => 'datetime',
+        'accepted_at' => 'datetime',
+        'cancelled_at' => 'datetime',
+    ];
+
+    public function participant(): BelongsTo
+    {
+        return $this->belongsTo(EventParticipant::class, 'event_participant_id');
+    }
+
+    public function event(): BelongsTo
+    {
+        return $this->belongsTo(Event::class);
+    }
+
+    /**
+     * Der Grund als Stammdatensatz. Nicht `reason()`, weil das die Spalte `reason` verdecken würde.
+     */
+    public function reasonRelation(): BelongsTo
+    {
+        return $this->belongsTo(RefundReason::class, 'reason', 'slug');
+    }
+
+    public function isPending(): bool
+    {
+        return $this->status === self::STATUS_PENDING;
+    }
+
+    public function isAccepted(): bool
+    {
+        return $this->status === self::STATUS_ACCEPTED;
+    }
+
+    /** Der auf dem Beleg auszuweisende Grundtext -- bei Freitext-Gründen der Text der Aktionsleitung. */
+    public function reasonText(): string
+    {
+        return $this->reasonRelation()->first()?->documentText($this->reason_note) ?? '';
+    }
+
+    public function reasonLabel(): string
+    {
+        return (string) ($this->reasonRelation()->first()?->name ?? '');
+    }
+}