Prepared new versio

app/Domains/Admin/Controllers/UserDetailGetController.php

@@ -23,7 +23,7 @@ class UserDetailGetController extends CommonController
 
         return response()->json([
             'user' => $userData,
-            'isOwnUser' => auth()->id() === $user->id,
+            'isOwnUser' => currentUser()?->id === $user->id,
             'isLvTenant' => $this->tenant->slug === 'lv',
             'userRoles' => UserRole::all()->map(fn($role) => ['slug' => $role->slug, 'name' => $role->name]),
             'localGroups' => $this->adminTenants->getActiveLocalGroups()->map(fn($t) => ['slug' => $t->slug, 'name' => $t->name]),

app/Domains/Admin/Controllers/UserToggleActiveController.php

@@ -16,7 +16,7 @@ class UserToggleActiveController extends CommonController
 
         $action = new ToggleUserActiveAction(new ToggleUserActiveRequest(
             user: $user,
-            currentUserId: auth()->id(),
+            currentUserId: currentUser()?->id,
         ));
 
         $response = $action->execute();

app/Domains/Admin/Controllers/UserUpdateController.php

@@ -17,7 +17,7 @@ class UserUpdateController extends CommonController
         $action = new UpdateUserAction(new UpdateUserRequest(
             user: $user,
             data: $request->all(),
-            isOwnUser: auth()->id() === $user->id,
+            isOwnUser: currentUser()?->id === $user->id,
             isLvTenant: $this->tenant->slug === 'lv',
         ));
 

app/Domains/Budget/Actions/CreateEstimate/CreateEstimateAction.php

@@ -25,7 +25,7 @@ class CreateEstimateAction {
 
         if ($this->request->estimateId === 0) {
             $estimate = CostUnitEstimate::create(array_merge([
-                'tenant' => app('tenant')->slug,
+                'tenant' => currentTenant()->slug,
                 'cost_unit_id' => $this->request->costUnit->id,
                 'type' => $this->request->estimateType,
                 'description' => $this->request->description,
@@ -33,7 +33,7 @@ class CreateEstimateAction {
         } else {
             $estimate = CostUnitEstimate::find($this->request->estimateId);
             $estimate->update(array_merge([
-                'tenant' => app('tenant')->slug,
+                'tenant' => currentTenant()->slug,
                 'cost_unit_id' => $this->request->costUnit->id,
                 'type' => $this->request->estimateType,
                 'description' => $this->request->description,

app/Domains/CostUnit/Actions/CreateCostUnit/CreateCostUnitCommand.php

@@ -15,7 +15,7 @@ class CreateCostUnitCommand {
         $response = new CreateCostUnitResponse();
         $costUnit = CostUnit::create([
             'name' => $this->request->name,
-            'tenant' => app('tenant')->slug,
+            'tenant' => currentTenant()->slug,
             'type' => $this->request->type,
             'billing_deadline' => $this->request->billingDeadline,
             'distance_allowance' => $this->request->distanceAllowance->getAmount(),

app/Domains/Dashboard/Controllers/PersonalDataController.php

@@ -13,7 +13,7 @@ class PersonalDataController extends CommonController
             return redirect()->intended('/login');
         }
 
-        $user = auth()->user();
+        $user = currentUser();
         $data = $this->users->getPersonalData($user);
 
         $inertiaProvider = new InertiaProvider('Dashboard/PersonalData', [

app/Domains/Dashboard/Controllers/StorePersonalDataController.php

@@ -12,7 +12,7 @@ class StorePersonalDataController extends CommonController
 {
     public function __invoke(Request $request): JsonResponse
     {
-        $user = auth()->user();
+        $user = currentUser();
 
         $actionRequest = new UpdatePersonalDataRequest(
             user:               $user,

app/Domains/Event/Actions/CreateEvent/CreateEventCommand.php

@@ -28,7 +28,7 @@ class CreateEventCommand {
         }
 
 
-        $tenant = app('tenant');
+        $tenant = currentTenant();
 
         // Anlage als Ganzes: der Event-Teil der Rechnungsnummer wird unter der Sperre vergeben und muss
         // im selben Zug geschrieben werden, sonst könnten zwei gleichzeitige Anlagen denselben erhalten.
@@ -91,12 +91,12 @@ class CreateEventCommand {
                 ]);
             }
 
-            if (app('tenant')->slug === 'lv') {
+            if (currentTenant()->slug === 'lv') {
                 foreach(Tenant::where(['is_active_local_group' => true])->get() as $tenant) {
                     EventLocalGroups::create(['event_id' => $event->id, 'local_group_id' => $tenant->id]);
                 }
             } else {
-                EventLocalGroups::create(['event_id' => $event->id, 'local_group_id' => app('tenant')->id]);
+                EventLocalGroups::create(['event_id' => $event->id, 'local_group_id' => currentTenant()->id]);
             }
 
 

app/Domains/Event/Actions/CreateIncomeSurplusStatement/CreateIncomeSurplusStatementCommand.php

@@ -0,0 +1,224 @@
+<?php
+
+namespace App\Domains\Event\Actions\CreateIncomeSurplusStatement;
+
+use App\Enumerations\ParticipationType;
+use App\Models\CostUnit;
+use App\Models\Event;
+use App\Providers\PdfGenerateAndDownloadProvider;
+use App\Repositories\CostUnitRepository;
+use App\ValueObjects\Amount;
+use Illuminate\Http\Request;
+
+/**
+ * Erzeugt die Einnahmen-Überschuss-Rechnung einer Veranstaltung als PDF.
+ *
+ * Gezeigt wird ausschließlich Geld, das geflossen ist: gezahlte Beiträge, weitere Einnahmen, was von
+ * Abmeldungen einbehalten wurde, Fördermittel -- und auf der anderen Seite die erfassten Belege. Was nur
+ * erwartet (offene Beiträge) oder geplant (Budgetwerte) ist, gehört in eine Einnahmen-Überschuss-Rechnung
+ * nicht hinein.
+ *
+ * Es wird nichts gespeichert: Alle Zahlen leiten sich aus dem aktuellen Stand ab, ein erneuter Abruf
+ * liefert den dann gültigen Stand.
+ */
+class CreateIncomeSurplusStatementCommand
+{
+    private Event $event;
+
+    private CostUnitRepository $costUnits;
+
+    public function __construct(private readonly CreateIncomeSurplusStatementRequest $request)
+    {
+        $this->event = $request->event;
+        $this->costUnits = new CostUnitRepository();
+    }
+
+    public function execute(): CreateIncomeSurplusStatementResponse
+    {
+        $response = new CreateIncomeSurplusStatementResponse();
+
+        $costUnit = $this->event->costUnit()->first();
+
+        if (!$costUnit instanceof CostUnit) {
+            $response->message = 'Der Veranstaltung ist keine Kostenstelle zugeordnet.';
+
+            return $response;
+        }
+
+        // Der Pauschalbetrag wird vor dem Resource-Aufruf gelesen: `EventResource::calculateSupportPerPerson()`
+        // multipliziert das Amount-Objekt von `support_per_person` in place. Auf `support_flat` wirkt das
+        // zwar nicht, aber der gesamte Zugriff auf Beträge des Models ist danach nicht mehr vertrauenswürdig.
+        $otherIncome = $this->event->support_flat->getAmount();
+
+        $eventData = $this->event->toResource()->toArray(new Request());
+
+        $income = $this->buildIncome($eventData, $otherIncome);
+        $expenses = $this->buildExpenses($costUnit);
+
+        $result = new Amount($income['total']->getAmount() - $expenses['total']->getAmount(), 'Euro');
+
+        $html = view('pdfs.income-surplus-statement', [
+            'event' => $this->event,
+            'createdAt' => new \DateTime()->format('d.m.Y'),
+            'income' => $income,
+            'expenses' => $expenses,
+            'result' => $result,
+            'money' => self::money(...),
+        ])->render();
+
+        $response->success = true;
+        $response->filename = 'EUER-' . $this->event->identifier . '.pdf';
+        $response->income = $income;
+        $response->expenses = $expenses;
+        $response->result = $result;
+        $response->pdfContent = PdfGenerateAndDownloadProvider::fromHtml($html, 'portrait');
+
+        return $response;
+    }
+
+    /**
+     * Die Einnahmenseite in zwei Ober-Kategorien.
+     *
+     * Alle Zahlen stammen aus {@see \App\Resources\EventResource} -- derselben Quelle wie die
+     * Veranstaltungsübersicht am Bildschirm. Eine eigene Rechnung daneben würde über kurz oder lang von
+     * der Übersicht abweichen, und dann glaubt niemand mehr einer der beiden Zahlen.
+     *
+     * @param array<string, mixed> $eventData
+     *
+     * @return array{categories: array<int, array{name: string, total: Amount, entries: array<int, array{name: string, amount: Amount}>}>, total: Amount}
+     */
+    private function buildIncome(array $eventData, float $otherIncome): array
+    {
+        // Beiträge aller Teilnahmearten in einer Zeile: Für die Mittelverwendung zählt, was an Beiträgen
+        // hereingekommen ist, nicht von wem.
+        $participationFees = new Amount(0, 'Euro');
+        foreach ([
+            ParticipationType::PARTICIPATION_TYPE_PARTICIPANT,
+            ParticipationType::PARTICIPATION_TYPE_TEAM,
+            ParticipationType::PARTICIPATION_TYPE_VOLUNTEER,
+            ParticipationType::PARTICIPATION_TYPE_OTHER,
+        ] as $participationType) {
+            $participationFees->addAmount(
+                new Amount((float) $eventData['participants'][$participationType]['amount']['paid']['value'], 'Euro')
+            );
+        }
+
+        $ownFunds = [
+            ['name' => 'Teilnahmebeiträge', 'amount' => $participationFees],
+            ['name' => 'Weitere Einnahmen', 'amount' => new Amount($otherIncome, 'Euro')],
+            [
+                'name' => 'Einbehaltene Einnahmen aus Abmeldungen',
+                'amount' => new Amount((float) $eventData['retainedFromUnregistered']['value'], 'Euro'),
+            ],
+        ];
+
+        $supportRate = new Amount((float) $eventData['supportPersonValue'], 'Euro');
+        $funding = [
+            [
+                'name' => 'Fördermittel (' . self::money($supportRate) . ' € p.P./Tag)',
+                'amount' => new Amount($eventData['supportPerson']['amount']->getAmount(), 'Euro'),
+            ],
+        ];
+
+        $categories = [
+            ['name' => 'Eigenmittel', 'entries' => $ownFunds, 'total' => self::sum($ownFunds)],
+            ['name' => 'Förderungen', 'entries' => $funding, 'total' => self::sum($funding)],
+        ];
+
+        return [
+            'categories' => $categories,
+            'total' => self::sum($categories),
+        ];
+    }
+
+    /**
+     * Die Ausgabenseite: eine Zeile je Ausgabentyp, dazu die Belege für die Anlage.
+     *
+     * @return array{groups: array<int, array{name: string, sum: Amount, rows: array<int, array{number: string, date: string, purpose: string, amount: Amount}>}>, total: Amount}
+     */
+    private function buildExpenses(CostUnit $costUnit): array
+    {
+        $groups = [];
+        $total = new Amount(0, 'Euro');
+
+        foreach ($this->costUnits->groupExpensesByType($costUnit) as $group) {
+            $rows = [];
+
+            foreach ($group['invoices'] as $invoice) {
+                $rows[] = [
+                    'number' => (string) $invoice->invoice_number,
+                    'date' => $invoice->created_at?->format('d.m.Y') ?? '',
+                    'purpose' => $this->purpose($invoice->type_other, $invoice->comment),
+                    'amount' => Amount::fromString($invoice->amount),
+                ];
+            }
+
+            $groups[] = [
+                'name' => $group['type']->name,
+                'sum' => $group['sum'],
+                'rows' => $rows,
+            ];
+
+            $total->addAmount($group['sum']);
+        }
+
+        return ['groups' => $groups, 'total' => $total];
+    }
+
+    /**
+     * Wofür der Beleg steht.
+     *
+     * `type_other` trägt seit der Pflichtangabe "Was wurde eingekauft" zu jeder Abrechnung den Zweck,
+     * nicht mehr nur bei "Sonstige Kosten". Ältere Belege haben das Feld leer -- dann bleibt die
+     * Anmerkung, und fehlt auch die, bleibt die Zelle leer. Ein Platzhalter wie "--" würde in der
+     * Belegliste nur Platz kosten.
+     */
+    private function purpose(?string $typeOther, ?string $comment): string
+    {
+        $parts = [];
+
+        foreach ([$typeOther, $comment] as $part) {
+            if (trim((string) $part) !== '') {
+                $parts[] = trim((string) $part);
+            }
+        }
+
+        return implode(' — ', $parts);
+    }
+
+    /**
+     * Ein Betrag in deutscher Schreibweise: Punkt als Tausender-, Komma als Dezimaltrennzeichen.
+     *
+     * Bewusst nicht {@see Amount::getFormattedAmount()}: Die Methode ersetzt nach `number_format` jeden
+     * Punkt durch ein Komma und macht aus 1.487,50 damit "1,487,50". Auf einer Aufstellung, in der
+     * vierstellige Beträge die Regel sind, wäre das nicht lesbar. Der Fehler steckt im Value Object und
+     * wirkt überall, wo Beträge angezeigt werden -- ihn dort zu beheben ist eine eigene Änderung.
+     *
+     * Öffentlich, weil die Vorlage sie als Callable bekommt und weil sie für sich prüfbar sein soll.
+     */
+    public static function money(Amount $amount): string
+    {
+        return number_format(round($amount->getAmount(), 2), 2, ',', '.');
+    }
+
+    /**
+     * Summiert Zeilen, die je ein `amount` oder `total` tragen.
+     *
+     * Über ein frisches Amount-Objekt, weil `Amount::addAmount()` den Empfänger verändert -- die
+     * Einzelbeträge sollen unangetastet bleiben, sie werden anschließend gedruckt.
+     *
+     * @param array<int, array<string, mixed>> $rows
+     */
+    private static function sum(array $rows): Amount
+    {
+        $sum = new Amount(0, 'Euro');
+
+        foreach ($rows as $row) {
+            /** @var Amount $amount */
+            $amount = $row['amount'] ?? $row['total'];
+            $sum->addAmount($amount);
+        }
+
+        return $sum;
+    }
+}

app/Domains/Event/Actions/CreateIncomeSurplusStatement/CreateIncomeSurplusStatementRequest.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace App\Domains\Event\Actions\CreateIncomeSurplusStatement;
+
+use App\Models\Event;
+
+class CreateIncomeSurplusStatementRequest
+{
+    public function __construct(public readonly Event $event)
+    {
+    }
+}

app/Domains/Event/Actions/CreateIncomeSurplusStatement/CreateIncomeSurplusStatementResponse.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Domains\Event\Actions\CreateIncomeSurplusStatement;
+
+use App\ValueObjects\Amount;
+
+class CreateIncomeSurplusStatementResponse
+{
+    public bool $success = false;
+
+    public string $filename = '';
+
+    public string $pdfContent = '';
+
+    public ?string $message = null;
+
+    /**
+     * Die Zahlen, aus denen das PDF entsteht -- Einnahmen-Kategorien, Ausgaben-Gruppen und das Ergebnis.
+     *
+     * Sie stehen hier, weil sie das eigentliche Ergebnis der Action sind; das PDF ist nur ihre Darstellung.
+     * So lässt sich die Rechnung prüfen, ohne ein PDF zerlegen zu müssen.
+     *
+     * @var array{categories: array<int, array{name: string, total: Amount, entries: array<int, array{name: string, amount: Amount}>}>, total: Amount}|array{}
+     */
+    public array $income = [];
+
+    /**
+     * @var array{groups: array<int, array{name: string, sum: Amount, rows: array<int, array<string, mixed>>}>, total: Amount}|array{}
+     */
+    public array $expenses = [];
+
+    public ?Amount $result = null;
+}

app/Domains/Event/Actions/GenerateIcal/GenerateIcalCommand.php

@@ -13,7 +13,7 @@ class GenerateIcalCommand
         $participant = $this->request->participant;
         $event = $participant->event;
 
-        $uid = $participant->identifier . '@' . app('tenant')->slug;
+        $uid = $participant->identifier . '@' . currentTenant()->slug;
         $dtStart = $event->start_date->format('Ymd');
         $dtEnd = $event->end_date->copy()->addDay()->format('Ymd');
         $now = now()->format('Ymd\THis\Z');
@@ -24,7 +24,7 @@ class GenerateIcalCommand
         $icalContent = implode("\r\n", [
                 'BEGIN:VCALENDAR',
                 'VERSION:2.0',
-                'PRODID:-//' . app('tenant')->name . '//Veranstaltungskalender//DE',
+                'PRODID:-//' . currentTenant()->name . '//Veranstaltungskalender//DE',
                 'CALSCALE:GREGORIAN',
                 'METHOD:PUBLISH',
                 'BEGIN:VEVENT',

app/Domains/Event/Actions/GenerateIcalForDeadline/GenerateIcalForDeadlineCommand.php

@@ -21,11 +21,11 @@ class GenerateIcalForDeadlineCommand {
         $icalContent = implode("\r\n", [
                 'BEGIN:VCALENDAR',
                 'VERSION:2.0',
-                'PRODID:-//' . app('tenant')->name . '//Veranstaltungskalender//DE',
+                'PRODID:-//' . currentTenant()->name . '//Veranstaltungskalender//DE',
                 'CALSCALE:GREGORIAN',
                 'METHOD:PUBLISH',
                 'BEGIN:VEVENT',
-                'UID:payment-deadline-' . $event->identifier . '@' . app('tenant')->slug,
+                'UID:payment-deadline-' . $event->identifier . '@' . currentTenant()->slug,
                 'DTSTAMP:' . $now,
                 'DTSTART;VALUE=DATE:' . $dtDate,
                 'DTEND;VALUE=DATE:' . $dtDate,

app/Domains/Event/Actions/SetParticipationFees/SetParticipationFeesCommand.php

@@ -18,7 +18,7 @@ class SetParticipationFeesCommand {
         $this->cleanBefore();
 
         $this->request->event->participationFee1()->associate(EventParticipationFee::create([
-            'tenant' => app('tenant')->slug,
+            'tenant' => currentTenant()->slug,
             'type' => $this->request->participationFeeFirst['type'],
             'name' => $this->request->participationFeeFirst['name'],
             'description' => $this->request->participationFeeFirst['description'],
@@ -29,7 +29,7 @@ class SetParticipationFeesCommand {
 
         if ($this->request->participationFeeSecond !== null) {
             $this->request->event->participationFee2()->associate(EventParticipationFee::create([
-                'tenant' => app('tenant')->slug,
+                'tenant' => currentTenant()->slug,
                 'type' => $this->request->participationFeeSecond['type'],
                 'name' => $this->request->participationFeeSecond['name'],
                 'description' => $this->request->participationFeeSecond['description'],
@@ -41,7 +41,7 @@ class SetParticipationFeesCommand {
 
         if ($this->request->participationFeeThird !== null) {
             $this->request->event->participationFee3()->associate(EventParticipationFee::create([
-                'tenant' => app('tenant')->slug,
+                'tenant' => currentTenant()->slug,
                 'type' => $this->request->participationFeeThird['type'],
                 'name' => $this->request->participationFeeThird['name'],
                 'description' => $this->request->participationFeeThird['description'],
@@ -53,7 +53,7 @@ class SetParticipationFeesCommand {
 
         if ($this->request->participationFeeFourth !== null) {
             $this->request->event->participationFee4()->associate(EventParticipationFee::create([
-                'tenant' => app('tenant')->slug,
+                'tenant' => currentTenant()->slug,
                 'type' => $this->request->participationFeeFourth['type'],
                 'name' => $this->request->participationFeeFourth['name'],
                 'description' => $this->request->participationFeeFourth['description'],

app/Domains/Event/Controllers/CreateController.php

@@ -21,7 +21,7 @@ use Illuminate\Http\Request;
 class CreateController extends CommonController {
     public function __invoke() {
         return new InertiaProvider('Event/Create', [
-            'emailAddress' => auth()->user()->email,
+            'emailAddress' => currentUserOrFail()->email,
             'eventAccount' => $this->tenant->account_name,
             'eventIban' => $this->tenant->account_iban,
             'eventPayPerDay' => $this->tenant->slug === 'lv' ? true : false,

app/Domains/Event/Controllers/IncomeSurplusStatementController.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Domains\Event\Controllers;
+
+use App\Domains\Event\Actions\CreateIncomeSurplusStatement\CreateIncomeSurplusStatementCommand;
+use App\Domains\Event\Actions\CreateIncomeSurplusStatement\CreateIncomeSurplusStatementRequest;
+use App\Scopes\CommonController;
+use Illuminate\Http\Response;
+
+class IncomeSurplusStatementController extends CommonController
+{
+    public function __invoke(string $eventId): Response
+    {
+        $event = $this->events->getByIdentifier($eventId);
+
+        if ($event === null) {
+            abort(403, 'Zugriff verweigert.');
+        }
+
+        $statementRequest = new CreateIncomeSurplusStatementRequest($event);
+        $statementCommand = new CreateIncomeSurplusStatementCommand($statementRequest);
+        $statementResponse = $statementCommand->execute();
+
+        if (!$statementResponse->success) {
+            abort(422, $statementResponse->message ?? 'Die EÜR konnte nicht erstellt werden.');
+        }
+
+        return response($statementResponse->pdfContent, 200, [
+            'Content-Type' => 'application/pdf',
+            'Content-Disposition' => 'attachment; filename="' . $statementResponse->filename . '"',
+        ]);
+    }
+}

app/Domains/Event/Controllers/MailCompose/SendController.php

@@ -38,7 +38,7 @@ class SendController extends CommonController
             }
         }
 
-        $user = auth()->user();
+        $user = currentUser();
         $reportSubject = sprintf('Sendebericht für Nachricht mit Betreff "%s"', $subject);
 
         Mail::to($user->email)->send(new ManualMailsReportMail(

app/Domains/Event/Controllers/SignupController.php

@@ -35,8 +35,9 @@ class SignupController extends CommonController {
             'lastname' => '',
         ];
 
-        if (auth()->check()) {
+        $currentUser = currentUser();
-            $user = new UserResource(auth()->user())->toArray($request);
+        if ($currentUser !== null) {
+            $user = new UserResource($currentUser)->toArray($request);
 
             $participantData = [
                 'id' => $user['id'],

app/Domains/Event/Routes/web.php

@@ -4,6 +4,7 @@ use App\Domains\Event\Controllers\ArchivedEventsController;
 use App\Domains\Event\Controllers\AvailableEventsController;
 use App\Domains\Event\Controllers\CreateController;
 use App\Domains\Event\Controllers\DetailsController;
+use App\Domains\Event\Controllers\IncomeSurplusStatementController;
 use App\Domains\Event\Controllers\SignupController;
 use App\Middleware\IdentifyTenant;
 use Illuminate\Support\Facades\Route;
@@ -18,6 +19,10 @@ Route::middleware(IdentifyTenant::class)->group(function () {
 
         Route::middleware(['auth'])->group(function () {
             Route::get('/details/{eventId}', DetailsController::class);
+
+            // Vor der Wildcard darunter: Sonst greift `downloadPdfList()` und sucht ein Blade namens
+            // `income-surplus-statement` mit Teilnehmendendaten, die die EÜR gar nicht braucht.
+            Route::get('/details/{eventId}/pdf/income-surplus-statement', IncomeSurplusStatementController::class);
             Route::get('/details/{eventId}/pdf/{listType}', [DetailsController::class, 'downloadPdfList']);
             Route::get('/details/{eventId}/csv/{listType}', [DetailsController::class, 'downloadCsvList']);
         });

app/Domains/Event/Views/Partials/Overview.vue

@@ -106,6 +106,10 @@ async function showEventAddons() {
             <input type="button" value="Beitragsliste (PDF)" />
         </a><br/>
 
+        <a :href="'/event/details/' + props.data.event.identifier + '/pdf/income-surplus-statement'">
+            <input type="button" value="EüR (PDF)" />
+        </a><br/>
+
         <a :href="'/event/details/' + props.data.event.identifier + '/pdf/drinking-list'">
             <input type="button" value="Getränkeliste (PDF)" />
         </a><br/>
@@ -143,6 +147,10 @@ async function showEventAddons() {
                     <input type="button" value="Beitragsliste (PDF)" />
                 </a><br/>
 
+                <a :href="'/event/details/' + props.data.event.identifier + '/pdf/income-surplus-statement'">
+                    <input type="button" value="EüR (PDF)" />
+                </a><br/>
+
                 <a :href="'/event/details/' + props.data.event.identifier + '/pdf/drinking-list'">
                     <input type="button" value="Getränkeliste (PDF)" />
                 </a><br/>

app/Domains/Event/Views/Partials/ParticipantData.vue

@@ -388,6 +388,14 @@ function saveParticipant() {
                             <small v-else-if="props.participant.refund.status === 'accepted'">
                                 bestätigt am {{ props.participant.refund.acceptedAt }}
                             </small>
+
+                            <!-- Was beim Verband geblieben ist und warum. -->
+                            <small v-if="props.participant.refund.hasRetention" class="retention-note">
+                                <br />Einbehalten: {{ props.participant.refund.retainedAmount }} &ndash;
+                                {{ props.participant.refund.retentionReasonLabel }}<template
+                                    v-if="props.participant.refund.retentionReasonNote"
+                                > ({{ props.participant.refund.retentionReasonNote }})</template>
+                            </small>
                         </td>
                     </tr>
                 </table>
@@ -541,4 +549,8 @@ textarea {
 select {
     width: 262px;
 }
+
+.retention-note {
+    color: #8a6d00;
+}
 </style>

app/Domains/Event/Views/Partials/ParticipantsList.vue

@@ -51,15 +51,82 @@ const openRefundDialogSwitch = ref(false);
 // Der Erstattungsdialog. `captureMode` steuert den Weg: 'participant' schickt dem Teili einen Link, über
 // den er seine Bankverbindung selbst einträgt; 'management' heißt, sie liegt der Aktionsleitung bereits
 // vor -- dann wird die Erstattung sofort eingereicht.
-const refundForm = reactive({amount: '', reason: '', reasonNote: '', captureMode: 'participant', accountOwner: '', accountIban: ''});
+const refundForm = reactive({
+    amount: '', reason: '', reasonNote: '',
+    captureMode: 'participant', accountOwner: '', accountIban: '',
+    retentionReason: '', retentionReasonNote: '',
+});
 const refundErrors = reactive({amount: '', reason: '', reasonNote: '', accountOwner: '', accountIban: ''});
 const refundReasons = ref([]);
+const retentionReasons = ref([]);
 const refundSaving = ref(false);
 
 const selectedRefundReason = computed(
     () => refundReasons.value.find(r => r.value === refundForm.reason) ?? null
 );
 
+const selectedRetentionReason = computed(
+    () => retentionReasons.value.find(r => r.value === refundForm.retentionReason) ?? null
+);
+
+/** Was nach der Erstattung beim Verband bleibt -- die Grundlage für den Einbehaltungsblock. */
+const retainedAmount = computed(() => {
+    const paid = Number(showParticipant.value?.amountPaidValue ?? 0);
+    const refunded = Number((refundForm.amount ?? '').replace(',', '.'));
+
+    if (!Number.isFinite(refunded)) {
+        return 0;
+    }
+
+    const remaining = Math.round((paid - refunded) * 100) / 100;
+
+    return remaining > 0.005 ? remaining : 0;
+});
+
+const hasRetention = computed(() => retainedAmount.value > 0);
+
+const retainedAmountReadable = computed(
+    () => retainedAmount.value.toFixed(2).replace('.', ',') + ' Euro'
+);
+
+/**
+ * Ob abgesendet werden kann. Der Knopf erscheint erst dann -- was noch fehlt, soll die Aktionsleitung
+ * sehen, bevor sie klickt, statt danach eine Fehlermeldung zu lesen.
+ */
+const refundFormComplete = computed(() => {
+    const amount = Number((refundForm.amount ?? '').replace(',', '.'));
+    const paid = Number(showParticipant.value?.amountPaidValue ?? 0);
+
+    if (!refundForm.amount || !(amount > 0) || amount > paid + 0.005) {
+        return false;
+    }
+
+    if (!refundForm.reason) {
+        return false;
+    }
+
+    if (selectedRefundReason.value?.requiresNote && !refundForm.reasonNote.trim()) {
+        return false;
+    }
+
+    // Bleibt etwas beim Verband, muss begründet sein, warum.
+    if (hasRetention.value) {
+        if (!refundForm.retentionReason) {
+            return false;
+        }
+
+        if (selectedRetentionReason.value?.requiresNote && !refundForm.retentionReasonNote.trim()) {
+            return false;
+        }
+    }
+
+    if (refundForm.captureMode === 'management') {
+        return refundForm.accountOwner.trim() !== '' && refundForm.accountIban.trim() !== '';
+    }
+
+    return true;
+});
+
 defineEmits(['showParticipantDetails', 'markCocExisting', 'paymentComplete'])
 
 function openParticipantDetails(input) {
@@ -323,6 +390,8 @@ async function openRefundDialog(participant) {
     refundForm.captureMode = 'participant';
     refundForm.accountOwner = '';
     refundForm.accountIban = '';
+    refundForm.retentionReason = '';
+    refundForm.retentionReasonNote = '';
 
     Object.keys(refundErrors).forEach(key => refundErrors[key] = '');
 
@@ -331,6 +400,11 @@ async function openRefundDialog(participant) {
         refundReasons.value = reasons ?? [];
     }
 
+    if (retentionReasons.value.length === 0) {
+        const reasons = await request('/api/v1/core/retrieve-retention-reasons', {method: 'GET'});
+        retentionReasons.value = reasons ?? [];
+    }
+
     openRefundDialogSwitch.value = true;
 }
 
@@ -384,6 +458,9 @@ async function execRefund() {
                 // Leer beim Weg über den Teili -- dann verschickt der Server nur den Link.
                 accountOwner: refundForm.captureMode === 'management' ? refundForm.accountOwner : '',
                 accountIban: refundForm.captureMode === 'management' ? refundForm.accountIban : '',
+                // Leer bei voller Erstattung -- dann gibt es nichts zu begründen.
+                retentionReason: hasRetention.value ? refundForm.retentionReason : '',
+                retentionReasonNote: hasRetention.value ? refundForm.retentionReasonNote : '',
             },
         });
 
@@ -479,6 +556,15 @@ function mailToGroup(groupKey) {
                         <td class="pl-amount" :id="'participant-' + participant.identifier +'-payment'" :class="participant.amount_left_value != 0 && !participant.unregistered ? 'not-paid' : ''">
                             Gezahlt: <label :id="'participant-' + participant.identifier + '-paid'">{{ participant?.amountPaid.readable }}</label> /<br />
                             Gesamt: <label :id="'participant-' + participant.identifier + '-expected'">{{ participant?.amountExpected.readable }}</label>
+
+                            <!-- Warum ein Teil des Beitrags beim Verband geblieben ist. -->
+                            <span v-if="participant.refund?.hasRetention" class="retention-note">
+                                Einbehalten: {{ participant.refund.retainedAmount }}<br />
+                                {{ participant.refund.retentionReasonLabel }}<template
+                                    v-if="participant.refund.retentionReasonNote"
+                                > &ndash; {{ participant.refund.retentionReasonNote }}</template>
+                            </span>
+
                             <br /><br />
                             <span v-if="participant.amount_left_value != 0 && !participant.unregistered" :id="'participant-' + participant.identifier + '-actions'">
                                 <span class="link" style="font-size:10pt;" @click="paymentComplete(participant)">Zahlung buchen</span> &nbsp;
@@ -655,6 +741,36 @@ function mailToGroup(groupKey) {
             <ErrorText :message="refundErrors.reasonNote" />
         </div>
 
+        <!--
+            Bleibt ein Teil beim Verband, muss begründet sein, warum -- ein einbehaltener Betrag ohne
+            Grund ist in der Buchhaltung nicht haltbar. Bei voller Erstattung gibt es nichts zu zeigen.
+        -->
+        <template v-if="hasRetention">
+            <p class="refund-hint">
+                <strong>{{ retainedAmountReadable }}</strong> verbleiben beim Verband.
+            </p>
+
+            <div class="refund-field">
+                <label for="refund_retention_reason">Grund der Einbehaltung</label>
+                <select id="refund_retention_reason" v-model="refundForm.retentionReason" class="form-input">
+                    <option value="">Bitte auswählen …</option>
+                    <option v-for="reason in retentionReasons" :key="reason.value" :value="reason.value">
+                        {{ reason.label }}
+                    </option>
+                </select>
+            </div>
+
+            <div v-if="selectedRetentionReason?.requiresNote" class="refund-field">
+                <label for="refund_retention_note">Erläuterung zur Einbehaltung</label>
+                <textarea
+                    id="refund_retention_note"
+                    v-model="refundForm.retentionReasonNote"
+                    class="form-input"
+                    rows="3"
+                ></textarea>
+            </div>
+        </template>
+
         <!--
             Liegt die Bankverbindung schon vor, entfällt der Umweg über den Teili: die Erstattung wird
             sofort eingereicht. Er bekommt den Beleg trotzdem.
@@ -694,7 +810,13 @@ function mailToGroup(groupKey) {
             </p>
         </template>
 
-        <button class="button" :disabled="refundSaving" @click="execRefund()">
+        <!-- Erscheint erst, wenn alles ausgefüllt ist; während des Speicherns gesperrt statt weg. -->
+        <button
+            v-if="refundFormComplete"
+            class="button"
+            :disabled="refundSaving"
+            @click="execRefund()"
+        >
             <template v-if="refundSaving">Wird gespeichert…</template>
             <template v-else-if="refundForm.captureMode === 'management'">Erstattung einreichen</template>
             <template v-else>Erstattung freigeben</template>
@@ -749,6 +871,14 @@ function mailToGroup(groupKey) {
     margin-right: 6px;
 }
 
+.retention-note {
+    display: block;
+    margin-top: 6px;
+    font-size: 10pt;
+    color: #ca5a0a;
+    line-height: 1.4;
+}
+
 .refund-hint {
     margin-bottom: 14px;
     padding: 8px 10px;

app/Domains/Event/Views/Partials/ParticipationSummary.vue

@@ -68,6 +68,17 @@ const props = defineProps({
                         </td>
                     </tr>
 
+                    <!--
+                        Beiträge, die trotz Abmeldung beim Verband geblieben sind. Eigene Zeile, weil die
+                        Zeilen darüber nur aktive Anmeldungen führen.
+                    -->
+                    <tr v-if="props.event.retainedFromUnregistered.value > 0">
+                        <th style="padding-bottom: 20px" colspan="2">Einbehalten von Abmeldungen</th>
+                        <td style="padding-bottom: 20px" colspan="2">
+                            {{ props.event.retainedFromUnregistered.readable }}
+                        </td>
+                    </tr>
+
                     <tr>
                         <th colspan="2" style="border-width: 1px; border-top-style: solid">Gesamt</th>
                         <td style="font-weight: bold; border-width: 1px; border-top-style: solid">

app/Domains/Invoice/Actions/ChangeStatus/ChangeStatusCommand.php

@@ -22,7 +22,7 @@ class ChangeStatusCommand {
         switch ($this->request->status) {
             case InvoiceStatus::INVOICE_STATUS_APPROVED:
                 $this->request->invoice->status = InvoiceStatus::INVOICE_STATUS_APPROVED;
-                $this->request->invoice->approved_by = auth()->user()->id;
+                $this->request->invoice->approved_by = currentUserOrFail()->id;
                 $this->request->invoice->approved_at = now();
 
                 if ($this->request->invoice->contact_email !== null) {
@@ -35,7 +35,7 @@ class ChangeStatusCommand {
 
             case InvoiceStatus::INVOICE_STATUS_DENIED:
                 $this->request->invoice->status = InvoiceStatus::INVOICE_STATUS_DENIED;
-                $this->request->invoice->denied_by = auth()->user()->id;
+                $this->request->invoice->denied_by = currentUserOrFail()->id;
                 $this->request->invoice->denied_at = now();
                 $this->request->invoice->denied_reason = $this->request->comment;
                 if ($this->request->invoice->contact_email !== null) {

app/Domains/Invoice/Actions/CreateInvoice/CreateInvoiceCommand.php

@@ -24,7 +24,7 @@ class CreateInvoiceCommand {
         }
 
         $invoice = Invoice::create([
-            'tenant' => app('tenant')->slug,
+            'tenant' => currentTenant()->slug,
             'cost_unit_id' => $this->request->costUnit->id,
             'invoice_number' => $this->generateInvoiceNumber(),
             'status' => InvoiceStatus::INVOICE_STATUS_NEW,
@@ -61,7 +61,7 @@ class CreateInvoiceCommand {
         }
 
         if ($this->request->costUnit->mail_on_new) {
-            $recipients = [app('tenant')->email_finance];
+            $recipients = [currentTenant()->email_finance];
 
             foreach ($this->request->costUnit->treasurers()->get() as $treasurer) {
                 if (!in_array($treasurer->email, $recipients)) {
@@ -83,7 +83,7 @@ class CreateInvoiceCommand {
 
     private function generateInvoiceNumber() : string {
         $lastInvoiceNumber = Invoice::query()
-            ->where('tenant', app('tenant')->slug)
+            ->where('tenant', currentTenant()->slug)
             ->whereYear('created_at', date('Y'))
             ->count();
 

app/Domains/Invoice/Actions/UploadInvoice/UploadInvoiceCommand.php

@@ -19,7 +19,7 @@ class UploadInvoiceCommand {
         $uploadDir = sprintf(
             '%1$s%2$s/%3$s',
             WebDavProvider::INVOICE_PREFIX,
-            app('tenant')->url,
+            currentTenant()->url,
             $this->request->invoice->costUnit()->first()->name
         );
 

app/Domains/Invoice/Views/Partials/newInvoice/direct-payment.vue

@@ -1,6 +1,6 @@
 <script setup>
 
-import { ref, onMounted, reactive } from 'vue'
+import { ref, computed, onMounted, reactive } from 'vue'
 import {checkFilesize} from "../../../../../../resources/js/components/InvoiceUploadChecks.js";
 import RefundData from "./refund-data.vue";
 import AmountInput from "../../../../../Views/Components/AmountInput.vue";
@@ -38,6 +38,20 @@ onMounted(async () => {
     Object.assign(invoiceTypeCollection, data);
 });
 
+/**
+ * Das Beispiel im Feld "Was wurde eingekauft" kommt aus `invoice_types.purchase_example` und ist damit
+ * ohne Deployment pflegbar. Ein allgemeines "z. B. Material" hilft beim Ausfüllen nicht weiter, und von
+ * genau diesem Text lebt später die Zweck-Spalte der EüR-Belegliste.
+ *
+ * Ist am Typ nichts gepflegt, greift der allgemeine Text -- ein Feld ohne jede Hilfestellung wäre
+ * schlechter als ein unscharfes Beispiel.
+ */
+const purchasePlaceholder = computed(() => {
+    const selected = Object.values(invoiceTypeCollection.invoiceTypes)
+        .find((type) => type.slug === invoiceType.value)
+
+    return selected?.purchaseExample || 'z. B. Material für die Veranstaltung'
+})
 
 function handleFileChange(event) {
     if (checkFilesize('receipt')) {
@@ -66,28 +80,36 @@ function handleFileChange(event) {
             <InfoIcon :text="'INFO_INVOICE_TYPE_' + availableInvoiceType.slug" /><br />
         </p>
 
+    </fieldset><br /><br />
 
-        <label for="invoice_type_other">
+    <!--
+        Pflichtangabe zu jeder Rechnung, nicht nur zu "Sonstige Kosten": Erst dieser Text sagt, wofür das
+        Geld ausgegeben wurde, und füllt damit die Zweck-Spalte der EüR-Belegliste.
+
+        Die Schritte bauen aufeinander auf -- ohne Ausgabenart gäbe es kein passendes Beispiel für den
+        Einkauf, und ein Betrag ohne Zweck ließe sich später nicht mehr zuordnen.
+    -->
+    <template v-if="invoiceType !== null">
+        <fieldset>
+            <legend><span style="font-weight: bolder;">Was wurde eingekauft</span></legend>
             <input
                 type="text"
                 class="width-full"
-                name="kostengruppe_sonstiges"
+                id="purchase_description"
-                placeholder="Sonstige"
+                name="purchase_description"
-                for="invoice_type_other"
+                :placeholder="purchasePlaceholder"
                 v-model="otherText"
-                @focus="invoiceType = 'other'"
             />
-        </label>
+        </fieldset><br /><br />
+    </template>
 
-    </fieldset><br /><br />
+    <fieldset v-if="invoiceType !== null && otherText.trim() !== ''">
-
-    <fieldset>
         <legend><span style="font-weight: bolder;">Wie hoch ist der Betrag</span></legend>
         <AmountInput v-model="amount" class="width-small" id="amount" name="amount"  /> Euro
         <info-icon></info-icon><br /><br />
 
         <input
-            v-if="amount != '' && invoiceType !== null"
+            v-if="amount != ''"
             class="mareike-button"
             onclick="document.getElementById('receipt').click();"
             type="button"

app/Domains/Invoice/Views/Partials/newInvoice/expense-accounting.vue

@@ -1,6 +1,6 @@
 <script setup>
 
-import { ref, onMounted, reactive } from 'vue'
+import { ref, computed, onMounted, reactive } from 'vue'
 import {checkFilesize} from "../../../../../../resources/js/components/InvoiceUploadChecks.js";
 import RefundData from "./refund-data.vue";
 import AmountInput from "../../../../../Views/Components/AmountInput.vue";
@@ -37,6 +37,20 @@ onMounted(async () => {
     Object.assign(invoiceTypeCollection, data);
 });
 
+/**
+ * Das Beispiel im Feld "Was wurde eingekauft" kommt aus `invoice_types.purchase_example` und ist damit
+ * ohne Deployment pflegbar. Ein allgemeines "z. B. Material" hilft beim Ausfüllen nicht weiter, und von
+ * genau diesem Text lebt später die Zweck-Spalte der EüR-Belegliste.
+ *
+ * Ist am Typ nichts gepflegt, greift der allgemeine Text -- ein Feld ohne jede Hilfestellung wäre
+ * schlechter als ein unscharfes Beispiel.
+ */
+const purchasePlaceholder = computed(() => {
+    const selected = Object.values(invoiceTypeCollection.invoiceTypes)
+        .find((type) => type.slug === invoiceType.value)
+
+    return selected?.purchaseExample || 'z. B. Material für die Veranstaltung'
+})
 
 function handleFileChange(event) {
     if (checkFilesize('receipt')) {
@@ -65,28 +79,36 @@ function handleFileChange(event) {
             <InfoIcon :text="'INFO_INVOICE_TYPE_' + availableInvoiceType.slug" /><br />
         </p>
 
+    </fieldset><br /><br />
 
-        <label for="invoice_type_other">
+    <!--
+        Pflichtangabe zu jeder Abrechnung, nicht nur zu "Sonstige Kosten": Erst dieser Text sagt, wofür
+        das Geld ausgegeben wurde, und füllt damit die Zweck-Spalte der EüR-Belegliste.
+
+        Die Schritte bauen aufeinander auf -- ohne Ausgabenart gäbe es kein passendes Beispiel für den
+        Einkauf, und ein Betrag ohne Zweck ließe sich später nicht mehr zuordnen.
+    -->
+    <template v-if="invoiceType !== null">
+        <fieldset>
+            <legend><span style="font-weight: bolder;">Was wurde eingekauft</span></legend>
             <input
                 type="text"
                 class="width-full"
-                name="kostengruppe_sonstiges"
+                id="purchase_description"
-                placeholder="Sonstige"
+                name="purchase_description"
-                for="invoice_type_other"
+                :placeholder="purchasePlaceholder"
                 v-model="otherText"
-                @focus="invoiceType = 'other'"
             />
-        </label>
+        </fieldset><br /><br />
+    </template>
 
-    </fieldset><br /><br />
+    <fieldset v-if="invoiceType !== null && otherText.trim() !== ''">
-
-    <fieldset>
         <legend><span style="font-weight: bolder;">Wie hoch ist der Betrag</span></legend>
         <AmountInput v-model="amount" class="width-small" id="amount" name="amount"  /> Euro
         <info-icon></info-icon><br /><br />
 
         <input
-            v-if="amount != '' && invoiceType !== null"
+            v-if="amount != ''"
             class="mareike-button"
             onclick="document.getElementById('receipt').click();"
             type="button"

app/Domains/ParticipantInvoice/Actions/CreateParticipantInvoice/CreateParticipantInvoiceCommand.php

@@ -35,7 +35,7 @@ class CreateParticipantInvoiceCommand
         $this->participant = $request->participant;
         $this->event = $request->participant->event;
 
-        // Über die Relation und nicht über app('tenant'): die Rechnung hängt an der Veranstaltung,
+        // Über die Relation und nicht über currentTenant(): die Rechnung hängt an der Veranstaltung,
         // nicht am gerade aktiven Mandanten. `$event->tenant` liefert das Slug-Attribut, nicht die
         // Relation -- deshalb der ausdrückliche Aufruf.
         $this->sender = $this->event->tenant()->first();

app/Domains/ParticipantRefund/Actions/AcceptRefund/AcceptRefundCommand.php

@@ -120,8 +120,8 @@ class AcceptRefundCommand
             $invoice = $this->createInvoice($refund, $costUnit, $document);
 
             // Erst jetzt, nicht früher: Beleg und Anmerkung der Abrechnung weisen den gezahlten Beitrag
-            // aus und läsen sonst bereits die 0.
+            // aus und läsen sonst bereits den verrechneten Stand.
-            $this->clearAmountPaid($refund);
+            $this->settleAmountPaid($refund);
 
             $refund->invoice_id = $invoice->id;
             $refund->save();
@@ -141,7 +141,7 @@ class AcceptRefundCommand
      * Die Kostenstelle der Veranstaltung.
      *
      * Ohne Zugriffsprüfung, weil hier niemand angemeldet ist -- der Teili bestätigt über seinen Token.
-     * Der Repository-Check greift sonst auf `auth()->user()->id` zu und liefe in einen Fehler.
+     * Der Repository-Check greift sonst auf `currentUserOrFail()->id` zu und liefe in einen Fehler.
      *
      * Bewusst ohne Prüfung auf `allow_new`/`archived`: Eine Erstattung fällt oft erst nach dem Ende der
      * Veranstaltung an, wenn die Kostenstelle längst geschlossen ist. Sie gehört trotzdem dorthin -- und
@@ -255,16 +255,23 @@ class AcceptRefundCommand
     }
 
     /**
-     * Setzt den gezahlten Beitrag des Teilis auf 0.
+     * Zieht den erstatteten Betrag vom gezahlten Beitrag ab.
      *
-     * Mit der eingereichten Abrechnung ist der Beitrag nicht mehr beim Verband, sondern auf dem Weg
+     * Danach führt `amount_paid` genau das, was beim Verband geblieben ist -- bei voller Erstattung also
-     * zurück -- die Zahlungsübersichten der Aktionsleitung sollen ihn nicht länger als offen führen. Der
+     * 0, bei einer Teilerstattung den einbehaltenen Rest. Auf diesem Feld baut die Einnahmenrechnung der
-     * ursprüngliche Betrag steht zur Kontrolle in der Anmerkung der Abrechnung und auf dem Beleg.
+     * Veranstaltung auf; es muss deshalb den tatsächlichen Bestand abbilden und nicht die Zahlung von
+     * einst. Der ursprüngliche Betrag steht zur Kontrolle in der Anmerkung der Abrechnung und auf dem
+     * Beleg.
      */
-    private function clearAmountPaid(ParticipantRefund $refund): void
+    private function settleAmountPaid(ParticipantRefund $refund): void
     {
         $participant = $refund->participant;
-        $participant->amount_paid = new Amount(0.0, 'Euro');
+
+        $paid = $participant->amount_paid?->getAmount() ?? 0.0;
+        $refunded = $refund->amount?->getAmount() ?? 0.0;
+
+        // `max` gegen Rundungsreste: Ein negativer gezahlter Betrag wäre in jeder Auswertung Unsinn.
+        $participant->amount_paid = new Amount(max(0.0, round($paid - $refunded, 2)), 'Euro');
         $participant->save();
     }
 

app/Domains/ParticipantRefund/Actions/CreateRefundDocument/CreateRefundDocumentCommand.php

@@ -104,6 +104,26 @@ class CreateRefundDocumentCommand
      * Fallback stünde hier ein Fatal Error auf `null` -- so steht es heute im Deckblatt-Code der
      * Auslagenerstattung, und daran soll sich der Beleg kein Beispiel nehmen.
      */
+    /**
+     * Der Hinweis, warum ein Teil des Beitrags beim Verband bleibt -- leer bei voller Erstattung.
+     *
+     * Der Beleg wandert in die Buchhaltung und ins Archiv; dort muss die Differenz zwischen gezahltem
+     * und erstattetem Betrag ohne Rückfrage erklärt sein.
+     */
+    private function retentionNote(): string
+    {
+        if (!$this->refund->hasRetention()) {
+            return '';
+        }
+
+        $text = trim($this->refund->retentionReasonText());
+        $label = $this->refund->retentionReasonLabel();
+
+        return $text !== '' && $text !== $label
+            ? sprintf('%s (%s)', $label, $text)
+            : $label;
+    }
+
     /**
      * Der Vermerk, wenn die Aktionsleitung die Angaben aufgenommen hat.
      *
@@ -199,6 +219,9 @@ class CreateRefundDocumentCommand
             'account_owner' => (string) $refund->account_owner,
             'account_iban' => $this->formatIban((string) $refund->account_iban),
 
+            'retained_amount' => $this->money($refund->retained_amount?->getAmount() ?? 0.0),
+            'retention_note' => $this->retentionNote(),
+
             'declaration_text' => $this->declarationText(),
             'capture_note' => $this->captureNote(),
 
@@ -242,6 +265,13 @@ class CreateRefundDocumentCommand
             $rows[] = ['Begründung', e($reasonText)];
         }
 
+        // Nur bei einer Teilerstattung: Ohne diese Zeile bliebe die Differenz zwischen gezahltem und
+        // erstattetem Betrag im Beleg unerklärt.
+        if ($refund->hasRetention()) {
+            $rows[] = ['Einbehalten', $this->money($refund->retained_amount?->getAmount() ?? 0.0)];
+            $rows[] = ['Grund der Einbehaltung', e($this->retentionNote())];
+        }
+
         $rows[] = ['Kontoinhaber*in', e((string) $refund->account_owner)];
         $rows[] = ['IBAN', e($this->formatIban((string) $refund->account_iban))];
 

app/Domains/ParticipantRefund/Actions/ReleaseRefund/ReleaseRefundCommand.php

@@ -5,6 +5,7 @@ namespace App\Domains\ParticipantRefund\Actions\ReleaseRefund;
 use App\Domains\ParticipantRefund\Actions\AcceptRefund\AcceptRefundCommand;
 use App\Domains\ParticipantRefund\Actions\AcceptRefund\AcceptRefundRequest;
 use App\Enumerations\RefundReason;
+use App\Enumerations\RetentionReason;
 use App\Mail\ParticipantRefundMails\RefundReleasedMail;
 use App\Models\EventParticipant;
 use App\Models\ParticipantRefund;
@@ -57,7 +58,12 @@ class ReleaseRefundCommand
                 'amount' => $this->request->amount,
                 'reason' => $this->request->reason,
                 'reason_note' => $this->reasonNote(),
-                'released_by' => auth()->id(),
+                // Was beim Verband bleibt, wird hier festgeschrieben: Nach dem Einreichen führt
+                // `amount_paid` bereits diesen Rest, eine spätere Differenz wäre falsch.
+                'retained_amount' => $this->request->retainedAmount(),
+                'retention_reason' => $this->retentionReason(),
+                'retention_reason_note' => $this->retentionReasonNote(),
+                'released_by' => currentUser()?->id,
                 'released_at' => now(),
             ]);
 
@@ -95,7 +101,7 @@ class ReleaseRefundCommand
             accountIban: (string) $this->request->accountIban,
             // Niemand kreuzt hier eine Erklärung an; wer die Angaben aufgenommen hat, hält `captured_by`
             // fest, und der Beleg weist es aus.
-            capturedBy: auth()->id(),
+            capturedBy: currentUser()?->id,
         ))->execute();
 
         if (!$acceptResponse->success) {
@@ -141,7 +147,32 @@ class ReleaseRefundCommand
             return 'Für diesen Grund ist eine Erläuterung erforderlich.';
         }
 
-        return $this->rejectBankDetails();
+        return $this->rejectRetention() ?? $this->rejectBankDetails();
+    }
+
+    /**
+     * Prüfungen zum einbehaltenen Teil.
+     *
+     * Sicherheitsnetz hinter der Oberfläche: Dort erscheint der Absende-Knopf erst, wenn ein Grund
+     * gewählt ist. Über einen direkten Aufruf ginge das sonst vorbei, und ein einbehaltener Betrag ohne
+     * Begründung ist in der Buchhaltung nicht haltbar.
+     */
+    private function rejectRetention(): ?string
+    {
+        if (!$this->request->hasRetention()) {
+            return null;
+        }
+
+        $reason = RetentionReason::find($this->request->retentionReason);
+        if ($reason === null) {
+            return 'Bitte gib an, warum ein Teil des Beitrags einbehalten wird.';
+        }
+
+        if ($reason->requires_note && trim((string) $this->request->retentionReasonNote) === '') {
+            return 'Für diesen Einbehaltungsgrund ist eine Erläuterung erforderlich.';
+        }
+
+        return null;
     }
 
     /**
@@ -184,6 +215,33 @@ class ReleaseRefundCommand
         return trim((string) $this->request->reasonNote);
     }
 
+    /**
+     * Der Einbehaltungsgrund -- nur, wenn tatsächlich etwas beim Verband bleibt.
+     *
+     * Bei voller Erstattung wird ein mitgeschickter Grund verworfen: In der Oberfläche ist das Feld dann
+     * gar nicht sichtbar, und ein Wert ohne Bezug hätte in der Datenbank nichts zu suchen.
+     */
+    private function retentionReason(): ?string
+    {
+        return $this->request->hasRetention() ? $this->request->retentionReason : null;
+    }
+
+    /** Der Freitext dazu -- wie beim Erstattungsgrund nur bei Gründen, die ihn verlangen. */
+    private function retentionReasonNote(): ?string
+    {
+        if (!$this->request->hasRetention()) {
+            return null;
+        }
+
+        $reason = RetentionReason::find($this->request->retentionReason);
+
+        if ($reason === null || !$reason->requires_note) {
+            return null;
+        }
+
+        return trim((string) $this->request->retentionReasonNote);
+    }
+
     /**
      * Teili und Kontaktperson bekommen je eine eigene Mail -- dasselbe Muster wie bei der Abmeldung
      * (siehe SetParticipationStateCommand).

app/Domains/ParticipantRefund/Actions/ReleaseRefund/ReleaseRefundRequest.php

@@ -20,6 +20,14 @@ class ReleaseRefundRequest
          */
         public readonly ?string $accountOwner = null,
         public readonly ?string $accountIban = null,
+        /**
+         * Warum ein Teil des Beitrags beim Verband bleibt.
+         *
+         * Pflicht, sobald weniger erstattet wird als gezahlt wurde: Ein einbehaltener Betrag ohne Grund
+         * ist in der Buchhaltung nicht haltbar.
+         */
+        public readonly ?string $retentionReason = null,
+        public readonly ?string $retentionReasonNote = null,
     ) {
     }
 
@@ -28,4 +36,23 @@ class ReleaseRefundRequest
     {
         return filled($this->accountOwner) && filled($this->accountIban);
     }
+
+    /**
+     * Der Betrag, der beim Verband bleibt.
+     *
+     * Die halbe Cent-Toleranz fängt die Rundung des gespeicherten Floats ab -- ohne sie entstünden
+     * Restbeträge von Bruchteilen eines Cents, die eine Begründung verlangen würden.
+     */
+    public function retainedAmount(): float
+    {
+        $paid = $this->participant->amount_paid?->getAmount() ?? 0.0;
+        $remaining = round($paid - $this->amount->getAmount(), 2);
+
+        return $remaining > 0.005 ? $remaining : 0.0;
+    }
+
+    public function hasRetention(): bool
+    {
+        return $this->retainedAmount() > 0.0;
+    }
 }

app/Domains/ParticipantRefund/Controllers/ReleaseRefundController.php

@@ -28,6 +28,9 @@ class ReleaseRefundController extends CommonController
             // Leer, wenn der Teili die Bankverbindung selbst eintragen soll.
             accountOwner: Text::nullIfBlank($request->input('accountOwner')),
             accountIban: Text::nullIfBlank($request->input('accountIban')),
+            // Leer, wenn der volle Beitrag erstattet wird -- dann gibt es nichts zu begründen.
+            retentionReason: Text::nullIfBlank($request->input('retentionReason')),
+            retentionReasonNote: Text::nullIfBlank($request->input('retentionReasonNote')),
         );
 
         $response = new ReleaseRefundCommand($refundRequest)->execute();

app/Domains/ParticipantRefund/ParticipantRefundTokens.php

@@ -61,6 +61,8 @@ final class ParticipantRefundTokens
                     'paid_amount' => ['description' => 'Bereits gezahlter Teilnahmebeitrag', 'sample' => '300,00 €'],
                     'invoice_number' => ['description' => 'Nummer der Teilnahmerechnung', 'sample' => 'WM-V-20260701-0005'],
                     'refund_amount' => ['description' => 'Erstattungsbetrag', 'sample' => '220,00 €'],
+                    'retained_amount' => ['description' => 'Betrag, der beim Verband bleibt — 0,00 € bei voller Erstattung', 'sample' => '80,00 €'],
+                    'retention_note' => ['description' => 'Grund der Einbehaltung — leer bei voller Erstattung', 'sample' => 'Stornogebühr laut Ausschreibung'],
                     'refund_reason' => ['description' => 'Bezeichnung des Grundes', 'sample' => 'Krankheitsbedingte Absage'],
                     'refund_reason_text' => ['description' => 'Erläuterung des Grundes (bei „Sonstiger Grund" der Freitext)', 'sample' => 'Die Teilnahme konnte krankheitsbedingt nicht angetreten werden.'],
                     'account_owner' => ['description' => 'Kontoinhaber*in', 'sample' => 'Mika Muster'],
@@ -111,6 +113,8 @@ final class ParticipantRefundTokens
             . '<tr><td class="detail-key">Erstattungsbetrag</td><td class="detail-val">220,00&nbsp;&euro;</td></tr>'
             . '<tr><td class="detail-key">Grund</td><td class="detail-val">Krankheitsbedingte Absage</td></tr>'
             . '<tr><td class="detail-key">Begr&uuml;ndung</td><td class="detail-val">Die Teilnahme konnte krankheitsbedingt nicht angetreten werden.</td></tr>'
+            . '<tr><td class="detail-key">Einbehalten</td><td class="detail-val">80,00&nbsp;&euro;</td></tr>'
+            . '<tr><td class="detail-key">Grund der Einbehaltung</td><td class="detail-val">Stornogeb&uuml;hr laut Ausschreibung</td></tr>'
             . '<tr><td class="detail-key">Kontoinhaber*in</td><td class="detail-val">Mika Muster</td></tr>'
             . '<tr><td class="detail-key">IBAN</td><td class="detail-val">DE02 1203 0000 0000 2020 51</td></tr>'
             . '</table>';

app/Domains/UserManagement/Controllers/EmailVerificationController.php

@@ -23,7 +23,7 @@ use Illuminate\Http\Request;
 class EmailVerificationController extends CommonController
 {
     public function verifyEmailForm(Request $request) {
-        $inertiaProvider = new InertiaProvider('UserManagement/VerifyEmail', ['appName' => app('tenant')->name]);
+        $inertiaProvider = new InertiaProvider('UserManagement/VerifyEmail', ['appName' => currentTenant()->name]);
         return $inertiaProvider->render();
     }
 

app/Domains/UserManagement/Controllers/LoginController.php

@@ -17,7 +17,7 @@ class LoginController extends CommonController {
         }
 
 
-        $inertiaProvider = new InertiaProvider('UserManagement/Login', ['errors' => $errors, 'appName' => app('tenant')->name]);
+        $inertiaProvider = new InertiaProvider('UserManagement/Login', ['errors' => $errors, 'appName' => currentTenant()->name]);
         return $inertiaProvider->render();
     }
 
@@ -45,8 +45,8 @@ class LoginController extends CommonController {
             ]);
         }
 
-        $user = Auth::user();
+        $user = currentUserOrFail();
-        $tenant = app('tenant');
+        $tenant = currentTenant();
 
         // Auf "lv" darf sich grundsätzlich jeder aktive Nutzer einloggen.
         // Auf Sub-Tenants gilt:

app/Domains/UserManagement/Controllers/ProfileController.php

@@ -13,7 +13,7 @@ class ProfileController extends CommonController
             return redirect()->intended('/login');
         }
 
-        $user = auth()->user();
+        $user = currentUser();
 
         $inertiaProvider = new InertiaProvider('UserManagement/Profile', [
             'username' => $user->username,

app/Domains/UserManagement/Controllers/RegistrationController.php

@@ -26,8 +26,8 @@ class RegistrationController extends CommonController {
 
         $inertiaProvider = new InertiaProvider('UserManagement/Registration', [
             'errors' => $errors,
-            'appName' => app('tenant')->name,
+            'appName' => currentTenant()->name,
-            'tenant' => app('tenant'),
+            'tenant' => currentTenant(),
         ]);
         return $inertiaProvider->render();
     }
@@ -46,7 +46,7 @@ class RegistrationController extends CommonController {
         $userRoleMain = UserRole::USER_ROLE_USER;
         $userRoleLocalGroup = UserRole::USER_ROLE_USER;
 
-        $localGroup = app('tenant')->slug === 'lv' ? $request->get('localGroup') : app('tenant')->slug;
+        $localGroup = currentTenant()->slug === 'lv' ? $request->get('localGroup') : currentTenant()->slug;
 
 
         $registrationRequest = new UserRegistrationRequest(

app/Domains/UserManagement/Controllers/StoreProfileController.php

@@ -7,6 +7,7 @@ use App\Domains\UserManagement\Actions\UserChangePassword\UserChangePasswordRequ
 use App\Scopes\CommonController;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
 
 class StoreProfileController extends CommonController
 {
@@ -27,11 +28,11 @@ class StoreProfileController extends CommonController
             return response()->json(['success' => false, 'message' => 'Die Passwörter stimmen nicht überein.'], 422);
         }
 
-        $actionRequest = new UserChangePasswordRequest(auth()->user(), $password);
+        $actionRequest = new UserChangePasswordRequest(currentUserOrFail(), $password);
         $command = new UserChangePasswordCommand($actionRequest);
         $command->execute();
 
-        auth()->logout();
+        Auth::logout();
         return response()->json(['success' => true, 'message' => 'Dein Passwort wurde erfolgreich geändert.']);
     }
 }

app/Enumerations/InvoiceType.php

@@ -30,13 +30,16 @@ class InvoiceType extends CommonModel {
     protected $fillable = [
         'slug',
         'name',
+        'purchase_example',
         'sort_order',
         'selectable',
+        'counts_as_expense',
     ];
 
     protected $casts = [
         'sort_order' => 'integer',
         'selectable' => 'boolean',
+        'counts_as_expense' => 'boolean',
     ];
 
     /**
@@ -51,4 +54,21 @@ class InvoiceType extends CommonModel {
     {
         return self::where('selectable', true)->orderBy('sort_order')->get();
     }
+
+    /**
+     * Die Typen, die in der Ausgabenrechnung einer Veranstaltung zählen -- nach Sortierung.
+     *
+     * Ausgenommen ist, was fachlich keine Ausgabe ist, sondern die Rücknahme einer Einnahme: Eine
+     * Beitragserstattung mindert bereits die Einnahmenseite, weil der abgemeldete Teili dort herausfällt.
+     * Als Ausgabe gezählt, ginge derselbe Vorgang ein zweites Mal in die Bilanz.
+     *
+     * Der Name ist zweiter Sortierschlüssel: Die meisten Typen teilen sich `sort_order = 1`, und ohne ihn
+     * stünden die Zeilen der Ausgabenrechnung bei jedem Aufruf in einer anderen Reihenfolge.
+     *
+     * @return \Illuminate\Database\Eloquent\Collection<int, self>
+     */
+    public static function countingAsExpense(): \Illuminate\Database\Eloquent\Collection
+    {
+        return self::where('counts_as_expense', true)->orderBy('sort_order')->orderBy('name')->get();
+    }
 }

app/Enumerations/RetentionReason.php

@@ -0,0 +1,67 @@
+<?php
+
+namespace App\Enumerations;
+
+use App\Scopes\CommonModel;
+
+/**
+ * Gründe, aus denen ein Teil des gezahlten Teilnahmebeitrags beim Verband bleibt.
+ *
+ * Gegenstück zu {@see RefundReason}: Jener sagt, warum erstattet wird, dieser, warum nicht alles.
+ *
+ * @property string $slug
+ * @property string $name
+ * @property string|null $document_text
+ * @property bool $requires_note
+ * @property int $sort_order
+ */
+class RetentionReason extends CommonModel
+{
+    public const string CANCELLATION_FEE = 'cancellation_fee';
+    public const string INCURRED_COSTS = 'incurred_costs';
+    public const string MATERIAL = 'material';
+    public const string CUSTOM = 'custom';
+
+    protected $table = 'retention_reasons';
+    protected $primaryKey = 'slug';
+    public $incrementing = false;
+    protected $keyType = 'string';
+
+    protected $fillable = [
+        'slug',
+        'name',
+        'document_text',
+        'requires_note',
+        'sort_order',
+    ];
+
+    protected $casts = [
+        'requires_note' => 'boolean',
+        'sort_order' => 'integer',
+    ];
+
+    /**
+     * Der Text, der auf dem Beleg unter „Einbehalten" steht. Bei einem Grund, der einen Freitext
+     * verlangt, ist es der Text der Aktionsleitung.
+     */
+    public function documentText(?string $note = null): string
+    {
+        return $this->requires_note ? trim((string) $note) : (string) $this->document_text;
+    }
+
+    /**
+     * Optionen für das Frontend. `requiresNote` steuert dort das Freitextfeld.
+     *
+     * @return array<int, array{value: string, label: string, requiresNote: bool}>
+     */
+    public static function options(): array
+    {
+        return self::orderBy('sort_order')->get()
+            ->map(static fn (self $reason): array => [
+                'value' => $reason->slug,
+                'label' => $reason->name,
+                'requiresNote' => $reason->requires_note,
+            ])
+            ->all();
+    }
+}

app/Http/Controllers/TestRenderInertiaProvider.php

@@ -7,7 +7,7 @@ use App\Providers\InertiaProvider;
 class TestRenderInertiaProvider
 {
     public function index() {
-        $inertiaProvider = new InertiaProvider('Invoice/CreateInvoice', ['appName' => app('tenant')->name]);
+        $inertiaProvider = new InertiaProvider('Invoice/CreateInvoice', ['appName' => currentTenant()->name]);
         return $inertiaProvider->render();
     }
 }

app/Installer/ProductionDataSeeder.php

@@ -121,29 +121,37 @@ class ProductionDataSeeder {
 
 
     private function installInvoiceMetaData() {
+        // `purchase_example` steht im Formular als Beispiel im Feld "Was wurde eingekauft" und ist dort
+        // Pflicht. Der Text hängt an der Ausgabenart, weil ein allgemeines "z. B. Material" beim
+        // Ausfüllen nicht weiterhilft; pflegen lässt er sich anschließend in der Tabelle.
         InvoiceType::create([
             'slug' => InvoiceType::INVOICE_TYPE_TRAVELLING,
-            'name' => 'Reisekosten'
+            'name' => 'Reisekosten',
+            'purchase_example' => 'z. B. Bahnfahrt Halle–Leipzig',
         ]);
 
         InvoiceType::create([
             'slug' => InvoiceType::INVOICE_TYPE_PROGRAM,
-            'name' => 'Programmkosten'
+            'name' => 'Programmkosten',
+            'purchase_example' => 'z. B. Bastelmaterial für den Workshop',
         ]);
 
         InvoiceType::create([
             'slug' => InvoiceType::INVOICE_TYPE_ACCOMMODATION,
-            'name' => 'Unterkunftskosten'
+            'name' => 'Unterkunftskosten',
+            'purchase_example' => 'z. B. zwei Nächte Jugendherberge',
         ]);
 
         InvoiceType::create([
             'slug' => InvoiceType::INVOICE_TYPE_CATERING,
             'name' => 'Verpflegungskosten',
+            'purchase_example' => 'z. B. Wocheneinkauf für das Frühstück',
         ]);
 
         InvoiceType::create([
             'slug' => InvoiceType::INVOICE_TYPE_OTHER,
-            'name' => 'Sonstige Kosten'
+            'name' => 'Sonstige Kosten',
+            'purchase_example' => 'z. B. Erste-Hilfe-Set',
         ]);
 
         InvoiceStatus::create(['slug' => InvoiceStatus::INVOICE_STATUS_NEW]);

app/Mail/ParticipantRefundMails/RefundAcceptedMail.php

@@ -54,6 +54,11 @@ class RefundAcceptedMail extends Mailable
                 'accountIban' => Iban::format((string) $this->refund->account_iban),
                 'hasDocument' => $this->pdfContent !== null,
                 'invoiceNumber' => $invoice?->invoice_number,
+                // Wird nur ein Teil erstattet, soll der Teili nicht rätseln, wo der Rest geblieben ist.
+                'hasRetention' => $this->refund->hasRetention(),
+                'retainedAmount' => $this->refund->retained_amount?->toString() ?? '0,00 Euro',
+                'retentionReason' => $this->refund->retentionReasonLabel(),
+                'retentionReasonNote' => $this->refund->retention_reason_note,
                 // Hat die Aktionsleitung die Bankverbindung aufgenommen, hat der Teili selbst nichts
                 // eingetragen -- dann darf die Mail sich nicht für seine Angaben bedanken.
                 'capturedByManagement' => $this->refund->wasCapturedByManagement(),

app/Middleware/AdminRoleMiddleware.php

@@ -10,7 +10,7 @@ class AdminRoleMiddleware
 {
     public function handle($request, Closure $next)
     {
-        if (!auth()->check()) {
+        if (currentUser() === null) {
             return redirect('/login')->with('message', 'Du musst eingeloggt sein.');
         }
 

app/Middleware/LvOnlyMiddleware.php

@@ -8,7 +8,7 @@ class LvOnlyMiddleware
 {
     public function handle($request, Closure $next)
     {
-        if (app('tenant')->slug !== 'lv') {
+        if (currentTenant()->slug !== 'lv') {
             return redirect('/admin')->with('message', 'Diese Funktion ist nur auf LV-Ebene verfügbar.');
         }
 

app/Middleware/MainAdminRoleMiddleware.php

@@ -15,7 +15,7 @@ class MainAdminRoleMiddleware
 {
     public function handle($request, Closure $next)
     {
-        if (!auth()->check()) {
+        if (currentUser() === null) {
             return redirect('/login')->with('message', 'Du musst eingeloggt sein.');
         }
 

app/Models/Event.php

@@ -169,7 +169,7 @@ class Event extends InstancedModel
     public function paymentMethods() : BelongsToMany {
         // Pivot verknüpft über den Slug (payment_methods.slug), nicht über die numerische id
         // von available_payment_methods -- die tenant-spezifische Instanz wird dadurch implizit
-        // über den globalen SiteScope von AvailablePaymentMethod (gefiltert auf app('tenant')) aufgelöst.
+        // über den globalen SiteScope von AvailablePaymentMethod (gefiltert auf currentTenant()) aufgelöst.
         return $this->belongsToMany(AvailablePaymentMethod::class, 'event_payment_methods', 'event_id', 'slug', 'id', 'slug')
             ->using(EventPaymentMethods::class)
             ->withPivot('configuration')

app/Models/ParticipantRefund.php

@@ -4,6 +4,7 @@ namespace App\Models;
 
 use App\Casts\AmountCast;
 use App\Enumerations\RefundReason;
+use App\Enumerations\RetentionReason;
 use App\Scopes\InstancedModel;
 use App\ValueObjects\Amount;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
@@ -20,6 +21,9 @@ use Illuminate\Database\Eloquent\Relations\BelongsTo;
  * @property Amount|null $amount
  * @property string|null $reason
  * @property string|null $reason_note
+ * @property string|null $retention_reason
+ * @property string|null $retention_reason_note
+ * @property Amount|null $retained_amount
  * @property string|null $account_owner
  * @property string|null $account_iban
  * @property int|null $captured_by
@@ -51,6 +55,9 @@ class ParticipantRefund extends InstancedModel
         'amount',
         'reason',
         'reason_note',
+        'retention_reason',
+        'retention_reason_note',
+        'retained_amount',
         'account_owner',
         'account_iban',
         'captured_by',
@@ -63,6 +70,7 @@ class ParticipantRefund extends InstancedModel
 
     protected $casts = [
         'amount' => AmountCast::class,
+        'retained_amount' => AmountCast::class,
         'released_at' => 'datetime',
         'accepted_at' => 'datetime',
         'cancelled_at' => 'datetime',
@@ -129,4 +137,32 @@ class ParticipantRefund extends InstancedModel
     {
         return (string) ($this->reasonRelation()->first()?->name ?? '');
     }
+
+    /** Der Einbehaltungsgrund als Stammdatensatz -- leer, wenn voll erstattet wurde. */
+    public function retentionReasonRelation(): BelongsTo
+    {
+        return $this->belongsTo(RetentionReason::class, 'retention_reason', 'slug');
+    }
+
+    public function retentionReasonLabel(): string
+    {
+        return (string) ($this->retentionReasonRelation()->first()?->name ?? '');
+    }
+
+    /** Der auf dem Beleg auszuweisende Text zur Einbehaltung. */
+    public function retentionReasonText(): string
+    {
+        return $this->retentionReasonRelation()->first()?->documentText($this->retention_reason_note) ?? '';
+    }
+
+    /**
+     * Ob etwas beim Verband bleibt -- die halbe Cent-Toleranz fängt die Float-Rundung ab.
+     *
+     * Der Betrag steht in `retained_amount` und wird beim Einreichen festgeschrieben. Ihn zur Laufzeit
+     * aus `amount_paid` zu rechnen ginge schief: Danach führt das Feld bereits den Rest.
+     */
+    public function hasRetention(): bool
+    {
+        return ($this->retained_amount?->getAmount() ?? 0.0) > 0.005;
+    }
 }

app/Models/Tenant.php

@@ -50,7 +50,7 @@ class Tenant extends CommonModel
     }
 
     public static function getTempDirectory() : string {
-        return app('tenant')->slug . '/temp-data/';
+        return currentTenant()->slug . '/temp-data/';
     }
 
     /**

app/Models/User.php

@@ -2,7 +2,7 @@
 
 namespace App\Models;
 
-use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 use Illuminate\Foundation\Auth\User as Authenticatable;
 use Illuminate\Notifications\Notifiable;
 
@@ -115,10 +115,10 @@ class User extends Authenticatable
     }
 
     public function localGroup() : Tenant {
-        return $this->belongsTo(Tenant::class, 'local_group', 'slug')->first();
+        return $this->belongsTo(Tenant::class, 'local_group', 'slug')->firstOrFail();
     }
 
-    public function costUnits()
+    public function costUnits() : BelongsToMany
     {
         return $this->belongsToMany(CostUnit::class, 'cost_unit_treasurers', 'user_id', 'cost_unit_id')
             ->withTimestamps();

app/Providers/AuthCheckProvider.php

@@ -7,12 +7,12 @@ use App\Models\User;
 
 class AuthCheckProvider {
     public function checkLoggedIn() : bool {
-        if (!auth()->check()) {
+        $user = currentUser();
+        if ($user === null) {
             return false;
         }
 
-        $user = auth()->user();
+        $tenant = currentTenant();
-        $tenant = app('tenant');
         if ($tenant->slug === 'lv') {
             return $user->active;
         }
@@ -29,9 +29,9 @@ class AuthCheckProvider {
             return null;
         }
 
-        $user = auth()->user();
+        $user = currentUserOrFail();
 
-        if (app('tenant')->slug === 'lv') {
+        if (currentTenant()->slug === 'lv') {
             return $user->user_role_main;
         }
 
@@ -50,7 +50,7 @@ class AuthCheckProvider {
      * Diese Rolle hebt das lokale Rechtesystem für alle Sub-Tenants auf.
      */
     public function isMainAdministrator(?User $user = null) : bool {
-        $user ??= auth()->user();
+        $user ??= currentUser();
 
         return $user !== null
             && $user->user_role_main === UserRole::USER_ROLE_ADMIN;

app/Providers/CronTaskHandleProvider.php

@@ -61,7 +61,7 @@ class CronTaskHandleProvider extends CommonController
 
     private function runTask(CronTask $task)
     {
-        $logger = $this->taskLogger($task->name, app('tenant'));
+        $logger = $this->taskLogger($task->name, currentTenant());
         app()->instance('taskLogger', $logger);
 
         $taskClass = "\\App\\Tasks\\" . $task->name;
@@ -73,7 +73,7 @@ class CronTaskHandleProvider extends CommonController
                 $lastRun = [];
             }
 
-            $lastRun[app('tenant')->slug] = now();
+            $lastRun[currentTenant()->slug] = now();
             // Update last_run
             $task->last_run = $lastRun;
             $task->save();

app/Providers/GlobalDataProvider.php

@@ -5,6 +5,7 @@ namespace App\Providers;
 use App\Enumerations\EatingHabit;
 use App\Enumerations\InvoiceType;
 use App\Enumerations\RefundReason;
+use App\Enumerations\RetentionReason;
 use App\Enumerations\UserRole;
 use App\Models\AvailablePaymentMethod;
 use App\Models\Tenant;
@@ -21,7 +22,7 @@ class GlobalDataProvider {
     private ?User $user;
 
     public function __invoke() {
-        $this->user = auth()->user();
+        $this->user = currentUser();
 
         $canAccessAdmin = false;
         $isMainAdmin = false;
@@ -37,7 +38,7 @@ class GlobalDataProvider {
         return response()->json([
             'user' => null !== $this->user ? new UserResource($this->user)->toArray(request()) : null,
             'navbar' => $this->generateNavbar(),
-            'tenant' => app('tenant'),
+            'tenant' => currentTenant(),
             'activeUsers' => $this->getActiveUsers(),
             'version' => config('app.version'),
             'currentEvent' => $this->getCurrentEventData(),
@@ -58,7 +59,10 @@ class GlobalDataProvider {
 
             $invoiceTypes[] = [
                 'slug' => $invoiceType->slug,
-                'name' => $invoiceType->name
+                'name' => $invoiceType->name,
+                // Beispieltext für "Was wurde eingekauft". Ist er nicht gepflegt, setzt das Formular
+                // seinen eigenen allgemeinen Text ein.
+                'purchaseExample' => $invoiceType->purchase_example,
             ];
         }
 
@@ -185,8 +189,8 @@ class GlobalDataProvider {
         $activeUsers = [];
         $conditions = ['active' => true];
 
-        if (app('tenant')->slug !== 'lv') {
+        if (currentTenant()->slug !== 'lv') {
-            $conditions['local_group'] = app('tenant')->slug;
+            $conditions['local_group'] = currentTenant()->slug;
         }
 
         foreach ($rawUsers = User::where($conditions)->get() as $user) {
@@ -202,6 +206,11 @@ class GlobalDataProvider {
         return response()->json(RefundReason::options());
     }
 
+    /** Auswahl der Gründe, aus denen ein Teil des Beitrags beim Verband bleibt. */
+    public function getRetentionReasons() : JsonResponse {
+        return response()->json(RetentionReason::options());
+    }
+
     public function getEventSettingData(Request $request) : JsonResponse {
         return response()->json(
             [

app/Providers/InertiaProvider.php

@@ -16,7 +16,7 @@ final class InertiaProvider
     private ?User $user;
 
     public function __construct(string $vueFile, array $props) {
-        $this->user = auth()->user();
+        $this->user = currentUser();
         $this->vueFile = $vueFile;
         $this->props = $props;
     }

app/Providers/TenantUserProvider.php

@@ -20,7 +20,7 @@ class TenantUserProvider extends EloquentUserProvider
         }
 
         // Auf "lv" gilt grundsätzlich keine local_group-Einschränkung.
-        if (app('tenant')->slug === 'lv') {
+        if (currentTenant()->slug === 'lv') {
             return $query->first();
         }
 
@@ -30,7 +30,7 @@ class TenantUserProvider extends EloquentUserProvider
         //     -> "Bundesrecht steht über Landesrecht": Login überall möglich.
         $query->where('active', true)
             ->where(function ($q) {
-                $q->where('local_group', app('tenant')->slug)
+                $q->where('local_group', currentTenant()->slug)
                   ->orWhere('user_role_main', UserRole::USER_ROLE_ADMIN);
             });
 

app/Providers/UploadFileProvider.php

@@ -25,7 +25,7 @@ class UploadFileProvider {
      * wo alle anderen Belege liegen.
      */
     public static function directoryFor(CostUnit $costUnit) : string {
-        return sprintf('%1$s/invoices/%2$s', app('tenant')->slug, $costUnit->id);
+        return sprintf('%1$s/invoices/%2$s', currentTenant()->slug, $costUnit->id);
     }
 
     public function saveUploadedFile() : ?InvoiceFile {

app/Repositories/CostUnitRepository.php

@@ -2,11 +2,13 @@
 
 namespace App\Repositories;
 
+use \currentUser;
 use App\Enumerations\CostUnitType;
 use App\Enumerations\InvoiceStatus;
 use App\Enumerations\InvoiceType;
 use App\Enumerations\UserRole;
 use App\Models\CostUnit;
+use App\Models\Invoice;
 use App\Providers\AuthCheckProvider;
 use App\Resources\CostUnitResource;
 use App\ValueObjects\Amount;
@@ -66,8 +68,7 @@ class CostUnitRepository {
     }
 
     public function getCostUnitsByCriteria(array $criteria, bool $forDisplay = true, $disableAccessCheck = false) : array {
-        $user = Auth()->user();
+        $user = currentUser();
-
         if ($disableAccessCheck) {
             $canSeeAll = true;
         } else {
@@ -96,7 +97,7 @@ class CostUnitRepository {
     public function listForSummary(int $maxCountCostUnits) : array {
         $costUnits = $this->getCostUnitsByCriteria([
             'archived' => false,
-            'tenant' => app('tenant')->slug,
+            'tenant' => currentTenant()->slug,
         ],false);
 
         foreach ($costUnits as &$cu) {
@@ -153,8 +154,7 @@ class CostUnitRepository {
 
         foreach ($costUnit->invoices()->get() as $invoice) {
             if (
-                $invoice->status === InvoiceStatus::INVOICE_STATUS_DENIED ||
+                !self::countsAsExpense($invoice) ||
-                $invoice->donation ||
                 $invoice->type !== $invoiceType->slug
             ) {
                 continue;
@@ -165,6 +165,52 @@ class CostUnitRepository {
         return $amount;
     }
 
+    /**
+     * Die Ausgaben einer Kostenstelle, nach Ausgabentyp gruppiert -- Summe und die Belege dahinter.
+     *
+     * Jeder zählende Typ steht im Ergebnis, auch ohne Beleg: Die Einnahmen-Überschuss-Rechnung zeigt
+     * damit immer dieselbe Gliederung, und eine fehlende Zeile lässt sich nicht mit einer vergessenen
+     * verwechseln.
+     *
+     * @return array<string, array{type: InvoiceType, invoices: array<int, Invoice>, sum: Amount}>
+     */
+    public function groupExpensesByType(CostUnit $costUnit) : array {
+        $groups = [];
+
+        foreach (InvoiceType::countingAsExpense() as $invoiceType) {
+            $groups[$invoiceType->slug] = [
+                'type' => $invoiceType,
+                'invoices' => [],
+                'sum' => new Amount(0, 'Euro'),
+            ];
+        }
+
+        foreach ($costUnit->invoices()->orderBy('invoice_number')->get() as $invoice) {
+            if (!self::countsAsExpense($invoice) || !isset($groups[$invoice->type])) {
+                continue;
+            }
+
+            $groups[$invoice->type]['invoices'][] = $invoice;
+            $groups[$invoice->type]['sum']->addAmount(Amount::fromString($invoice->amount));
+        }
+
+        return $groups;
+    }
+
+    /**
+     * Ob ein Beleg als Ausgabe zählt.
+     *
+     * Abgelehnt und gelöscht sind keine Ausgabe, weil kein Geld fließt. Dasselbe gilt für eine gespendete
+     * Auslage: Auf die Auszahlung wurde verzichtet, die Kostenstelle gibt nichts aus.
+     */
+    private static function countsAsExpense(Invoice $invoice) : bool {
+        return !in_array($invoice->status, [
+                InvoiceStatus::INVOICE_STATUS_DENIED,
+                InvoiceStatus::INVOICE_STATUS_DELETED,
+            ], true)
+            && !$invoice->donation;
+    }
+
     public function sumupEstimatedByInvoiceType(CostUnit $costUnit, InvoiceType $invoiceType) : Amount {
         $amount = new Amount(0, 'Euro');
         foreach ($costUnit->estimates()->get() as $estimate) {

app/Repositories/EventParticipantRepository.php

@@ -297,7 +297,7 @@ class EventParticipantRepository {
 
     public function getMyParticipations(?int $maxEvents = null) : array {
         $participations = [];
-        $user = auth()->user();
+        $user = currentUser();
         if ($user === null) {
             return $participations;
         }
@@ -326,13 +326,13 @@ class EventParticipantRepository {
     }
 
     public function getMyParticipationByIdentifier(string $identifier) : ?EventParticipant {
-        $user = auth()->user();
+        $user = currentUser();
         if ($user === null) {
             return null;
         }
 
         return EventParticipant::where('identifier', $identifier)
-            ->where('tenant', app('tenant')->slug)
+            ->where('tenant', currentTenant()->slug)
             ->where('user_id', $user->id)
             ->whereNull('unregistered_at')
             ->first();

app/Repositories/InvoiceRepository.php

@@ -20,7 +20,7 @@ class InvoiceRepository {
         ];
 
 
-        $user = auth()->user();
+        $user = currentUser();
         if (null === $user) {
             return $invoices;
         }
@@ -41,7 +41,7 @@ class InvoiceRepository {
     }
 
     public function getUnexportedInvoices() : Collection {
-        return Invoice::where(['tenant' => app('tenant')->slug, 'status' => InvoiceStatus::INVOICE_STATUS_EXPORTED, 'upload_required' => true])->get();
+        return Invoice::where(['tenant' => currentTenant()->slug, 'status' => InvoiceStatus::INVOICE_STATUS_EXPORTED, 'upload_required' => true])->get();
     }
 
     public function getByStatus(CostUnit $costUnit, string $status, bool $forDisplay = true) : array {
@@ -63,8 +63,8 @@ class InvoiceRepository {
         foreach (Invoice::where(
             [
                 'status' => $status,
-                'user_id' => auth()->user()->id,
+                'user_id' => currentUserOrFail()->id,
-                'tenant' => app('tenant')->slug,
+                'tenant' => currentTenant()->slug,
 
             ]
             )->get() as $invoice) {
@@ -79,7 +79,7 @@ class InvoiceRepository {
             return null;
         }
 
-        $isTreasurer = $invoice->costUnit()->first()->treasurers()->where('user_id', auth()->user()->id)->exists();
+        $isTreasurer = $invoice->costUnit()->first()->treasurers()->where('user_id', currentUserOrFail()->id)->exists();
         if ($isTreasurer) {
             return $invoice;
         }

app/Repositories/UserRepository.php

@@ -20,7 +20,7 @@ class UserRepository {
     }
 
     public function getCurrentUserDetails() : array {
-        $user = auth()->user();
+        $user = currentUser();
 
         $return = [
             'userId' => null,
@@ -31,7 +31,7 @@ class UserRepository {
             'userAccountIban' => '',
         ];
 
-        if (null !== auth()->user()) {
+        if ($user !== null) {
             $return = [
                 'userId' => $user->id,
                 'userName' => trim($user->getOfficialName()),

app/Resources/CostUnitResource.php

@@ -32,7 +32,10 @@ class CostUnitResource {
         $amounts = [];
         $overAllAmount = new Amount(0, 'Euro');
         $overAllEstimatedAmount = new Amount(0, 'Euro');
-        foreach (InvoiceType::orderBy('sort_order')->get() as $invoiceType) {
+        // Nur echte Aufwandsarten: Eine Beitragserstattung ist die Rücknahme einer Einnahme und wird auf
+        // der Einnahmenseite bereits berücksichtigt -- hier gezählt, stünde sie ein zweites Mal in der
+        // Bilanz. `totalAmount` weiter oben bleibt davon unberührt, das ist die Kassensicht.
+        foreach (InvoiceType::countingAsExpense() as $invoiceType) {
             $overAllAmount->addAmount($costUnitRepository->sumupByInvoiceType($this->costUnit, $invoiceType));
             $overAllEstimatedAmount->addAmount($costUnitRepository->sumupEstimatedByInvoiceType($this->costUnit, $invoiceType));
             $amounts[$invoiceType->slug]['string'] = $costUnitRepository->sumupByInvoiceType($this->costUnit, $invoiceType)->toString();

app/Resources/EventResource.php

@@ -27,8 +27,8 @@ class EventResource extends JsonResource{
             'id' => $this->event->id,
             'name' => $this->event->name,
             'identifier' => $this->event->identifier,
-            'url' => 'https://' . app('tenant')->url . '/event/' . $this->event->identifier . '/signup',
+            'url' => 'https://' . currentTenant()->url . '/event/' . $this->event->identifier . '/signup',
-            'urlShort' => 'https://' . app('tenant')->url . '/event/' . $this->event->identifier,
+            'urlShort' => 'https://' . currentTenant()->url . '/event/' . $this->event->identifier,
             'location' => $this->event->location,
             'postalCode' => $this->event->postal_code,
             'email' => $this->event->email,
@@ -96,6 +96,14 @@ class EventResource extends JsonResource{
 
         $returnArray['income'] = $this->calculateIncomes($returnArray['participants'], $returnArray['supportPerson']['amount']);
 
+        // Eigene Zeile in der Übersicht: In den Zeilen je Teilnahmeart hätte der Betrag nichts zu suchen,
+        // dort stehen nur aktive Anmeldungen.
+        $retainedFromUnregistered = $this->sumPaidOfUnregistered();
+        $returnArray['retainedFromUnregistered'] = [
+            'value' => $retainedFromUnregistered->getAmount(),
+            'readable' => $retainedFromUnregistered->toString(),
+        ];
+
 
         $totalBalanceReal = new Amount(0, 'Euro');
         $totalBalanceExpected = new Amount(0, 'Euro');
@@ -272,6 +280,13 @@ class EventResource extends JsonResource{
             $realAmount->addAmount(new Amount($participantData['amount']['paid']['value'], 'Euro'));
         }
 
+        // Was abgemeldete Teilis gezahlt haben und nicht zurückbekommen, gehört in beide Spalten: Das
+        // Geld liegt beim Verband (real) und fließt nicht mehr ab (erwartet). Ohne diese Zeile stünde
+        // jede Veranstaltung mit Abmeldungen dauerhaft schlechter da, als sie ist.
+        $retained = $this->sumPaidOfUnregistered();
+        $realAmount->addAmount($retained);
+        $expectedAmount->addAmount($retained);
+
         return ['real' => [
             'amount' => $realAmount,
             'readable' => $realAmount->toString()
@@ -283,6 +298,28 @@ class EventResource extends JsonResource{
         ];
     }
 
+    /**
+     * Was von abgemeldeten Teilis beim Verband geblieben ist.
+     *
+     * `amount_paid` führt nach einer Erstattung genau den einbehaltenen Rest; wurde nie erstattet, steht
+     * dort der volle gezahlte Beitrag. Beides ist Geld, das der Veranstaltung zusteht.
+     *
+     * Bewusst eine direkte Abfrage wie in {@see self::getParticipants()} nebenan -- ein einzelner
+     * Repository-Aufruf zwischen den Inline-Queries dieser Klasse würde sie uneinheitlicher machen.
+     */
+    public function sumPaidOfUnregistered() : Amount
+    {
+        $sum = new Amount(0, 'Euro');
+
+        foreach ($this->event->participants()->whereNotNull('unregistered_at')->get() as $participant) {
+            if ($participant->amount_paid !== null) {
+                $sum->addAmount($participant->amount_paid);
+            }
+        }
+
+        return $sum;
+    }
+
     public function getParticipants(string $participationType) : array {
         $returnData = [];
         $returnData['amount'] = [

app/Resources/ParticipantRefundResource.php

@@ -29,6 +29,12 @@ class ParticipantRefundResource extends JsonResource
             'reason' => $this->resource->reason,
             'reasonLabel' => $this->resource->reasonLabel(),
             'reasonNote' => $this->resource->reason_note,
+            // Was beim Verband bleibt. `hasRetention` erspart dem Frontend den Betragsvergleich samt
+            // Rundungsfrage -- es soll nur entscheiden, ob der Hinweis angezeigt wird.
+            'hasRetention' => $this->resource->hasRetention(),
+            'retainedAmount' => $this->resource->retained_amount?->toString() ?? '0,00 Euro',
+            'retentionReasonLabel' => $this->resource->retentionReasonLabel(),
+            'retentionReasonNote' => $this->resource->retention_reason_note,
             'releasedAt' => $this->resource->released_at?->format('d.m.Y'),
             'acceptedAt' => $this->resource->accepted_at?->format('d.m.Y'),
             'cancelledAt' => $this->resource->cancelled_at?->format('d.m.Y'),

app/Scopes/CommonController.php

@@ -31,7 +31,7 @@ abstract class CommonController {
     protected AdminTenantRepository $adminTenants;
 
     public function __construct() {
-        $this->tenant = app('tenant');
+        $this->tenant = currentTenant();
         $this->users = new UserRepository();
         $this->costUnits = new CostUnitRepository();
         $this->pageTexts = new PageTextRepository();

app/Scopes/SiteScope.php

@@ -9,6 +9,6 @@ class SiteScope implements Scope
 {
     public function apply(Builder $builder, Model $model): void
     {
-        $builder->where($model->getTable() . '.tenant', app('tenant')->slug);
+        $builder->where($model->getTable() . '.tenant', currentTenant()->slug);
     }
 }

app/Support/helpers.php

@@ -0,0 +1,36 @@
+<?php
+
+use App\Models\Tenant;
+use App\Models\User;
+use Illuminate\Auth\AuthenticationException;
+use Illuminate\Support\Facades\Auth;
+
+if (!function_exists('currentUser')) {
+    /**
+     * Der aktuell eingeloggte Nutzer, oder null wenn niemand eingeloggt ist.
+     */
+    function currentUser() : ?User {
+        return Auth::user();
+    }
+}
+
+if (!function_exists('currentUserOrFail')) {
+    /**
+     * Der aktuell eingeloggte Nutzer. Für Code hinter der auth-Middleware,
+     * wo ein fehlender Nutzer ein Programmierfehler ist.
+     *
+     * @throws AuthenticationException
+     */
+    function currentUserOrFail() : User {
+        return Auth::user() ?? throw new AuthenticationException();
+    }
+}
+
+if (!function_exists('currentTenant')) {
+    /**
+     * Der über IdentifyTenant aufgelöste Tenant der aktuellen Anfrage.
+     */
+    function currentTenant() : Tenant {
+        return app('tenant');
+    }
+}

app/Tasks/UploadInvoices.php

@@ -10,7 +10,7 @@ use Psr\Log\LoggerInterface;
 class UploadInvoices implements CronTask {
     public function handle(): void
     {
-        if (!app('tenant')->upload_exports) {
+        if (!currentTenant()->upload_exports) {
             return;
         }
 

composer.json

@@ -20,6 +20,7 @@
         "maennchen/zipstream-php": "^3.1"
     },
     "require-dev": {
+        "barryvdh/laravel-ide-helper": "^3.7",
         "fakerphp/faker": "^1.23",
         "laravel/pail": "^1.2.2",
         "laravel/pint": "^1.24",
@@ -29,6 +30,9 @@
         "phpunit/phpunit": "^11.5.3"
     },
     "autoload": {
+        "files": [
+            "app/Support/helpers.php"
+        ],
         "psr-4": {
             "App\\": "app/",
             "Database\\Factories\\": "database/factories/",

composer.lock

@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "9fb8095137a8e9d664e44b9fca5f1f5a",
+    "content-hash": "6e38fe16a000f12f5fff089b08b49780",
     "packages": [
         {
             "name": "bacon/bacon-qr-code",
@@ -6934,6 +6934,298 @@
         }
     ],
     "packages-dev": [
+        {
+            "name": "barryvdh/laravel-ide-helper",
+            "version": "v3.7.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/barryvdh/laravel-ide-helper.git",
+                "reference": "ad7e37676f1ff985d55ef1b6b96a0c0a40f2609a"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/barryvdh/laravel-ide-helper/zipball/ad7e37676f1ff985d55ef1b6b96a0c0a40f2609a",
+                "reference": "ad7e37676f1ff985d55ef1b6b96a0c0a40f2609a",
+                "shasum": ""
+            },
+            "require": {
+                "barryvdh/reflection-docblock": "^2.4",
+                "composer/class-map-generator": "^1.0",
+                "ext-json": "*",
+                "illuminate/console": "^11.15 || ^12 || ^13.0",
+                "illuminate/database": "^11.15 || ^12 || ^13.0",
+                "illuminate/filesystem": "^11.15 || ^12 || ^13.0",
+                "illuminate/support": "^11.15 || ^12 || ^13.0",
+                "php": "^8.2"
+            },
+            "require-dev": {
+                "ext-pdo_sqlite": "*",
+                "friendsofphp/php-cs-fixer": "^3",
+                "illuminate/config": "^11.15 || ^12 || ^13.0",
+                "illuminate/view": "^11.15 || ^12 || ^13.0",
+                "larastan/larastan": "^3.1",
+                "mockery/mockery": "^1.4",
+                "orchestra/testbench": "^9.2 || ^10 || ^11.0",
+                "phpstan/phpstan-phpunit": "^2.0",
+                "phpunit/phpunit": "^10.5 || ^11.5.3 || ^12.5.12",
+                "spatie/phpunit-snapshot-assertions": "^4 || ^5",
+                "vlucas/phpdotenv": "^5"
+            },
+            "suggest": {
+                "illuminate/events": "Required for automatic helper generation (^6|^7|^8|^9|^10|^11)."
+            },
+            "type": "library",
+            "extra": {
+                "laravel": {
+                    "providers": [
+                        "Barryvdh\\LaravelIdeHelper\\IdeHelperServiceProvider"
+                    ]
+                },
+                "branch-alias": {
+                    "dev-master": "3.6-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Barryvdh\\LaravelIdeHelper\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Barry vd. Heuvel",
+                    "email": "barryvdh@gmail.com"
+                }
+            ],
+            "description": "Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.",
+            "keywords": [
+                "autocomplete",
+                "codeintel",
+                "dev",
+                "helper",
+                "ide",
+                "laravel",
+                "netbeans",
+                "phpdoc",
+                "phpstorm",
+                "sublime"
+            ],
+            "support": {
+                "issues": "https://github.com/barryvdh/laravel-ide-helper/issues",
+                "source": "https://github.com/barryvdh/laravel-ide-helper/tree/v3.7.0"
+            },
+            "funding": [
+                {
+                    "url": "https://fruitcake.nl",
+                    "type": "custom"
+                },
+                {
+                    "url": "https://github.com/barryvdh",
+                    "type": "github"
+                }
+            ],
+            "time": "2026-03-17T14:12:51+00:00"
+        },
+        {
+            "name": "barryvdh/reflection-docblock",
+            "version": "v2.4.1",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/barryvdh/ReflectionDocBlock.git",
+                "reference": "4f5ba70c30c81f2ce03a16a9965832cfcc31ed3b"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/barryvdh/ReflectionDocBlock/zipball/4f5ba70c30c81f2ce03a16a9965832cfcc31ed3b",
+                "reference": "4f5ba70c30c81f2ce03a16a9965832cfcc31ed3b",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=7.1"
+            },
+            "require-dev": {
+                "phpunit/phpunit": "^8.5.14|^9"
+            },
+            "suggest": {
+                "dflydev/markdown": "~1.0",
+                "erusev/parsedown": "~1.0"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-master": "2.3.x-dev"
+                }
+            },
+            "autoload": {
+                "psr-0": {
+                    "Barryvdh": [
+                        "src/"
+                    ]
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Mike van Riel",
+                    "email": "mike.vanriel@naenius.com"
+                }
+            ],
+            "support": {
+                "source": "https://github.com/barryvdh/ReflectionDocBlock/tree/v2.4.1"
+            },
+            "time": "2026-03-05T20:09:01+00:00"
+        },
+        {
+            "name": "composer/class-map-generator",
+            "version": "1.7.3",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/composer/class-map-generator.git",
+                "reference": "86d8208fc3c649a3a999daf1a63c25201be2990f"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/composer/class-map-generator/zipball/86d8208fc3c649a3a999daf1a63c25201be2990f",
+                "reference": "86d8208fc3c649a3a999daf1a63c25201be2990f",
+                "shasum": ""
+            },
+            "require": {
+                "composer/pcre": "^2.1 || ^3.1",
+                "php": "^7.2 || ^8.0",
+                "symfony/finder": "^4.4 || ^5.3 || ^6 || ^7 || ^8"
+            },
+            "require-dev": {
+                "phpstan/phpstan": "^1.12 || ^2",
+                "phpstan/phpstan-deprecation-rules": "^1 || ^2",
+                "phpstan/phpstan-phpunit": "^1 || ^2",
+                "phpstan/phpstan-strict-rules": "^1.1 || ^2",
+                "phpunit/phpunit": "^8",
+                "symfony/filesystem": "^5.4 || ^6 || ^7 || ^8"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-main": "1.x-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Composer\\ClassMapGenerator\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Jordi Boggiano",
+                    "email": "j.boggiano@seld.be",
+                    "homepage": "https://seld.be"
+                }
+            ],
+            "description": "Utilities to scan PHP code and generate class maps.",
+            "keywords": [
+                "classmap"
+            ],
+            "support": {
+                "issues": "https://github.com/composer/class-map-generator/issues",
+                "source": "https://github.com/composer/class-map-generator/tree/1.7.3"
+            },
+            "funding": [
+                {
+                    "url": "https://packagist.com",
+                    "type": "custom"
+                },
+                {
+                    "url": "https://github.com/composer",
+                    "type": "github"
+                }
+            ],
+            "time": "2026-05-05T09:17:07+00:00"
+        },
+        {
+            "name": "composer/pcre",
+            "version": "3.4.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/composer/pcre.git",
+                "reference": "d5a341b3fb61f3001970940afb1d332968a183ed"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/composer/pcre/zipball/d5a341b3fb61f3001970940afb1d332968a183ed",
+                "reference": "d5a341b3fb61f3001970940afb1d332968a183ed",
+                "shasum": ""
+            },
+            "require": {
+                "php": "^7.4 || ^8.0"
+            },
+            "conflict": {
+                "phpstan/phpstan": "<2.2.2"
+            },
+            "require-dev": {
+                "phpstan/phpstan": "^2",
+                "phpstan/phpstan-deprecation-rules": "^2",
+                "phpstan/phpstan-strict-rules": "^2",
+                "phpunit/phpunit": "^9"
+            },
+            "type": "library",
+            "extra": {
+                "phpstan": {
+                    "includes": [
+                        "extension.neon"
+                    ]
+                },
+                "branch-alias": {
+                    "dev-main": "3.x-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Composer\\Pcre\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Jordi Boggiano",
+                    "email": "j.boggiano@seld.be",
+                    "homepage": "http://seld.be"
+                }
+            ],
+            "description": "PCRE wrapping library that offers type-safe preg_* replacements.",
+            "keywords": [
+                "PCRE",
+                "preg",
+                "regex",
+                "regular expression"
+            ],
+            "support": {
+                "issues": "https://github.com/composer/pcre/issues",
+                "source": "https://github.com/composer/pcre/tree/3.4.0"
+            },
+            "funding": [
+                {
+                    "url": "https://packagist.com",
+                    "type": "custom"
+                },
+                {
+                    "url": "https://github.com/composer",
+                    "type": "github"
+                }
+            ],
+            "time": "2026-06-07T11:47:49+00:00"
+        },
         {
             "name": "fakerphp/faker",
             "version": "v1.24.1",

database/migrations/2026_09_07_140010_add_counts_as_expense_to_invoice_types.php

@@ -0,0 +1,38 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Trennt die Abrechnungstypen, die in der Ausgabenrechnung einer Veranstaltung zählen, von denen, die es
+ * nicht tun.
+ *
+ * Anlass ist die Beitragserstattung: Sie ist keine Aufwandsposition, sondern die Rücknahme einer
+ * Einnahme. Die Einnahmenseite berücksichtigt sie bereits -- ein abgemeldeter Teili fällt aus
+ * `EventResource::getParticipants()` heraus, sein gezahlter Beitrag verschwindet also dort schon. Als
+ * Ausgabe gezählt, ginge derselbe Vorgang ein zweites Mal in die Bilanz.
+ *
+ * Betroffen ist nur die Budgetrechnung der Veranstaltung. In der Kassensicht (Kostenstellen-Liste,
+ * Dashboard) bleibt der Betrag stehen -- dort fließt er tatsächlich ab.
+ */
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::table('invoice_types', function (Blueprint $table) {
+            $table->boolean('counts_as_expense')->default(true)->after('selectable');
+        });
+
+        DB::table('invoice_types')
+            ->where('slug', 'participation_refund')
+            ->update(['counts_as_expense' => false]);
+    }
+
+    public function down(): void
+    {
+        Schema::table('invoice_types', function (Blueprint $table) {
+            $table->dropColumn('counts_as_expense');
+        });
+    }
+};

database/migrations/2026_09_08_140010_create_retention_reasons.php

@@ -0,0 +1,72 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Gründe, aus denen ein Teil des gezahlten Beitrags beim Verband bleibt.
+ *
+ * Wird nicht der volle Beitrag erstattet, ist der Rest eine Einnahme, die begründet sein muss -- in der
+ * Buchhaltung ist ein einbehaltener Betrag ohne Grund nicht haltbar. Aufgebaut wie
+ * {@see \App\Enumerations\RefundReason}: app-weite Stammdaten, `slug` als Schlüssel.
+ */
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::create('retention_reasons', function (Blueprint $table) {
+            $table->string('slug')->primary();
+            $table->string('name');
+            $table->text('document_text')->nullable();
+            $table->boolean('requires_note')->default(false);
+            $table->integer('sort_order')->default(0);
+            $table->timestamps();
+        });
+
+        DB::table('retention_reasons')->insert([
+            [
+                'slug' => 'cancellation_fee',
+                'name' => 'Stornogebühr laut Ausschreibung',
+                'document_text' => 'Einbehalten wurde die in der Ausschreibung genannte Stornogebühr.',
+                'requires_note' => false,
+                'sort_order' => 10,
+                'created_at' => now(),
+                'updated_at' => now(),
+            ],
+            [
+                'slug' => 'incurred_costs',
+                'name' => 'Bereits entstandene Kosten',
+                'document_text' => 'Einbehalten wurden Kosten, die zum Zeitpunkt der Abmeldung bereits entstanden waren.',
+                'requires_note' => false,
+                'sort_order' => 20,
+                'created_at' => now(),
+                'updated_at' => now(),
+            ],
+            [
+                'slug' => 'material',
+                'name' => 'Bereits beschafftes Material',
+                'document_text' => 'Einbehalten wurden Kosten für Material, das bereits beschafft wurde.',
+                'requires_note' => false,
+                'sort_order' => 30,
+                'created_at' => now(),
+                'updated_at' => now(),
+            ],
+            [
+                // Der Text entsteht erst aus dem Freitext der Aktionsleitung -- deshalb hier leer.
+                'slug' => 'custom',
+                'name' => 'Sonstiger Grund',
+                'document_text' => null,
+                'requires_note' => true,
+                'sort_order' => 40,
+                'created_at' => now(),
+                'updated_at' => now(),
+            ],
+        ]);
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('retention_reasons');
+    }
+};

database/migrations/2026_09_08_140020_add_retention_reason_to_participant_refunds.php

@@ -0,0 +1,40 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Was beim Verband bleibt und warum.
+ *
+ * Nur belegt, wenn weniger erstattet wird als gezahlt wurde. Bei voller Erstattung bleiben die Felder
+ * leer bzw. auf 0 -- dann gibt es nichts zu begründen.
+ *
+ * `retained_amount` wird beim Einreichen festgeschrieben und nicht zur Laufzeit gerechnet: Danach führt
+ * `event_participants.amount_paid` bereits den Rest, eine Differenz daraus wäre ab dem Moment falsch.
+ */
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::table('participant_refunds', function (Blueprint $table) {
+            $table->string('retention_reason')->nullable()->after('reason_note');
+            $table->text('retention_reason_note')->nullable()->after('retention_reason');
+            $table->float('retained_amount', 2)->default(0)->after('retention_reason_note');
+        });
+
+        // Der Fremdschlüssel in einem eigenen Aufruf: zusammen mit dem Anlegen der Spalte hat MariaDB ihn
+        // hier stillschweigend übergangen, und ein `down()` lief anschließend ins Leere.
+        Schema::table('participant_refunds', function (Blueprint $table) {
+            $table->foreign('retention_reason')->references('slug')->on('retention_reasons')
+                ->restrictOnDelete()->cascadeOnUpdate();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('participant_refunds', function (Blueprint $table) {
+            $table->dropForeign(['retention_reason']);
+            $table->dropColumn(['retention_reason', 'retention_reason_note', 'retained_amount']);
+        });
+    }
+};

database/migrations/2026_09_09_140010_add_purchase_example_to_invoice_types.php

@@ -0,0 +1,53 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Das Beispiel, das im Feld „Was wurde eingekauft" steht, solange es leer ist.
+ *
+ * Die Angabe ist seit der EüR Pflicht zu jeder Abrechnung, und von ihr lebt dort die Zweck-Spalte. Ein
+ * allgemeines „z. B. Material" hilft beim Ausfüllen nicht weiter -- was ein brauchbarer Zweck ist, hängt
+ * an der Ausgabenart. Der Text gehört deshalb an den Typ und nicht in den Quelltext des Formulars: So
+ * lässt er sich ohne Deployment nachschärfen, und ein später ergänzter Typ bringt sein Beispiel mit.
+ *
+ * Bleibt die Spalte leer, zeigt das Formular seinen eigenen allgemeinen Text -- ein Typ ohne Beispiel
+ * soll das Feld nicht ohne Hilfestellung lassen.
+ */
+return new class extends Migration {
+    /**
+     * Die Ausgangstexte. Bewusst konkret: Sie sollen zeigen, wie genau eine Angabe gemeint ist.
+     */
+    private const array EXAMPLES = [
+        'travelling' => 'z. B. Bahnfahrt Halle–Leipzig',
+        'program' => 'z. B. Bastelmaterial für den Workshop',
+        'accommodation' => 'z. B. zwei Nächte Jugendherberge',
+        'catering' => 'z. B. Wocheneinkauf für das Frühstück',
+        'logistic' => 'z. B. Miete für den Transporter',
+        'technical' => 'z. B. Verlängerungskabel und Mehrfachstecker',
+        'management' => 'z. B. Porto und Kopien',
+        'other' => 'z. B. Erste-Hilfe-Set',
+    ];
+
+    public function up(): void
+    {
+        Schema::table('invoice_types', function (Blueprint $table) {
+            $table->string('purchase_example')->nullable()->after('name');
+        });
+
+        foreach (self::EXAMPLES as $slug => $example) {
+            DB::table('invoice_types')
+                ->where('slug', $slug)
+                ->update(['purchase_example' => $example]);
+        }
+    }
+
+    public function down(): void
+    {
+        Schema::table('invoice_types', function (Blueprint $table) {
+            $table->dropColumn('purchase_example');
+        });
+    }
+};

resources/views/emails/events/refund_accepted.blade.php

@@ -44,6 +44,13 @@
     </tr>
 </table>
 
+@if ($hasRetention)
+    <p style="padding: 10px 12px; border-left: 3px solid #f5c400; background-color: #fffef5;">
+        Von deinem gezahlten Beitrag verbleiben <strong>{{$retainedAmount}}</strong> beim Verband.<br />
+        Grund: {{$retentionReason}}@if ($retentionReasonNote) &ndash; {{$retentionReasonNote}}@endif
+    </p>
+@endif
+
 @if ($hasDocument)
     <p>
         Im Anhang findest du deinen Beleg über die Rückerstattung als PDF &ndash; nur zu deiner

resources/views/pdfs/income-surplus-statement.blade.php

@@ -0,0 +1,236 @@
+<!DOCTYPE html>
+<html lang="de">
+<head>
+    <meta charset="UTF-8">
+    <style>
+        @page {
+            margin: 15mm 12mm;
+        }
+
+        body {
+            font-family: DejaVu Sans, sans-serif;
+            font-size: 10pt;
+            color: #000;
+        }
+
+        h1 {
+            font-size: 15pt;
+            margin: 0 0 2mm;
+        }
+
+        h2 {
+            font-size: 11pt;
+            letter-spacing: 1px;
+            margin: 8mm 0 2mm;
+            border-bottom: 1px solid #000;
+            padding-bottom: 1mm;
+        }
+
+        .subline {
+            font-size: 9pt;
+            color: #444;
+            margin-bottom: 2mm;
+        }
+
+        /* Die Rechnung selbst: keine Rahmen, nur Linien vor den Summen -- so liest sich eine Aufstellung
+           schneller als eine Gittertabelle. */
+        table.statement {
+            width: 100%;
+            border-collapse: collapse;
+        }
+
+        table.statement td {
+            padding: 1.2mm 0;
+            vertical-align: top;
+        }
+
+        table.statement td.value {
+            text-align: right;
+            width: 30mm;
+            white-space: nowrap;
+        }
+
+        tr.category td {
+            font-weight: bold;
+            padding-top: 3mm;
+        }
+
+        tr.entry td.label {
+            padding-left: 8mm;
+            color: #333;
+        }
+
+        tr.entry td.value {
+            color: #333;
+        }
+
+        tr.sum td {
+            font-weight: bold;
+            border-top: 1px solid #000;
+            padding-top: 1.5mm;
+        }
+
+        tr.result td {
+            font-weight: bold;
+            font-size: 12pt;
+            padding-top: 5mm;
+        }
+
+        .positive { color: #4caf50; }
+        .negative { color: #f44336; }
+
+        .footnote {
+            margin-top: 10mm;
+            font-size: 8pt;
+            color: #444;
+            line-height: 1.4;
+        }
+
+        .page-break {
+            page-break-before: always;
+        }
+
+        /* Die Anlage bleibt eine klassische Belegtabelle mit Rahmen. */
+        table.receipts {
+            width: 100%;
+            border-collapse: collapse;
+            margin-bottom: 6mm;
+        }
+
+        table.receipts th,
+        table.receipts td {
+            border: 1px solid #000;
+            padding: 4px 6px;
+            font-size: 8pt;
+            vertical-align: top;
+        }
+
+        table.receipts th {
+            background: #f2f2f2;
+            font-weight: bold;
+            text-align: left;
+        }
+
+        table.receipts td.value,
+        table.receipts th.value {
+            text-align: right;
+            white-space: nowrap;
+            width: 22mm;
+        }
+
+        table.receipts tr.group-sum td {
+            font-weight: bold;
+            background: #fafafa;
+        }
+
+        h3 {
+            font-size: 10pt;
+            margin: 5mm 0 1.5mm;
+        }
+    </style>
+</head>
+<body>
+
+<h1>Einnahmen-Überschuss-Rechnung</h1>
+<div class="subline">
+    {{ $event->name }}
+    &middot; {{ $event->start_date->format('d.m.Y') }}&ndash;{{ $event->end_date->format('d.m.Y') }}
+    @if($event->location)&middot; {{ $event->location }}@endif
+    &middot; Stand: {{ $createdAt }}
+</div>
+
+<h2>Einnahmen</h2>
+<table class="statement">
+    @foreach($income['categories'] as $category)
+        <tr class="category">
+            <td>{{ $category['name'] }}</td>
+            <td class="value">{{ $money($category['total']) }} &euro;</td>
+        </tr>
+        @foreach($category['entries'] as $entry)
+            <tr class="entry">
+                <td class="label">{{ $entry['name'] }}</td>
+                <td class="value">{{ $money($entry['amount']) }} &euro;</td>
+            </tr>
+        @endforeach
+    @endforeach
+    <tr class="sum">
+        <td>Summe Einnahmen</td>
+        <td class="value">{{ $money($income['total']) }} &euro;</td>
+    </tr>
+</table>
+
+<h2>Ausgaben</h2>
+<table class="statement">
+    @foreach($expenses['groups'] as $group)
+        <tr class="entry">
+            <td class="label">{{ $group['name'] }}</td>
+            <td class="value">{{ $money($group['sum']) }} &euro;</td>
+        </tr>
+    @endforeach
+    <tr class="sum">
+        <td>Summe Ausgaben</td>
+        <td class="value">{{ $money($expenses['total']) }} &euro;</td>
+    </tr>
+</table>
+
+<table class="statement">
+    <tr class="result">
+        <td class="{{ $result->getAmount() >= 0 ? 'positive' : 'negative' }}">
+            {{ $result->getAmount() >= 0 ? 'Überschuss' : 'Fehlbetrag' }}
+        </td>
+        <td class="value {{ $result->getAmount() >= 0 ? 'positive' : 'negative' }}">
+            {{ $money($result) }} &euro;
+        </td>
+    </tr>
+</table>
+
+<div class="footnote">
+    Berücksichtigt sind nur tatsächlich vereinnahmte Beiträge und erfasste Belege. Nicht enthalten sind
+    offene Beiträge, Budget- und Schätzwerte, erstattete Beiträge sowie Auslagen, auf deren Auszahlung
+    verzichtet wurde.
+    @if($event->tax_liable)
+        <br />Alle Beträge sind Bruttobeträge inklusive {{ $event->vat_rate }} % Umsatzsteuer.
+    @endif
+</div>
+
+@php
+    $documentedGroups = array_filter($expenses['groups'], fn ($group) => count($group['rows']) > 0);
+@endphp
+
+@if(count($documentedGroups) > 0)
+    <div class="page-break"></div>
+
+    <h1>Anlage: Belege</h1>
+    <div class="subline">{{ $event->name }} &middot; Stand: {{ $createdAt }}</div>
+
+    @foreach($documentedGroups as $group)
+        <h3>{{ $group['name'] }}</h3>
+        <table class="receipts">
+            <thead>
+            <tr>
+                <th style="width: 22mm;">Beleg-Nr.</th>
+                <th style="width: 18mm;">Datum</th>
+                <th>Zweck</th>
+                <th class="value">Betrag</th>
+            </tr>
+            </thead>
+            <tbody>
+            @foreach($group['rows'] as $row)
+                <tr>
+                    <td>{{ $row['number'] }}</td>
+                    <td>{{ $row['date'] }}</td>
+                    <td>{{ $row['purpose'] }}</td>
+                    <td class="value">{{ $money($row['amount']) }} &euro;</td>
+                </tr>
+            @endforeach
+            <tr class="group-sum">
+                <td colspan="3">Zwischensumme {{ $group['name'] }}</td>
+                <td class="value">{{ $money($group['sum']) }} &euro;</td>
+            </tr>
+            </tbody>
+        </table>
+    @endforeach
+@endif
+
+</body>
+</html>

routes/web.php

@@ -57,6 +57,7 @@ Route::middleware(IdentifyTenant::class)->group(function () {
         Route::get('/retrieve-invoice-types-all', [GlobalDataProvider::class, 'getAllInvoiceTypes']);
         Route::get('/retrieve-event-setting-data', [GlobalDataProvider::class, 'getEventSettingData']);
         Route::get('/retrieve-refund-reasons', [GlobalDataProvider::class, 'getRefundReasons']);
+        Route::get('/retrieve-retention-reasons', [GlobalDataProvider::class, 'getRetentionReasons']);
 
     });
 });

tests/Feature/EventBudgetTest.php

@@ -0,0 +1,324 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Enumerations\CostUnitType;
+use App\Enumerations\EfzStatus;
+use App\Enumerations\InvoiceStatus;
+use App\Enumerations\InvoiceType;
+use App\Models\CostUnit;
+use App\Models\Event;
+use App\Models\Invoice;
+use App\Models\PaymentMethod;
+use App\Models\Tenant;
+use App\RelationModels\EventParticipationFee;
+use App\Resources\CostUnitResource;
+use App\Resources\EventResource;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Tests\TestCase;
+
+/**
+ * Die Ausgabenrechnung der Veranstaltungsübersicht.
+ *
+ * Eine Beitragserstattung gehört dort nicht hinein: Sie ist die Rücknahme einer Einnahme, und die
+ * Einnahmenseite hat sie bereits berücksichtigt -- ein abgemeldeter Teili fällt aus `getParticipants()`
+ * heraus. Als Ausgabe gezählt, ginge derselbe Vorgang ein zweites Mal in die Bilanz.
+ */
+class EventBudgetTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private Tenant $tenant;
+
+    private CostUnit $costUnit;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->tenant = Tenant::create([
+            'slug' => 'wm',
+            'name' => 'Wilde Möhre',
+            'email' => 't@example.com',
+            'email_finance' => 'finance@example.com',
+            'url' => parse_url(config('app.url'), PHP_URL_HOST),
+            'account_name' => 'Test e.V.',
+            'account_iban' => 'DE00',
+            'account_bic' => 'XY',
+            'city' => 'Stadt',
+            'postcode' => '00000',
+            'invoice_prefix' => 'WM',
+            'is_active_local_group' => true,
+            'has_active_instance' => true,
+        ]);
+
+        app()->instance('tenant', $this->tenant);
+
+        DB::table('participation_types')->insert(['slug' => 'participant', 'name' => 'Teilnehmer']);
+        DB::table('participation_fee_types')->insert(['slug' => 'fixed', 'name' => 'Fix']);
+        DB::table('cost_unit_types')->insert(['slug' => CostUnitType::COST_UNIT_TYPE_EVENT, 'name' => 'Veranstaltung']);
+        DB::table('invoice_status')->insert(['slug' => InvoiceStatus::INVOICE_STATUS_NEW]);
+        PaymentMethod::create(['slug' => PaymentMethod::PAYMENT_ACCOUNT_TRANSACTION]);
+        EfzStatus::create(['slug' => EfzStatus::EFZ_STATUS_NOT_REQUIRED, 'name' => 'Nicht erforderlich']);
+
+        // Ein gewöhnlicher Aufwandstyp zum Vergleich; die Beitragserstattung bringt die Migration mit.
+        DB::table('invoice_types')->insert([
+            'slug' => InvoiceType::INVOICE_TYPE_PROGRAM,
+            'name' => 'Programmkosten',
+            'sort_order' => 1,
+            'selectable' => true,
+            'counts_as_expense' => true,
+        ]);
+
+        $this->costUnit = CostUnit::create([
+            'tenant' => $this->tenant->slug,
+            'name' => 'Sommerlager',
+            'type' => CostUnitType::COST_UNIT_TYPE_EVENT,
+            'distance_allowance' => 0.25,
+            'mail_on_new' => false,
+            'allow_new' => true,
+            'archived' => false,
+        ]);
+    }
+
+    private function makeEvent(): Event
+    {
+        $fee = EventParticipationFee::create([
+            'tenant' => $this->tenant->slug,
+            'type' => 'participant',
+            'name' => 'Sippe',
+            'description' => null,
+            'amount_standard' => 60.0,
+            'amount_reduced' => null,
+            'amount_solidarity' => null,
+        ]);
+
+        return Event::create([
+            'cost_unit_id' => $this->costUnit->id,
+            'tenant' => $this->tenant->slug,
+            'name' => 'Sommerlager',
+            'identifier' => 'evt-' . uniqid(),
+            'location' => 'Ort',
+            'postal_code' => '00000',
+            'email' => 'e@example.com',
+            'start_date' => '2026-07-16',
+            'end_date' => '2026-07-20',
+            'early_bird_end' => '2026-06-20',
+            'registration_final_end' => '2026-07-01',
+            'early_bird_end_amount_increase' => 0,
+            'account_owner' => 'Owner',
+            'account_iban' => 'DE00',
+            'participation_fee_type' => 'fixed',
+            'participation_fee_1' => $fee->id,
+            'pay_per_day' => true,
+            'pay_direct' => false,
+            'tax_liable' => false,
+            'vat_rate' => 0,
+            'vat_pricing_mode' => 'inclusive',
+            'invoice_key' => 'WM-V-20260701',
+        ]);
+    }
+
+    private function makeInvoice(string $type, float $amount): Invoice
+    {
+        return Invoice::create([
+            'tenant' => $this->tenant->slug,
+            'cost_unit_id' => $this->costUnit->id,
+            'invoice_number' => '2026-' . str_pad((string) Invoice::count() + 1, 4, '0', STR_PAD_LEFT),
+            'status' => InvoiceStatus::INVOICE_STATUS_NEW,
+            'type' => $type,
+            'donation' => false,
+            'contact_name' => 'Mika Muster',
+            'amount' => $amount,
+        ]);
+    }
+
+    /** @return array<string, mixed> */
+    private function costUnitData(): array
+    {
+        return new CostUnitResource($this->costUnit->fresh())->toArray(true);
+    }
+
+    /*
+    |--------------------------------------------------------------------------
+    | Die Ausgabenliste
+    |--------------------------------------------------------------------------
+    */
+
+    public function test_a_refund_does_not_appear_as_an_expense_row(): void
+    {
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PARTICIPATION_REFUND, 220.0);
+
+        $amounts = $this->costUnitData()['amounts'];
+
+        $this->assertArrayNotHasKey(InvoiceType::INVOICE_TYPE_PARTICIPATION_REFUND, $amounts);
+        $this->assertArrayHasKey(InvoiceType::INVOICE_TYPE_PROGRAM, $amounts);
+    }
+
+    public function test_a_refund_is_not_part_of_the_expense_total(): void
+    {
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PARTICIPATION_REFUND, 220.0);
+
+        $this->assertEqualsWithDelta(0.0, $this->costUnitData()['overAllAmount']['value']->getAmount(), 0.001);
+    }
+
+    public function test_an_ordinary_invoice_of_the_same_amount_does_count(): void
+    {
+        // Gegenprobe: Es liegt am Typ, nicht am Betrag.
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PROGRAM, 220.0);
+
+        $this->assertEqualsWithDelta(220.0, $this->costUnitData()['overAllAmount']['value']->getAmount(), 0.001);
+    }
+
+    public function test_the_cash_view_still_shows_the_refund(): void
+    {
+        // `totalAmount` speist Kostenstellen-Liste und Dashboard -- dort fließt das Geld tatsächlich ab.
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PARTICIPATION_REFUND, 220.0);
+
+        $this->assertStringContainsString('220,00', $this->costUnitData()['totalAmount']);
+    }
+
+    /*
+    |--------------------------------------------------------------------------
+    | Die Bilanz der Veranstaltung
+    |--------------------------------------------------------------------------
+    */
+
+    public function test_the_balance_is_not_reduced_by_a_refund(): void
+    {
+        // `fresh()`, weil die DB-Vorgaben (Förderung, Höchstbetrag) im frisch erzeugten Model noch nicht
+        // geladen sind und EventResource sie als Amount erwartet.
+        $event = $this->makeEvent()->fresh();
+        $before = new EventResource($event)->toArray(new Request())['totalBalance']['real']['value'];
+
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PARTICIPATION_REFUND, 220.0);
+
+        $after = new EventResource($event->fresh())->toArray(new Request())['totalBalance']['real']['value'];
+
+        $this->assertEqualsWithDelta($before, $after, 0.001);
+    }
+
+    public function test_the_balance_is_reduced_by_an_ordinary_invoice(): void
+    {
+        // `fresh()`, weil die DB-Vorgaben (Förderung, Höchstbetrag) im frisch erzeugten Model noch nicht
+        // geladen sind und EventResource sie als Amount erwartet.
+        $event = $this->makeEvent()->fresh();
+        $before = new EventResource($event)->toArray(new Request())['totalBalance']['real']['value'];
+
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PROGRAM, 220.0);
+
+        $after = new EventResource($event->fresh())->toArray(new Request())['totalBalance']['real']['value'];
+
+        $this->assertEqualsWithDelta($before - 220.0, $after, 0.001);
+    }
+
+    /*
+    |--------------------------------------------------------------------------
+    | Beiträge abgemeldeter Teilis
+    |--------------------------------------------------------------------------
+    */
+
+    public function test_money_left_by_unregistered_participants_counts_as_income(): void
+    {
+        $event = $this->makeEvent();
+        $before = new EventResource($event->fresh())->toArray(new Request());
+
+        // 80 € sind nach einer Teilerstattung beim Verband geblieben.
+        $this->makeUnregisteredParticipant($event, 80.0);
+
+        $after = new EventResource($event->fresh())->toArray(new Request());
+
+        $this->assertEqualsWithDelta(80.0, $after['retainedFromUnregistered']['value'], 0.001);
+
+        // In beide Spalten: Das Geld ist da (real) und fließt nicht mehr ab (erwartet).
+        $this->assertEqualsWithDelta(
+            $before['income']['real']['amount']->getAmount() + 80.0,
+            $after['income']['real']['amount']->getAmount(),
+            0.001
+        );
+        $this->assertEqualsWithDelta(
+            $before['income']['expected']['amount']->getAmount() + 80.0,
+            $after['income']['expected']['amount']->getAmount(),
+            0.001
+        );
+        $this->assertEqualsWithDelta(
+            $before['totalBalance']['real']['value'] + 80.0,
+            $after['totalBalance']['real']['value'],
+            0.001
+        );
+    }
+
+    public function test_unregistered_participants_stay_out_of_lists_and_counts(): void
+    {
+        $event = $this->makeEvent();
+        $this->makeUnregisteredParticipant($event, 80.0);
+
+        $participantData = new EventResource($event->fresh())
+            ->toArray(new Request())['participants']['participant'];
+
+        // Nur die Geldsumme kommt hinzu -- in Listen und Zahlen bleiben Abgemeldete außen vor.
+        $this->assertSame(0, $participantData['count']);
+        $this->assertArrayNotHasKey('participants', $participantData);
+        $this->assertEqualsWithDelta(0.0, $participantData['amount']['paid']['value'], 0.001);
+    }
+
+    public function test_the_funding_does_not_grow_with_unregistered_participants(): void
+    {
+        $event = $this->makeEvent();
+        $before = new EventResource($event->fresh())->toArray(new Request())['supportPerson']['amount']->getAmount();
+
+        $this->makeUnregisteredParticipant($event, 80.0);
+
+        $after = new EventResource($event->fresh())->toArray(new Request())['supportPerson']['amount']->getAmount();
+
+        // Die wichtigste Gegenprobe: Wer nicht da war, bringt keine Förderung.
+        $this->assertEqualsWithDelta($before, $after, 0.001);
+    }
+
+    public function test_the_row_is_hidden_when_nothing_was_retained(): void
+    {
+        $event = $this->makeEvent();
+        $this->makeUnregisteredParticipant($event, 0.0);
+
+        // Die Zeile in der Übersicht hängt an diesem Wert -- bei 0 soll sie nicht erscheinen.
+        $this->assertEqualsWithDelta(
+            0.0,
+            new EventResource($event->fresh())->toArray(new Request())['retainedFromUnregistered']['value'],
+            0.001
+        );
+    }
+
+    /** Ein abgemeldeter Teili, bei dem der übergebene Betrag beim Verband geblieben ist. */
+    private function makeUnregisteredParticipant(Event $event, float $remaining): void
+    {
+        $event->participants()->create([
+            'tenant' => $this->tenant->slug,
+            'identifier' => 'p-' . uniqid(),
+            'invoice_sequence' => $event->participants()->count() + 1,
+            'firstname' => 'Mika',
+            'lastname' => 'Muster',
+            'participation_type' => 'participant',
+            'fee_type' => 'standard',
+            'sibling_reduction' => false,
+            'local_group' => $this->tenant->slug,
+            'birthday' => '2000-01-01',
+            'address_1' => 'Beispielstraße 3',
+            'postcode' => '11111',
+            'city' => 'Beispielstadt',
+            'email_1' => 'mika@example.com',
+            'phone_1' => '0170 0000000',
+            'arrival_date' => '2026-07-16',
+            'departure_date' => '2026-07-20',
+            'arrival_eating' => 1,
+            'departure_eating' => 1,
+            'amount' => 300.0,
+            'amount_paid' => $remaining,
+            'unregistered_at' => '2026-06-12',
+            'payment_purpose' => 'Sommerlager',
+            'payment_method' => PaymentMethod::PAYMENT_ACCOUNT_TRANSACTION,
+            'efz_status' => EfzStatus::EFZ_STATUS_NOT_REQUIRED,
+        ]);
+    }
+}

tests/Feature/EventIncomeSurplusStatementTest.php

@@ -0,0 +1,504 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Domains\Event\Actions\CreateIncomeSurplusStatement\CreateIncomeSurplusStatementCommand;
+use App\Domains\Event\Actions\CreateIncomeSurplusStatement\CreateIncomeSurplusStatementRequest;
+use App\Domains\Event\Actions\CreateIncomeSurplusStatement\CreateIncomeSurplusStatementResponse;
+use App\Enumerations\CostUnitType;
+use App\Enumerations\EatingHabit;
+use App\Enumerations\EfzStatus;
+use App\Enumerations\FirstAidPermission;
+use App\Enumerations\InvoiceStatus;
+use App\Enumerations\InvoiceType;
+use App\Enumerations\SwimmingPermission;
+use App\Enumerations\UserRole;
+use App\Models\CostUnit;
+use App\Models\Event;
+use App\Models\Invoice;
+use App\Models\PaymentMethod;
+use App\Models\Tenant;
+use App\Models\User;
+use App\RelationModels\EventParticipationFee;
+use App\Repositories\CostUnitRepository;
+use App\Resources\CostUnitResource;
+use App\ValueObjects\Amount;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\DB;
+use Tests\TestCase;
+
+/**
+ * Die Einnahmen-Überschuss-Rechnung einer Veranstaltung.
+ *
+ * Sie zeigt ausschließlich Geld, das geflossen ist. Was nur erwartet wird (offene Beiträge) oder geplant
+ * ist (Budgetwerte), gehört nicht hinein -- ebenso wenig ein Beleg, der abgelehnt, gelöscht oder gespendet
+ * wurde.
+ */
+class EventIncomeSurplusStatementTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private Tenant $tenant;
+
+    private CostUnit $costUnit;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->tenant = Tenant::create([
+            'slug' => 'wm',
+            'name' => 'Wilde Möhre',
+            'email' => 't@example.com',
+            'email_finance' => 'finance@example.com',
+            'url' => parse_url(config('app.url'), PHP_URL_HOST),
+            'account_name' => 'Test e.V.',
+            'account_iban' => 'DE00',
+            'account_bic' => 'XY',
+            'city' => 'Stadt',
+            'postcode' => '00000',
+            'invoice_prefix' => 'WM',
+            'is_active_local_group' => true,
+            'has_active_instance' => true,
+        ]);
+
+        app()->instance('tenant', $this->tenant);
+
+        DB::table('participation_types')->insert(['slug' => 'participant', 'name' => 'Teilnehmer']);
+        DB::table('participation_fee_types')->insert(['slug' => 'fixed', 'name' => 'Fix']);
+        DB::table('cost_unit_types')->insert(['slug' => CostUnitType::COST_UNIT_TYPE_EVENT, 'name' => 'Veranstaltung']);
+        PaymentMethod::create(['slug' => PaymentMethod::PAYMENT_ACCOUNT_TRANSACTION]);
+        EfzStatus::create(['slug' => EfzStatus::EFZ_STATUS_NOT_REQUIRED, 'name' => 'Nicht erforderlich']);
+
+        // Aktive Anmeldungen laufen für die Fördertage durch `EventParticipantResource`, und die liest
+        // Erlaubnisse und Essgewohnheit ohne Null-Prüfung.
+        EatingHabit::create([
+            'slug' => EatingHabit::EATING_HABIT_OMNIVOR,
+            'name' => 'Alles',
+        ]);
+        SwimmingPermission::create([
+            'slug' => SwimmingPermission::SWIMMING_PERMISSION_ALLOWED,
+            'name' => 'Erlaubt',
+            'short' => 'ja',
+        ]);
+        FirstAidPermission::create([
+            'slug' => FirstAidPermission::FIRST_AID_PERMISSION_ALLOWED,
+            'name' => 'Erlaubt',
+            'description' => 'Erlaubt',
+        ]);
+
+        foreach ([
+            InvoiceStatus::INVOICE_STATUS_NEW,
+            InvoiceStatus::INVOICE_STATUS_APPROVED,
+            InvoiceStatus::INVOICE_STATUS_EXPORTED,
+            InvoiceStatus::INVOICE_STATUS_DENIED,
+            InvoiceStatus::INVOICE_STATUS_DELETED,
+        ] as $status) {
+            DB::table('invoice_status')->insert(['slug' => $status]);
+        }
+
+        foreach ([UserRole::USER_ROLE_ADMIN, UserRole::USER_ROLE_GROUP_LEADER, UserRole::USER_ROLE_USER] as $role) {
+            UserRole::create(['slug' => $role, 'name' => $role]);
+        }
+
+        // Zwei gewöhnliche Aufwandstypen plus einer, der leer bleibt; die Beitragserstattung bringt die
+        // Migration mit.
+        foreach ([
+            [InvoiceType::INVOICE_TYPE_PROGRAM, 'Programmkosten', 1],
+            [InvoiceType::INVOICE_TYPE_CATERING, 'Verpflegungskosten', 1],
+            [InvoiceType::INVOICE_TYPE_OTHER, 'Sonstige Kosten', 3],
+        ] as [$slug, $name, $sortOrder]) {
+            DB::table('invoice_types')->insert([
+                'slug' => $slug,
+                'name' => $name,
+                'sort_order' => $sortOrder,
+                'selectable' => true,
+                'counts_as_expense' => true,
+            ]);
+        }
+
+        $this->costUnit = CostUnit::create([
+            'tenant' => $this->tenant->slug,
+            'name' => 'Sommerlager',
+            'type' => CostUnitType::COST_UNIT_TYPE_EVENT,
+            'distance_allowance' => 0.25,
+            'mail_on_new' => false,
+            'allow_new' => true,
+            'archived' => false,
+        ]);
+    }
+
+    /*
+    |--------------------------------------------------------------------------
+    | Einnahmen
+    |--------------------------------------------------------------------------
+    */
+
+    public function test_only_paid_contributions_count(): void
+    {
+        $event = $this->makeEvent();
+        $this->makeParticipant($event, amount: 300.0, amountPaid: 300.0);
+        $this->makeParticipant($event, amount: 300.0, amountPaid: 0.0);
+
+        // 600 € wurden erwartet, 300 € sind angekommen -- die EÜR kennt nur die 300.
+        $this->assertEqualsWithDelta(300.0, $this->entry('Teilnahmebeiträge')->getAmount(), 0.001);
+    }
+
+    public function test_money_retained_from_unregistered_participants_is_its_own_line(): void
+    {
+        $event = $this->makeEvent();
+        $this->makeParticipant($event, amount: 300.0, amountPaid: 300.0);
+        $this->makeParticipant($event, amount: 300.0, amountPaid: 80.0, unregistered: true);
+
+        // Der Rest einer Teilerstattung liegt beim Verband, gehört aber nicht zu den Beiträgen: Dort
+        // stehen nur aktive Anmeldungen.
+        $this->assertEqualsWithDelta(300.0, $this->entry('Teilnahmebeiträge')->getAmount(), 0.001);
+        $this->assertEqualsWithDelta(80.0, $this->entry('Einbehaltene Einnahmen aus Abmeldungen')->getAmount(), 0.001);
+    }
+
+    public function test_the_two_income_categories_add_up(): void
+    {
+        $event = $this->makeEvent();
+        $this->makeParticipant($event, amount: 300.0, amountPaid: 300.0);
+        $this->makeParticipant($event, amount: 300.0, amountPaid: 80.0, unregistered: true);
+
+        $income = $this->statement()->income;
+
+        // Eigenmittel: 300 Beiträge + 1000 weitere Einnahmen + 80 einbehalten.
+        $this->assertSame('Eigenmittel', $income['categories'][0]['name']);
+        $this->assertEqualsWithDelta(1000.0, $this->entry('Weitere Einnahmen')->getAmount(), 0.001);
+        $this->assertEqualsWithDelta(1380.0, $income['categories'][0]['total']->getAmount(), 0.001);
+
+        // Förderungen: 2,00 € p.P./Tag über 4 Fördertage der einen aktiven Anmeldung.
+        $this->assertSame('Förderungen', $income['categories'][1]['name']);
+        $this->assertEqualsWithDelta(8.0, $income['categories'][1]['total']->getAmount(), 0.001);
+
+        $this->assertEqualsWithDelta(1388.0, $income['total']->getAmount(), 0.001);
+    }
+
+    public function test_the_funding_line_names_the_rate(): void
+    {
+        $this->makeEvent();
+
+        $funding = $this->statement()->income['categories'][1]['entries'][0];
+
+        $this->assertSame('Fördermittel (2,00 € p.P./Tag)', $funding['name']);
+    }
+
+    /*
+    |--------------------------------------------------------------------------
+    | Ausgaben
+    |--------------------------------------------------------------------------
+    */
+
+    public function test_only_receipts_representing_real_money_count(): void
+    {
+        $this->makeEvent();
+
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PROGRAM, 100.0, InvoiceStatus::INVOICE_STATUS_NEW);
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PROGRAM, 50.0, InvoiceStatus::INVOICE_STATUS_APPROVED);
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_CATERING, 30.0, InvoiceStatus::INVOICE_STATUS_EXPORTED);
+
+        // Kein Geldfluss, also keine Ausgabe:
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PROGRAM, 999.0, InvoiceStatus::INVOICE_STATUS_DENIED);
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PROGRAM, 888.0, InvoiceStatus::INVOICE_STATUS_DELETED);
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PROGRAM, 777.0, InvoiceStatus::INVOICE_STATUS_NEW, donation: true);
+
+        $this->assertEqualsWithDelta(150.0, $this->group('Programmkosten')['sum']->getAmount(), 0.001);
+        $this->assertEqualsWithDelta(30.0, $this->group('Verpflegungskosten')['sum']->getAmount(), 0.001);
+        $this->assertEqualsWithDelta(180.0, $this->statement()->expenses['total']->getAmount(), 0.001);
+    }
+
+    public function test_a_refund_is_no_expense(): void
+    {
+        $this->makeEvent();
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PARTICIPATION_REFUND, 220.0, InvoiceStatus::INVOICE_STATUS_EXPORTED);
+
+        $expenses = $this->statement()->expenses;
+
+        $this->assertEqualsWithDelta(0.0, $expenses['total']->getAmount(), 0.001);
+        $this->assertSame(
+            [],
+            array_values(array_filter($expenses['groups'], fn ($group) => $group['name'] === 'Beitragserstattung'))
+        );
+    }
+
+    public function test_every_expense_type_gets_a_row_even_without_receipts(): void
+    {
+        $this->makeEvent();
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PROGRAM, 100.0, InvoiceStatus::INVOICE_STATUS_NEW);
+
+        $groups = $this->statement()->expenses['groups'];
+
+        // Die Gliederung bleibt vollständig -- eine fehlende Zeile ließe sich sonst mit einer vergessenen
+        // verwechseln.
+        $this->assertSame(
+            ['Programmkosten', 'Verpflegungskosten', 'Sonstige Kosten'],
+            array_column($groups, 'name')
+        );
+        $this->assertEqualsWithDelta(0.0, $this->group('Verpflegungskosten')['sum']->getAmount(), 0.001);
+    }
+
+    public function test_a_type_without_receipts_has_no_attachment_rows(): void
+    {
+        $this->makeEvent();
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PROGRAM, 100.0, InvoiceStatus::INVOICE_STATUS_NEW);
+
+        $this->assertCount(1, $this->group('Programmkosten')['rows']);
+        $this->assertCount(0, $this->group('Verpflegungskosten')['rows']);
+    }
+
+    public function test_the_attachment_names_the_purpose_for_every_type(): void
+    {
+        // "Was wurde eingekauft" wird zu jeder Abrechnung erfasst, nicht nur zu "Sonstige Kosten" --
+        // dadurch trägt die Zweck-Spalte auch bei Programmkosten eine Aussage.
+        $this->makeEvent();
+        $this->makeInvoice(
+            InvoiceType::INVOICE_TYPE_PROGRAM,
+            100.0,
+            InvoiceStatus::INVOICE_STATUS_EXPORTED,
+            typeOther: 'Bastelmaterial'
+        );
+
+        $this->assertSame('Bastelmaterial — Materialkauf', $this->group('Programmkosten')['rows'][0]['purpose']);
+    }
+
+    public function test_an_older_receipt_without_the_purchase_note_falls_back_to_the_comment(): void
+    {
+        // Belege von vor der Pflichtangabe haben `type_other` leer.
+        $this->makeEvent();
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PROGRAM, 100.0, InvoiceStatus::INVOICE_STATUS_NEW);
+
+        $this->assertSame('Materialkauf', $this->group('Programmkosten')['rows'][0]['purpose']);
+    }
+
+    /*
+    |--------------------------------------------------------------------------
+    | Ergebnis und Auslieferung
+    |--------------------------------------------------------------------------
+    */
+
+    public function test_the_result_is_income_minus_expenses(): void
+    {
+        $event = $this->makeEvent();
+        $this->makeParticipant($event, amount: 300.0, amountPaid: 300.0);
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PROGRAM, 100.0, InvoiceStatus::INVOICE_STATUS_NEW);
+
+        $statement = $this->statement();
+
+        $this->assertEqualsWithDelta(
+            $statement->income['total']->getAmount() - $statement->expenses['total']->getAmount(),
+            $statement->result->getAmount(),
+            0.001
+        );
+    }
+
+    public function test_amounts_are_printed_in_german_notation(): void
+    {
+        // `Amount::getFormattedAmount()` ersetzt jeden Punkt durch ein Komma und macht aus 1.487,50 ein
+        // "1,487,50". Auf einer Aufstellung mit vierstelligen Beträgen wäre das nicht lesbar.
+        $this->assertSame('1.487,50', CreateIncomeSurplusStatementCommand::money(new Amount(1487.5, 'Euro')));
+        $this->assertSame('0,00', CreateIncomeSurplusStatementCommand::money(new Amount(0.0, 'Euro')));
+        $this->assertSame('-320,00', CreateIncomeSurplusStatementCommand::money(new Amount(-320.0, 'Euro')));
+    }
+
+    public function test_the_route_delivers_a_pdf_and_does_not_hit_the_list_wildcard(): void
+    {
+        $event = $this->makeEvent();
+        $this->actingAs($this->makeAdmin());
+
+        $response = $this->get('/event/details/' . $event->identifier . '/pdf/income-surplus-statement');
+
+        $response->assertOk();
+        $response->assertHeader('Content-Type', 'application/pdf');
+        $this->assertStringContainsString('EUER-' . $event->identifier . '.pdf', $response->headers->get('Content-Disposition'));
+        $this->assertStringStartsWith('%PDF', $response->getContent());
+    }
+
+    /*
+    |--------------------------------------------------------------------------
+    | Rückwirkung auf die Ausgabenübersicht
+    |--------------------------------------------------------------------------
+    */
+
+    public function test_a_deleted_receipt_no_longer_counts_in_the_expense_overview(): void
+    {
+        // Dieselbe Regel wie in der EÜR: Ein gelöschter Beleg ist keine Ausgabe. Vor dem Fix zählte er in
+        // `sumupByInvoiceType()` weiter und verfälschte damit Ausgabenübersicht und Bilanz.
+        $this->makeEvent();
+        $this->makeInvoice(InvoiceType::INVOICE_TYPE_PROGRAM, 888.0, InvoiceStatus::INVOICE_STATUS_DELETED);
+
+        $amount = new CostUnitRepository()->sumupByInvoiceType(
+            $this->costUnit->fresh(),
+            InvoiceType::where('slug', InvoiceType::INVOICE_TYPE_PROGRAM)->first()
+        );
+
+        $this->assertEqualsWithDelta(0.0, $amount->getAmount(), 0.001);
+        $this->assertEqualsWithDelta(
+            0.0,
+            new CostUnitResource($this->costUnit->fresh())->toArray(true)['overAllAmount']['value']->getAmount(),
+            0.001
+        );
+    }
+
+    /*
+    |--------------------------------------------------------------------------
+    | Helfer
+    |--------------------------------------------------------------------------
+    */
+
+    private function statement(): CreateIncomeSurplusStatementResponse
+    {
+        // `fresh()`, weil die DB-Vorgaben (Höchstbetrag) im frisch erzeugten Model noch nicht geladen sind
+        // und EventResource sie als Amount erwartet.
+        $event = Event::where('cost_unit_id', $this->costUnit->id)->first()->fresh();
+
+        $response = new CreateIncomeSurplusStatementCommand(
+            new CreateIncomeSurplusStatementRequest($event)
+        )->execute();
+
+        $this->assertTrue($response->success, $response->message ?? '');
+
+        return $response;
+    }
+
+    /** Der Betrag einer Unterzeile der Einnahmenseite, über alle Kategorien gesucht. */
+    private function entry(string $name): Amount
+    {
+        foreach ($this->statement()->income['categories'] as $category) {
+            foreach ($category['entries'] as $entry) {
+                if ($entry['name'] === $name) {
+                    return $entry['amount'];
+                }
+            }
+        }
+
+        $this->fail('Einnahmen-Zeile "' . $name . '" fehlt.');
+    }
+
+    /** @return array{name: string, sum: Amount, rows: array<int, array<string, mixed>>} */
+    private function group(string $name): array
+    {
+        foreach ($this->statement()->expenses['groups'] as $group) {
+            if ($group['name'] === $name) {
+                return $group;
+            }
+        }
+
+        $this->fail('Ausgaben-Gruppe "' . $name . '" fehlt.');
+    }
+
+    private function makeEvent(): Event
+    {
+        $fee = EventParticipationFee::create([
+            'tenant' => $this->tenant->slug,
+            'type' => 'participant',
+            'name' => 'Sippe',
+            'description' => null,
+            'amount_standard' => 60.0,
+            'amount_reduced' => null,
+            'amount_solidarity' => null,
+        ]);
+
+        return Event::create([
+            'cost_unit_id' => $this->costUnit->id,
+            'tenant' => $this->tenant->slug,
+            'name' => 'Sommerlager',
+            'identifier' => 'evt-' . uniqid(),
+            'location' => 'Ort',
+            'postal_code' => '00000',
+            'email' => 'e@example.com',
+            'start_date' => '2026-07-16',
+            'end_date' => '2026-07-20',
+            'early_bird_end' => '2026-06-20',
+            'registration_final_end' => '2026-07-01',
+            'early_bird_end_amount_increase' => 0,
+            'account_owner' => 'Owner',
+            'account_iban' => 'DE00',
+            'participation_fee_type' => 'fixed',
+            'participation_fee_1' => $fee->id,
+            'pay_per_day' => true,
+            'pay_direct' => false,
+            'support_flat' => 1000.0,
+            'support_per_person' => 2.0,
+            'tax_liable' => false,
+            'vat_rate' => 0,
+            'vat_pricing_mode' => 'inclusive',
+            'invoice_key' => 'WM-V-20260701',
+        ]);
+    }
+
+    private function makeParticipant(
+        Event $event,
+        float $amount,
+        float $amountPaid,
+        bool $unregistered = false
+    ): void {
+        $event->participants()->create([
+            'tenant' => $this->tenant->slug,
+            'identifier' => 'p-' . uniqid(),
+            'invoice_sequence' => $event->participants()->count() + 1,
+            'firstname' => 'Mika',
+            'lastname' => 'Muster',
+            'participation_type' => 'participant',
+            'fee_type' => 'standard',
+            'sibling_reduction' => false,
+            'local_group' => $this->tenant->slug,
+            'birthday' => '2000-01-01',
+            'address_1' => 'Beispielstraße 3',
+            'postcode' => '11111',
+            'city' => 'Beispielstadt',
+            'email_1' => 'mika@example.com',
+            'phone_1' => '0170 0000000',
+            'arrival_date' => '2026-07-16',
+            'departure_date' => '2026-07-20',
+            'eating_habit' => EatingHabit::EATING_HABIT_OMNIVOR,
+            'arrival_eating' => 1,
+            'departure_eating' => 1,
+            'amount' => $amount,
+            'amount_paid' => $amountPaid,
+            'unregistered_at' => $unregistered ? '2026-06-12' : null,
+            'swimming_permission' => SwimmingPermission::SWIMMING_PERMISSION_ALLOWED,
+            'first_aid_permission' => FirstAidPermission::FIRST_AID_PERMISSION_ALLOWED,
+            'payment_purpose' => 'Sommerlager',
+            'payment_method' => PaymentMethod::PAYMENT_ACCOUNT_TRANSACTION,
+            'efz_status' => EfzStatus::EFZ_STATUS_NOT_REQUIRED,
+        ]);
+    }
+
+    private function makeInvoice(
+        string $type,
+        float $amount,
+        string $status,
+        bool $donation = false,
+        ?string $typeOther = null
+    ): Invoice {
+        return Invoice::create([
+            'tenant' => $this->tenant->slug,
+            'cost_unit_id' => $this->costUnit->id,
+            'invoice_number' => '2026-' . str_pad((string) (Invoice::count() + 1), 4, '0', STR_PAD_LEFT),
+            'status' => $status,
+            'type' => $type,
+            'type_other' => $typeOther,
+            'donation' => $donation,
+            'contact_name' => 'Mika Muster',
+            'comment' => 'Materialkauf',
+            'amount' => $amount,
+        ]);
+    }
+
+    private function makeAdmin(): User
+    {
+        return User::create([
+            'username' => 'admin-' . uniqid() . '@example.com',
+            'email' => 'admin-' . uniqid() . '@example.com',
+            'firstname' => 'Test',
+            'lastname' => 'Person',
+            'password' => bcrypt('secret'),
+            'local_group' => $this->tenant->slug,
+            'user_role_main' => UserRole::USER_ROLE_USER,
+            'user_role_local_group' => UserRole::USER_ROLE_ADMIN,
+            'active' => true,
+        ]);
+    }
+}

tests/Feature/InvoiceTypeSelectionTest.php

@@ -40,13 +40,41 @@ class InvoiceTypeSelectionTest extends TestCase
 
         app()->instance('tenant', $tenant);
 
-        // Zwei wählbare Typen neben der Beitragserstattung, die aus der Migration kommt.
+        // Zwei wählbare Typen neben der Beitragserstattung, die aus der Migration kommt. Nur einer trägt
+        // ein Einkaufsbeispiel -- der andere prüft den Fall einer ungepflegten Spalte.
         DB::table('invoice_types')->insert([
-            ['slug' => InvoiceType::INVOICE_TYPE_PROGRAM, 'name' => 'Programmkosten', 'sort_order' => 1, 'selectable' => true],
+            [
-            ['slug' => InvoiceType::INVOICE_TYPE_OTHER, 'name' => 'Sonstige Kosten', 'sort_order' => 3, 'selectable' => true],
+                'slug' => InvoiceType::INVOICE_TYPE_PROGRAM,
+                'name' => 'Programmkosten',
+                'purchase_example' => 'z. B. Bastelmaterial für den Workshop',
+                'sort_order' => 1,
+                'selectable' => true,
+            ],
+            [
+                'slug' => InvoiceType::INVOICE_TYPE_OTHER,
+                'name' => 'Sonstige Kosten',
+                'purchase_example' => null,
+                'sort_order' => 3,
+                'selectable' => true,
+            ],
         ]);
     }
 
+    public function test_the_form_receives_the_purchase_example_of_each_type(): void
+    {
+        // Das Beispiel im Feld "Was wurde eingekauft" wird in der Tabelle gepflegt, nicht im Formular --
+        // sonst bräuchte jede Textänderung ein Deployment.
+        $response = $this->getJson('/api/v1/core/retrieve-invoice-types');
+
+        $response->assertOk();
+        $examples = array_column($response->json('invoiceTypes'), 'purchaseExample', 'slug');
+
+        $this->assertSame('z. B. Bastelmaterial für den Workshop', $examples[InvoiceType::INVOICE_TYPE_PROGRAM]);
+
+        // Ungepflegt: Das Formular setzt dann seinen eigenen allgemeinen Text ein.
+        $this->assertNull($examples[InvoiceType::INVOICE_TYPE_OTHER]);
+    }
+
     public function test_the_refund_type_exists_but_is_not_selectable(): void
     {
         // `where` und nicht `find`: InvoiceType deklariert keinen Primärschlüssel, `find` suchte nach `id`.
@@ -90,4 +118,16 @@ class InvoiceTypeSelectionTest extends TestCase
             InvoiceType::selectable()->pluck('slug')->all()
         );
     }
+
+    public function test_the_refund_type_does_not_count_as_an_expense(): void
+    {
+        // Sie mindert die Einnahmenseite bereits -- als Ausgabe gezählt, stünde sie zweimal in der Bilanz.
+        $this->assertSame(
+            [InvoiceType::INVOICE_TYPE_PROGRAM, InvoiceType::INVOICE_TYPE_OTHER],
+            InvoiceType::countingAsExpense()->pluck('slug')->all()
+        );
+
+        $type = InvoiceType::where('slug', InvoiceType::INVOICE_TYPE_PARTICIPATION_REFUND)->first();
+        $this->assertFalse($type->counts_as_expense);
+    }
 }

tests/Feature/ParticipantRefundTest.php

@@ -14,6 +14,7 @@ use App\Enumerations\CostUnitType;
 use App\Enumerations\InvoiceStatus;
 use App\Enumerations\InvoiceType;
 use App\Enumerations\RefundReason;
+use App\Enumerations\RetentionReason;
 use App\Enumerations\UserRole;
 use App\Mail\ParticipantRefundMails\RefundAcceptedMail;
 use App\Mail\ParticipantRefundMails\RefundReleasedMail;
@@ -206,17 +207,23 @@ class ParticipantRefundTest extends TestCase
         ], $attributes));
     }
 
+    /**
+     * Der Vorgabewert 300,00 € entspricht dem gezahlten Beitrag -- es bleibt also nichts einbehalten und
+     * es braucht keinen Einbehaltungsgrund. Bei kleineren Beträgen muss einer mitgegeben werden.
+     */
     private function release(
         EventParticipant $participant,
         float $amount = 300.0,
         string $reason = RefundReason::SICKNESS,
         ?string $note = null,
+        ?string $retentionReason = null,
     ) {
         return new ReleaseRefundCommand(new ReleaseRefundRequest(
             participant: $participant,
             amount: new Amount($amount, 'Euro'),
             reason: $reason,
             reasonNote: $note,
+            retentionReason: $retentionReason,
         ))->execute();
     }
 
@@ -296,10 +303,12 @@ class ParticipantRefundTest extends TestCase
     {
         $participant = $this->makeParticipant($this->makeEvent());
 
-        $response = $this->release($participant, 220.0);
+        $response = $this->release($participant, 220.0, retentionReason: RetentionReason::CANCELLATION_FEE);
 
         $this->assertTrue($response->success);
         $this->assertEqualsWithDelta(220.0, $response->refund->amount->getAmount(), 0.001);
+        // Der Rest wird am Vorgang festgeschrieben, nicht später gerechnet.
+        $this->assertEqualsWithDelta(80.0, $response->refund->retained_amount->getAmount(), 0.001);
     }
 
     public function test_release_is_rejected_without_an_amount(): void
@@ -626,6 +635,8 @@ class ParticipantRefundTest extends TestCase
         $response = $this->postJson('/api/v1/participant-refund/' . $participant->identifier . '/release', [
             'amount' => '220,50',
             'reason' => RefundReason::SICKNESS,
+            // Weniger als gezahlt -- der Rest bleibt beim Verband und braucht eine Begründung.
+            'retentionReason' => RetentionReason::CANCELLATION_FEE,
         ]);
 
         $response->assertOk()->assertJsonPath('status', 'success');
@@ -768,7 +779,13 @@ class ParticipantRefundTest extends TestCase
     public function test_the_release_mail_renders_with_the_link(): void
     {
         $participant = $this->makeParticipant($this->makeEvent());
-        $refund = $this->release($participant, 220.0, RefundReason::OTHER, 'Umzug')->refund;
+        $refund = $this->release(
+            $participant,
+            220.0,
+            RefundReason::OTHER,
+            'Umzug',
+            RetentionReason::CANCELLATION_FEE
+        )->refund;
 
         $html = new RefundReleasedMail($participant, $refund)->render();
 

tests/Feature/RefundDirectCaptureTest.php

@@ -10,6 +10,7 @@ use App\Enumerations\CostUnitType;
 use App\Enumerations\EfzStatus;
 use App\Enumerations\InvoiceStatus;
 use App\Enumerations\RefundReason;
+use App\Enumerations\RetentionReason;
 use App\Enumerations\UserRole;
 use App\Mail\ParticipantRefundMails\RefundAcceptedMail;
 use App\Mail\ParticipantRefundMails\RefundReleasedMail;
@@ -204,12 +205,18 @@ class RefundDirectCaptureTest extends TestCase
         ], $attributes));
     }
 
-    /** Freigabe mit bereits bekannter Bankverbindung. */
+    /**
+     * Freigabe mit bereits bekannter Bankverbindung.
+     *
+     * 220 von 300 gezahlten Euro: Es bleibt etwas beim Verband, deshalb gehört ein Einbehaltungsgrund
+     * dazu.
+     */
     private function releaseWithBankDetails(
         ?EventParticipant $participant = null,
         string $owner = 'Mika Muster',
         string $iban = 'DE02120300000000202051',
         float $amount = 220.0,
+        ?string $retentionReason = RetentionReason::CANCELLATION_FEE,
     ) {
         return new ReleaseRefundCommand(new ReleaseRefundRequest(
             participant: $participant ?? $this->makeParticipant(),
@@ -217,6 +224,7 @@ class RefundDirectCaptureTest extends TestCase
             reason: RefundReason::SICKNESS,
             accountOwner: $owner,
             accountIban: $iban,
+            retentionReason: $retentionReason,
         ))->execute();
     }
 
@@ -252,7 +260,7 @@ class RefundDirectCaptureTest extends TestCase
         $this->assertTrue($refund->wasCapturedByManagement());
     }
 
-    public function test_the_invoice_exists_and_the_paid_amount_is_cleared(): void
+    public function test_the_invoice_exists_and_the_paid_amount_is_settled(): void
     {
         $participant = $this->makeParticipant();
 
@@ -263,7 +271,19 @@ class RefundDirectCaptureTest extends TestCase
         $this->assertEqualsWithDelta(220.0, $invoice->amount, 0.001);
         $this->assertSame($invoice->id, ParticipantRefund::first()->invoice_id);
 
+        // 300 gezahlt, 220 erstattet -- die restlichen 80 bleiben beim Verband und werden dort geführt.
+        $this->assertEqualsWithDelta(80.0, $participant->fresh()->amount_paid->getAmount(), 0.001);
+    }
+
+    public function test_a_full_refund_leaves_nothing_behind(): void
+    {
+        $participant = $this->makeParticipant();
+
+        $this->releaseWithBankDetails($participant, amount: 300.0, retentionReason: null);
+
         $this->assertEqualsWithDelta(0.0, $participant->fresh()->amount_paid->getAmount(), 0.001);
+        $this->assertEqualsWithDelta(0.0, ParticipantRefund::first()->retained_amount->getAmount(), 0.001);
+        $this->assertNull(ParticipantRefund::first()->retention_reason);
     }
 
     public function test_only_the_receipt_mail_goes_out(): void
@@ -299,6 +319,7 @@ class RefundDirectCaptureTest extends TestCase
             participant: $this->makeParticipant(),
             amount: new Amount(220.0, 'Euro'),
             reason: RefundReason::SICKNESS,
+            retentionReason: RetentionReason::CANCELLATION_FEE,
         ))->execute()->refund;
 
         $refund->update([
@@ -379,6 +400,8 @@ class RefundDirectCaptureTest extends TestCase
         $this->postJson('/api/v1/participant-refund/' . $participant->identifier . '/release', [
             'amount' => '220,00',
             'reason' => RefundReason::SICKNESS,
+            // 220 von 300 -- der Rest bleibt beim Verband und braucht eine Begründung.
+            'retentionReason' => RetentionReason::CANCELLATION_FEE,
             'accountOwner' => 'Mika Muster',
             'accountIban' => 'DE02 1203 0000 0000 2020 51',
         ])
@@ -396,6 +419,8 @@ class RefundDirectCaptureTest extends TestCase
         $this->postJson('/api/v1/participant-refund/' . $participant->identifier . '/release', [
             'amount' => '220,00',
             'reason' => RefundReason::SICKNESS,
+            // 220 von 300 -- der Rest bleibt beim Verband und braucht eine Begründung.
+            'retentionReason' => RetentionReason::CANCELLATION_FEE,
             'accountOwner' => '',
             'accountIban' => '',
         ])

tests/Feature/RefundInvoiceTest.php

@@ -11,6 +11,7 @@ use App\Enumerations\EfzStatus;
 use App\Enumerations\InvoiceStatus;
 use App\Enumerations\InvoiceType;
 use App\Enumerations\RefundReason;
+use App\Enumerations\RetentionReason;
 use App\Enumerations\UserRole;
 use App\Mail\InvoiceMails\InvoiceMailsSubmittedConfirmationMail;
 use App\Models\CostUnit;
@@ -200,11 +201,16 @@ class RefundInvoiceTest extends TestCase
         ], $attributes));
     }
 
-    /** Der ganze Ablauf: Freigabe durch die Aktionsleitung, Bestätigung durch den Teili. */
+    /**
+     * Der ganze Ablauf: Freigabe durch die Aktionsleitung, Bestätigung durch den Teili.
+     *
+     * 220 von 300 gezahlten Euro -- es bleibt etwas beim Verband, deshalb der Einbehaltungsgrund.
+     */
     private function runRefund(
         ?EventParticipant $participant = null,
         float $amount = 220.0,
         string $reason = RefundReason::SICKNESS,
+        ?string $retentionReason = RetentionReason::CANCELLATION_FEE,
     ): ParticipantRefund {
         $participant ??= $this->makeParticipant($this->makeEvent());
 
@@ -212,6 +218,7 @@ class RefundInvoiceTest extends TestCase
             participant: $participant,
             amount: new Amount($amount, 'Euro'),
             reason: $reason,
+            retentionReason: $retentionReason,
         ))->execute()->refund;
 
         new AcceptRefundCommand(new AcceptRefundRequest(
@@ -359,6 +366,7 @@ class RefundInvoiceTest extends TestCase
             participant: $participant,
             amount: new Amount(220.0, 'Euro'),
             reason: RefundReason::SICKNESS,
+            retentionReason: RetentionReason::CANCELLATION_FEE,
         ))->execute()->refund;
 
         $response = new AcceptRefundCommand(new AcceptRefundRequest(
@@ -403,25 +411,26 @@ class RefundInvoiceTest extends TestCase
         Mail::assertSent(InvoiceMailsSubmittedConfirmationMail::class);
     }
 
-    public function test_amount_paid_is_cleared_once_the_invoice_exists(): void
+    public function test_amount_paid_is_settled_once_the_invoice_exists(): void
     {
         $participant = $this->makeParticipant($this->makeEvent());
         $this->runRefund($participant);
 
-        // Mit der eingereichten Abrechnung ist der Beitrag auf dem Weg zurück und darf in den
+        // 300 gezahlt, 220 erstattet: `amount_paid` führt danach den Rest, der beim Verband bleibt.
-        // Zahlungsübersichten nicht länger als eingegangen stehen.
+        $this->assertEqualsWithDelta(80.0, $participant->fresh()->amount_paid->getAmount(), 0.001);
-        $this->assertEqualsWithDelta(0.0, $participant->fresh()->amount_paid->getAmount(), 0.001);
+
+        // Der Sollbetrag bleibt: was der Teili hätte zahlen müssen, ändert die Erstattung nicht.
         $this->assertEqualsWithDelta(300.0, $participant->fresh()->amount->getAmount(), 0.001);
     }
 
-    public function test_the_receipt_is_written_before_the_amount_is_cleared(): void
+    public function test_the_receipt_is_written_before_the_amount_is_settled(): void
     {
         $refund = $this->runRefund();
 
-        // Reihenfolge-Falle: Beleg und Anmerkung weisen den gezahlten Beitrag aus. Wird zu früh genullt,
+        // Reihenfolge-Falle: Beleg und Anmerkung weisen den gezahlten Beitrag aus. Wird zu früh
-        // stünde dort 0,00 €. Der Beleg selbst liegt als PDF vor; nachprüfbar ist die Reihenfolge an der
+        // verrechnet, stünden dort 80,00 € statt 300,00 €. Der Beleg selbst liegt als PDF vor;
-        // Anmerkung, die im selben Schritt und aus derselben Quelle entsteht.
+        // nachprüfbar ist die Reihenfolge an der Anmerkung, die im selben Schritt entsteht.
         $this->assertStringContainsString('300,00 Euro', Invoice::first()->comment);
-        $this->assertEqualsWithDelta(0.0, $refund->participant->fresh()->amount_paid->getAmount(), 0.001);
+        $this->assertEqualsWithDelta(80.0, $refund->participant->fresh()->amount_paid->getAmount(), 0.001);
     }
 }

tests/Feature/RefundRetentionTest.php

@@ -0,0 +1,407 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Domains\ParticipantRefund\Actions\AcceptRefund\AcceptRefundCommand;
+use App\Domains\ParticipantRefund\Actions\AcceptRefund\AcceptRefundRequest;
+use App\Domains\ParticipantRefund\Actions\CreateRefundDocument\CreateRefundDocumentCommand;
+use App\Domains\ParticipantRefund\Actions\CreateRefundDocument\CreateRefundDocumentRequest;
+use App\Domains\ParticipantRefund\Actions\ReleaseRefund\ReleaseRefundCommand;
+use App\Domains\ParticipantRefund\Actions\ReleaseRefund\ReleaseRefundRequest;
+use App\Enumerations\CostUnitType;
+use App\Enumerations\EfzStatus;
+use App\Enumerations\InvoiceStatus;
+use App\Enumerations\RefundReason;
+use App\Enumerations\RetentionReason;
+use App\Enumerations\UserRole;
+use App\Mail\ParticipantRefundMails\RefundAcceptedMail;
+use App\Models\CostUnit;
+use App\Models\DocumentTemplate;
+use App\Models\Event;
+use App\Models\EventParticipant;
+use App\Models\ParticipantRefund;
+use App\Models\PaymentMethod;
+use App\Models\Tenant;
+use App\Models\User;
+use App\Providers\DocumentTemplateRenderProvider;
+use App\RelationModels\EventParticipationFee;
+use App\ValueObjects\Amount;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Mail;
+use Illuminate\Support\Facades\Storage;
+use ReflectionMethod;
+use Tests\TestCase;
+
+/**
+ * Der einbehaltene Teil einer Erstattung.
+ *
+ * Wird weniger erstattet als gezahlt wurde, bleibt Geld beim Verband. Das muss begründet sein und überall
+ * sichtbar bleiben -- und `amount_paid` muss es weiter führen, weil die Einnahmenrechnung darauf aufbaut.
+ */
+class RefundRetentionTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private Tenant $tenant;
+
+    private int $sequence = 0;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->tenant = Tenant::create([
+            'slug' => 'wm',
+            'name' => 'Wilde Möhre',
+            'address_1' => 'Musterweg 1',
+            'email' => 't@example.com',
+            'email_finance' => 'finance@example.com',
+            'url' => parse_url(config('app.url'), PHP_URL_HOST),
+            'account_name' => 'Test e.V.',
+            'account_iban' => 'DE00',
+            'account_bic' => 'XY',
+            'city' => 'Stadt',
+            'postcode' => '00000',
+            'invoice_prefix' => 'WM',
+            'is_active_local_group' => true,
+            'has_active_instance' => true,
+        ]);
+
+        app()->instance('tenant', $this->tenant);
+
+        DB::table('participation_types')->insert(['slug' => 'participant', 'name' => 'Teilnehmer']);
+        DB::table('participation_fee_types')->insert(['slug' => 'fixed', 'name' => 'Fix']);
+        DB::table('cost_unit_types')->insert(['slug' => CostUnitType::COST_UNIT_TYPE_EVENT, 'name' => 'Veranstaltung']);
+        DB::table('invoice_status')->insert(['slug' => InvoiceStatus::INVOICE_STATUS_NEW]);
+        PaymentMethod::create(['slug' => PaymentMethod::PAYMENT_ACCOUNT_TRANSACTION]);
+        EfzStatus::create(['slug' => EfzStatus::EFZ_STATUS_NOT_REQUIRED, 'name' => 'Nicht erforderlich']);
+
+        foreach ([UserRole::USER_ROLE_ADMIN, UserRole::USER_ROLE_GROUP_LEADER, UserRole::USER_ROLE_USER] as $role) {
+            UserRole::create(['slug' => $role, 'name' => $role]);
+        }
+
+        $this->seedTemplate();
+
+        Storage::fake('local');
+        Mail::fake();
+    }
+
+    /** Die Vorlage setzt den Datenblock ein -- daran lassen sich die Belegzeilen prüfen. */
+    private function seedTemplate(): void
+    {
+        DocumentTemplate::create([
+            'document_type' => DocumentTemplate::TYPE_PARTICIPANT_REFUND,
+            'block' => DocumentTemplate::BLOCK_LAYOUT,
+            'content' => '<div>{block:body}</div>',
+            'sort_order' => 10,
+        ]);
+
+        DocumentTemplate::create([
+            'document_type' => DocumentTemplate::TYPE_PARTICIPANT_REFUND,
+            'block' => DocumentTemplate::BLOCK_BODY,
+            'content' => '{details_table}<p>{retained_amount} / {retention_note}</p>',
+            'sort_order' => 20,
+        ]);
+    }
+
+    private function makeEvent(): Event
+    {
+        $fee = EventParticipationFee::create([
+            'tenant' => $this->tenant->slug,
+            'type' => 'participant',
+            'name' => 'Sippe',
+            'description' => null,
+            'amount_standard' => 60.0,
+            'amount_reduced' => null,
+            'amount_solidarity' => null,
+        ]);
+
+        $costUnit = CostUnit::create([
+            'tenant' => $this->tenant->slug,
+            'name' => 'Sommerlager',
+            'type' => CostUnitType::COST_UNIT_TYPE_EVENT,
+            'distance_allowance' => 0.25,
+            'mail_on_new' => false,
+            'allow_new' => true,
+            'archived' => false,
+        ]);
+
+        return Event::create([
+            'cost_unit_id' => $costUnit->id,
+            'tenant' => $this->tenant->slug,
+            'name' => 'Sommerlager',
+            'identifier' => 'evt-' . uniqid(),
+            'location' => 'Ort',
+            'postal_code' => '00000',
+            'email' => 'e@example.com',
+            'start_date' => '2026-07-16',
+            'end_date' => '2026-07-20',
+            'early_bird_end' => '2026-06-20',
+            'registration_final_end' => '2026-07-01',
+            'early_bird_end_amount_increase' => 0,
+            'account_owner' => 'Owner',
+            'account_iban' => 'DE00',
+            'participation_fee_type' => 'fixed',
+            'participation_fee_1' => $fee->id,
+            'pay_per_day' => true,
+            'pay_direct' => false,
+            'tax_liable' => false,
+            'vat_rate' => 0,
+            'vat_pricing_mode' => 'inclusive',
+            // Je Test können mehrere Veranstaltungen entstehen; der Schlüssel ist eindeutig.
+            'invoice_key' => 'WM-V-2026070' . ($this->sequence + 1),
+        ]);
+    }
+
+    private function makeParticipant(array $attributes = []): EventParticipant
+    {
+        $this->sequence++;
+
+        $user = User::create([
+            'username' => 'teili-' . uniqid() . '@example.com',
+            'email' => 'teili-' . uniqid() . '@example.com',
+            'firstname' => 'Mika',
+            'lastname' => 'Muster',
+            'password' => bcrypt('secret'),
+            'local_group' => $this->tenant->slug,
+            'user_role_main' => UserRole::USER_ROLE_USER,
+            'user_role_local_group' => UserRole::USER_ROLE_USER,
+            'active' => true,
+        ]);
+
+        return $this->makeEvent()->participants()->create(array_merge([
+            'tenant' => $this->tenant->slug,
+            'identifier' => 'p-' . uniqid(),
+            'invoice_sequence' => $this->sequence,
+            'user_id' => $user->id,
+            'firstname' => 'Mika',
+            'lastname' => 'Muster',
+            'participation_type' => 'participant',
+            'fee_type' => 'standard',
+            'sibling_reduction' => false,
+            'local_group' => $this->tenant->slug,
+            'birthday' => '2000-01-01',
+            'address_1' => 'Beispielstraße 3',
+            'postcode' => '11111',
+            'city' => 'Beispielstadt',
+            'email_1' => 'mika@example.com',
+            'phone_1' => '0170 0000000',
+            'arrival_date' => '2026-07-16',
+            'departure_date' => '2026-07-20',
+            'arrival_eating' => 1,
+            'departure_eating' => 1,
+            'amount' => 300.0,
+            'amount_paid' => 300.0,
+            'unregistered_at' => '2026-06-12',
+            'payment_purpose' => 'Sommerlager',
+            'payment_method' => PaymentMethod::PAYMENT_ACCOUNT_TRANSACTION,
+            'efz_status' => EfzStatus::EFZ_STATUS_NOT_REQUIRED,
+        ], $attributes));
+    }
+
+    private function release(
+        EventParticipant $participant,
+        float $amount,
+        ?string $retentionReason = null,
+        ?string $retentionNote = null,
+    ) {
+        return new ReleaseRefundCommand(new ReleaseRefundRequest(
+            participant: $participant,
+            amount: new Amount($amount, 'Euro'),
+            reason: RefundReason::SICKNESS,
+            retentionReason: $retentionReason,
+            retentionReasonNote: $retentionNote,
+        ))->execute();
+    }
+
+    private function accept(ParticipantRefund $refund): void
+    {
+        new AcceptRefundCommand(new AcceptRefundRequest(
+            refund: $refund,
+            accountOwner: 'Mika Muster',
+            accountIban: 'DE02120300000000202051',
+            declarationAccepted: true,
+        ))->execute();
+    }
+
+    /*
+    |--------------------------------------------------------------------------
+    | Der Grund ist Pflicht, sobald etwas bleibt
+    |--------------------------------------------------------------------------
+    */
+
+    public function test_a_partial_refund_without_a_reason_is_refused(): void
+    {
+        $response = $this->release($this->makeParticipant(), 220.0);
+
+        $this->assertFalse($response->success);
+        $this->assertStringContainsString('einbehalten', $response->message);
+        $this->assertSame(0, ParticipantRefund::count());
+    }
+
+    public function test_a_full_refund_needs_no_reason(): void
+    {
+        $response = $this->release($this->makeParticipant(), 300.0);
+
+        $this->assertTrue($response->success);
+        $this->assertNull($response->refund->retention_reason);
+        $this->assertEqualsWithDelta(0.0, $response->refund->retained_amount->getAmount(), 0.001);
+    }
+
+    public function test_a_free_text_retention_reason_needs_its_note(): void
+    {
+        $response = $this->release($this->makeParticipant(), 220.0, RetentionReason::CUSTOM, '   ');
+
+        $this->assertFalse($response->success);
+        $this->assertStringContainsString('Erläuterung', $response->message);
+        $this->assertSame(0, ParticipantRefund::count());
+    }
+
+    public function test_an_unknown_retention_reason_is_refused(): void
+    {
+        $response = $this->release($this->makeParticipant(), 220.0, 'erfunden');
+
+        $this->assertFalse($response->success);
+        $this->assertSame(0, ParticipantRefund::count());
+    }
+
+    public function test_a_reason_sent_with_a_full_refund_is_not_stored(): void
+    {
+        // Im Formular ist das Feld dann gar nicht sichtbar -- ein Wert ohne Bezug gehört nicht in die DB.
+        $response = $this->release($this->makeParticipant(), 300.0, RetentionReason::CANCELLATION_FEE);
+
+        $this->assertTrue($response->success);
+        $this->assertNull($response->refund->retention_reason);
+    }
+
+    public function test_the_note_is_only_stored_for_reasons_that_require_it(): void
+    {
+        $withNote = $this->release($this->makeParticipant(), 220.0, RetentionReason::CUSTOM, 'Bereits gebuchte Bahnfahrt');
+        $this->assertSame('Bereits gebuchte Bahnfahrt', $withNote->refund->retention_reason_note);
+
+        $ignored = $this->release($this->makeParticipant(), 220.0, RetentionReason::MATERIAL, 'wird verworfen');
+        $this->assertNull($ignored->refund->retention_reason_note);
+    }
+
+    /*
+    |--------------------------------------------------------------------------
+    | Was beim Verband bleibt
+    |--------------------------------------------------------------------------
+    */
+
+    public function test_the_retained_amount_is_recorded_at_release(): void
+    {
+        $response = $this->release($this->makeParticipant(), 220.0, RetentionReason::CANCELLATION_FEE);
+
+        // Festgeschrieben, nicht gerechnet: Nach dem Einreichen führt `amount_paid` bereits den Rest.
+        $this->assertEqualsWithDelta(80.0, $response->refund->retained_amount->getAmount(), 0.001);
+        $this->assertTrue($response->refund->hasRetention());
+    }
+
+    public function test_amount_paid_keeps_the_retained_share(): void
+    {
+        $participant = $this->makeParticipant();
+        $refund = $this->release($participant, 220.0, RetentionReason::CANCELLATION_FEE)->refund;
+
+        $this->accept($refund);
+
+        $this->assertEqualsWithDelta(80.0, $participant->fresh()->amount_paid->getAmount(), 0.001);
+    }
+
+    public function test_a_full_refund_leaves_nothing(): void
+    {
+        $participant = $this->makeParticipant();
+        $refund = $this->release($participant, 300.0)->refund;
+
+        $this->accept($refund);
+
+        $this->assertEqualsWithDelta(0.0, $participant->fresh()->amount_paid->getAmount(), 0.001);
+    }
+
+    public function test_a_second_refund_is_capped_at_the_remainder(): void
+    {
+        $participant = $this->makeParticipant();
+        $this->accept($this->release($participant, 220.0, RetentionReason::CANCELLATION_FEE)->refund);
+
+        // Es liegen noch 80 € beim Verband -- mehr kann nicht zurückgehen.
+        $tooMuch = $this->release($participant->fresh(), 100.0, RetentionReason::CANCELLATION_FEE);
+        $this->assertFalse($tooMuch->success);
+
+        $fits = $this->release($participant->fresh(), 80.0);
+        $this->assertTrue($fits->success);
+        $this->assertEqualsWithDelta(0.0, $fits->refund->retained_amount->getAmount(), 0.001);
+    }
+
+    /*
+    |--------------------------------------------------------------------------
+    | Sichtbarkeit
+    |--------------------------------------------------------------------------
+    */
+
+    public function test_the_receipt_names_the_retained_amount_and_reason(): void
+    {
+        $participant = $this->makeParticipant();
+        $refund = $this->release($participant, 220.0, RetentionReason::CANCELLATION_FEE)->refund;
+        $this->accept($refund);
+
+        $html = $this->renderReceipt($refund->fresh());
+
+        $this->assertStringContainsString('Einbehalten', $html);
+        $this->assertStringContainsString('80,00', $html);
+        $this->assertStringContainsString('Stornogebühr laut Ausschreibung', $html);
+    }
+
+    public function test_the_receipt_stays_silent_on_a_full_refund(): void
+    {
+        $participant = $this->makeParticipant();
+        $refund = $this->release($participant, 300.0)->refund;
+        $this->accept($refund);
+
+        $this->assertStringNotContainsString('Einbehalten', $this->renderReceipt($refund->fresh()));
+    }
+
+    public function test_the_mail_explains_the_retention(): void
+    {
+        $participant = $this->makeParticipant();
+        $refund = $this->release($participant, 220.0, RetentionReason::CUSTOM, 'Bereits gebuchte Bahnfahrt')->refund;
+        $this->accept($refund);
+
+        $html = new RefundAcceptedMail($participant, $refund->fresh())->render();
+
+        $this->assertStringContainsString('80,00 Euro', $html);
+        $this->assertStringContainsString('Sonstiger Grund', $html);
+        $this->assertStringContainsString('Bereits gebuchte Bahnfahrt', $html);
+    }
+
+    public function test_the_mail_stays_silent_on_a_full_refund(): void
+    {
+        $participant = $this->makeParticipant();
+        $refund = $this->release($participant, 300.0)->refund;
+        $this->accept($refund);
+
+        $this->assertStringNotContainsString('verbleiben beim Verband', new RefundAcceptedMail($participant, $refund->fresh())->render());
+    }
+
+    public function test_the_resource_carries_the_retention_for_the_lists(): void
+    {
+        $participant = $this->makeParticipant();
+        $refund = $this->release($participant, 220.0, RetentionReason::CANCELLATION_FEE)->refund;
+        $this->accept($refund);
+
+        $data = $refund->fresh()->toResource()->toArray(request());
+
+        $this->assertTrue($data['hasRetention']);
+        $this->assertSame('80,00 Euro', $data['retainedAmount']);
+        $this->assertSame('Stornogebühr laut Ausschreibung', $data['retentionReasonLabel']);
+    }
+
+    private function renderReceipt(ParticipantRefund $refund): string
+    {
+        $command = new CreateRefundDocumentCommand(new CreateRefundDocumentRequest($refund));
+        $number = new ReflectionMethod($command, 'documentNumber')->invoke($command);
+        $tokens = new ReflectionMethod($command, 'buildTokens')->invoke($command, $number);
+
+        return new DocumentTemplateRenderProvider(DocumentTemplate::TYPE_PARTICIPANT_REFUND)->render($tokens);
+    }
+}

version

@@ -1 +1 @@
-4.7.0
+4.8.0