teamwallet/docs/superpowers/specs/2026-08-03-cashbox-export-design.md

# Kassenbuch-Export (manuell + automatischer PDF-Versand)

Status: approved
Datum: 2026-08-03

## Kontext

TeamWallet bietet mit dem Kassenjournal (`teams/:id/transactions/journal`, Cashbox-Seite im
Frontend) bereits eine paginierte, filterbare Ansicht aller Buchungen. Es gibt aber keine
Möglichkeit, diese Daten für die Vereinsbuchhaltung oder eine Kassenprüfung zu exportieren — weder
manuell (CSV/PDF-Download) noch automatisiert (regelmäßiger Versand an Vorstand/Kassenprüfer). Beide
Fähigkeiten fehlen komplett (kein Export-Code, `mail`-Modul aktuell nur für Login/Passwort-Reset
genutzt).

Ziel: Ein Kassenwart/Captain/Coach kann (a) für einen frei wählbaren Zeitraum einen Kassenbuch-Export
als CSV und/oder PDF herunterladen, und (b) optional einen wiederkehrenden automatischen PDF-Versand
an beliebige E-Mail-Adressen einrichten (z.B. monatlich an den Vereinsvorstand).

Das Feature wurde im Brainstorming aus mehreren Optionen ausgewählt (Alternativen: Saldo-
Erinnerungen, server-seitige Journal-Filterung, Belege-Anhang, Vier-Augen-Prinzip — diese sind nicht
Teil dieses Plans). Ausdrücklich nicht Teil dieses oder eines zukünftigen Plans: Team
verlassen/löschen.

## Fachliche Einordnung

Ein "Kassenbuch" bildet nur **echte Kassenbewegungen** ab — Buchungen, die laut `setBalance()`
(`Transaction`- und `TeamWalletTransaction`-Entity) tatsächlich `team.balance` verändern:

- `Transaction` mit `type.id === 0` (`payment`) — Spieler zahlt echtes Geld ein.
- **Alle** `TeamWalletTransaction`-Einträge (`credit` und `expense`) — direkte Kassenbewegungen ohne
  Spielerbezug.

Spieler-Fälligkeiten (`fee`/`levy`/`fine`, `type.id > 10`) verändern nur die Spielerschuld, nie den
Kassenbestand, und werden **bewusst ausgeschlossen** (entspricht der gewählten Option "Nur
Kassenjournal (Team-Saldo)").

Der Export zeigt einen **Periodensaldo** (laufende Summe ab 0, beginnend am gewählten Startdatum),
keinen historischen Kontostand — eine Rekonstruktion des absoluten Kontostands zu einem beliebigen
Vergangenheitszeitpunkt wäre für den ersten Wurf YAGNI.

## Entscheidungen aus dem Brainstorming

- **Format**: CSV und PDF, beide.
- **Zeitraum (manueller Export)**: frei wählbares Von/Bis-Datum.
- **Inhalt**: nur Kassenjournal (Team-Saldo), keine Spieler-Fälligkeiten.
- **Berechtigung**: wie Buchungen anlegen (`transaction_create_min_role`) — sowohl für den manuellen
  Export als auch für die Konfiguration des automatischen Versands.
- **Automatischer Versand — Intervalle**: monatlich, quartalsweise, jährlich (identisch zu den
  wiederkehrenden Buchungen).
- **Automatischer Versand — Zeitraum**: immer der jeweils **abgelaufene volle Zeitraum** (z.B. bei
  monatlichem Versand am 1. des Monats immer genau der komplette Vormonat), nicht "seit letztem
  Versand" (das wäre bei verpassten Läufen mehrdeutig).
- **Automatischer Versand — Umfang**: **eine** Konfiguration pro Team (eine Empfängerliste, ein
  Intervall, pausierbar) statt mehrerer unabhängiger Abos.
- **Out of Scope**: Team verlassen/löschen (bereits an anderer Stelle ausgeschlossen).

## Architektur / Komponenten

### 1. Backend: neues Modul `cashbox-export/`

Struktur analog zu `recurring-transactions/` (eigenständiges Modul statt Erweiterung von
`teams.service.ts`, das bereits die Journal- und Statistik-Logik trägt).

**`cashbox-export.service.ts`**:
- `buildRows(team: Team, from: string, to: string): CashboxExportRow[]` — reine Funktion auf einer
  bereits geladenen `Team`-Entity (inkl. `players.transactions.type`, `transactions.type`). Filtert
  auf echte Kassenbewegungen (s.o.), grenzt auf `[from, to]` ein (Ende inklusiv, Tagesende), sortiert
  chronologisch aufsteigend, berechnet laufenden `runningTotal`. Wird sowohl vom HTTP-Pfad als auch
  vom Scheduler verwendet — keine Duplikation der Filterlogik.
- `getExportRowsForUser(teamId, userId, from, to)` — HTTP-Pfad: prüft `transaction_create_min_role`
  via `TeamAccessService.assertAtLeast`, lädt das Team, ruft `buildRows` auf.
- `buildCsv(team, rows, from, to): string` — Semikolon-getrennt, deutsches Komma als
  Dezimaltrennzeichen (Excel-DE-Standard), RFC4180-Escaping für Notizen mit Semikolon/Anführungszeichen/
  Zeilenumbruch. Spalten: Datum, Typ, Wer (Spielername oder "Teamkasse"), Notiz, Betrag, Periodensaldo.
  Bei leerem Zeitraum: nur Kopfzeile + Hinweiszeile "Keine Buchungen im gewählten Zeitraum".
- `buildPdf(team, rows, from, to): Buffer` — einfache Tabellen-PDF via neuer Abhängigkeit **`pdfkit`**
  (kein Chromium/Puppeteer nötig): Kopf mit Teamname + Zeitraum + Erstellungsdatum, Tabelle, Fußzeile
  mit Periodensaldo. Gleiche Leerzeitraum-Behandlung wie CSV.

**`cashbox-export.controller.ts`** (Pfad `cashbox-export`, `version: '1'`, nur `AuthGuard('jwt')`,
Berechtigung im Service):
- `GET cashbox-export/:teamId?from=&to=&format=csv|pdf` — liefert Datei über `@Res({passthrough:
  false})` mit manuell gesetzten Headern (`Content-Type`, `Content-Disposition: attachment;
  filename="kassenbuch_<teamAlias>_<from>_<to>.<ext>"`), kein globaler Response-Interceptor im
  Projekt vorhanden, der das stören würde.
- `GET cashbox-export/:teamId/subscription` — aktuelle Versand-Konfiguration (oder Default:
  `{ recipients: [], interval: 'monthly', active: false }`).
- `PUT cashbox-export/:teamId/subscription` — Upsert (Empfänger/Intervall/Aktiv-Status).

**Neue Entity `entities/cashbox-export-subscription.entity.ts`**: `id`, `team` (ManyToOne, in der
Praxis 1:1 durch Anwendungslogik im Service erzwungen — nur eine Subscription pro Team wird gepflegt/
aktualisiert statt neu angelegt), `recipients` (`simple-array`-Spalte, Liste von E-Mail-Strings),
`interval` (`RecurringTransactionIntervalEnum`, wiederverwendet aus dem `recurring-transactions`-
Modul — fachlich identisches Konzept), `active` (default `false`), `nextRunDate` (string, ISO-Datum),
`createdAt`.

**DTO `UpsertCashboxExportSubscriptionDto`**: `recipients: string[]` (`@IsEmail({}, {each:true})`),
`interval`, `active`. Validierung: `active === true` mit leerer `recipients`-Liste wird mit 400
abgelehnt (ergibt keinen Sinn, nichts zu versenden aber "aktiv").

**`cashbox-export.scheduler.ts`** (`@Cron`, zeitlich versetzt zum bestehenden
Recurring-Transactions-Job, z.B. `04:00 Uhr` statt `03:00 Uhr`, um DB-Last zu entzerren):
1. Lädt alle `active: true`-Subscriptions mit `nextRunDate <= heute` (inkl. `team`).
2. Pro fälliger Subscription: bestimmt den **abgelaufenen** Zeitraum passend zum `interval`
   ausgehend von `nextRunDate` (z.B. `nextRunDate = 2026-09-01`, `interval = monthly` → Zeitraum
   `2026-08-01`–`2026-08-31`), lädt das Team (inkl. Relationen), ruft `buildRows` + `buildPdf` auf
   (Wiederverwendung derselben Logik wie der manuelle Export), verschickt das PDF per
   `MailService`/`MailerService`-Attachment an alle `recipients` (neues Template
   `mail-templates/cashbox-export.hbs`, analog Aufbau zu `reset-password.hbs`), rückt `nextRunDate`
   um das Intervall vor (gleiche `setUTCMonth`-Arithmetik wie im Recurring-Transactions-Scheduler:
   `+1`/`+3`/`+12` Monate) und speichert.
3. Ein verpasster Tag (Server-Downtime) wird beim nächsten Lauf automatisch nachgeholt (rein
   datumsbasierter Check wie beim Recurring-Transactions-Scheduler).

**Registrierung**: `CashboxExportModule` in `src/app.module.ts` ergänzen (analog `PenaltyModule`/
`RecurringTransactionsModule`); `MailModule` importieren für den Versand.

**Logging-Events**: `cashbox_export_download`, `cashbox_export_subscription_update`,
`cashbox_export_subscription_run` in `logging-event.type.ts` ergänzen.

### 2. Frontend

**Cashbox-Toolbar**: neuer "Export"-Button (sichtbar nur mit `canDo(team(), 'transactionCreate')`,
kein neuer Permission-Key) öffnet einen Dialog mit Von/Bis-Datumsfeldern und Format-Auswahl
(CSV/PDF), löst über `CashboxExportApi.exportCashbox(teamId, from, to, format)`
(`responseType: 'blob'`) den Download aus. Ein kleiner `FileDownloadService.save(blob, filename)`
kapselt den Anchor-Click-Mechanismus, damit die Dialog-Komponente ohne echte DOM-Downloads getestet
werden kann (Service wird im Test gemockt).

Im selben Export-Bereich zusätzlich ein Zahnrad/Link "Automatischen Versand einrichten" → eigener
Dialog: Chip-Liste für E-Mail-Adressen (hinzufügen/entfernen, clientseitige Format-Validierung vor
dem Speichern), Intervall-Dropdown, Aktiv/Pausiert-Toggle, Speichern-Button. Neue Methoden
`CashboxExportApi.getSubscription(teamId)` / `updateSubscription(teamId, dto)`.

Neues Model `models/cashbox-export.model.ts` (`CashboxExportFormat`, `CashboxExportSubscription`,
`UpdateCashboxExportSubscription`).

## Fehlerbehandlung

- `from > to` → 400 (Backend), Submit-Button im Dialog zusätzlich clientseitig deaktiviert.
- Keine Buchungen im Zeitraum → Datei wird trotzdem erzeugt (Kopfzeile + Hinweistext), kein Fehler.
- Ungültige E-Mail-Adresse in der Empfängerliste → 400 (DTO-Validierung), Inline-Fehler im Dialog.
- `active: true` mit leerer Empfängerliste → 400.
- Fehlende Berechtigung → bestehender `assertAtLeast`-Wurf (403), keine neue Behandlung nötig.

## Testing

**Backend**:
- `cashbox-export.service.spec.ts` — Filterlogik (Ausschluss fee/levy/fine, Einschluss payment +
  alle TeamWallet-Typen), Datumsgrenzen (inklusive Tagesende), laufender Saldo, leerer Zeitraum,
  Berechtigungsdurchsetzung.
- `cashbox-export.http.spec.ts` — Auth erforderlich, korrekte Header/Content-Type je Format, CSV-
  Inhalt exakt geprüft (String-Vergleich), PDF nur auf `%PDF-`-Signatur + Non-Empty geprüft (kein
  Byte-Vergleich).
- `cashbox-export-subscription.service.spec.ts` — Upsert, Validierung (aktiv + leere Liste),
  Berechtigung.
- `cashbox-export.scheduler.spec.ts` — Perioden-Berechnung je Intervall (`it.each`), PDF+Mail-
  Dispatch mit gemocktem `MailerService` (Attachment vorhanden, korrekte Empfänger/Betreff),
  `nextRunDate`-Vorrücken, überspringt inaktive/nicht-fällige Subscriptions, Downtime-Nachholung.

**Frontend**:
- `cashbox-export-api.spec.ts` — korrekte HTTP-Calls (Query-Params, `responseType: 'blob'`,
  Subscription-GET/PUT).
- Export-Dialog-Spec — Formvalidierung (`from <= to`), Permission-Gating, ruft
  `FileDownloadService.save` mit korrekten Argumenten auf.
- Subscription-Dialog-Spec — Laden/Speichern, Chip-Validierung, Permission-Gating.

## Bewusst nicht enthalten (YAGNI)

- Kein historischer Anfangssaldo (nur Periodensaldo ab 0 innerhalb des Exportzeitraums).
- Kein Export der Spieler-Fälligkeiten (fee/levy/fine).
- Kein Excel-(.xlsx)-Format, nur CSV+PDF.
- Keine mehreren Versand-Konfigurationen pro Team.
- Kein CSV im automatischen Versand, nur PDF.
- Keine Empfänger-Verifizierung (Double-Opt-In) für frei eingetragene Adressen.

## Verifikation

- **Backend-Unit-Tests**: siehe oben, alle grün, `nest build` sauber.
- **Frontend-Unit-Tests**: siehe oben, alle grün, `tsc --noEmit` + `ng build` sauber.
- **Manuell**: Backend lokal starten, über die neue UI einen CSV- und einen PDF-Export für einen
  Zeitraum mit bekannten Testbuchungen herunterladen und Inhalt/Saldo stichprobenartig prüfen; eine
  Subscription mit `nextRunDate` = heute anlegen, Scheduler-Methode einmalig manuell aufrufen, prüfen
  dass eine E-Mail mit PDF-Anhang an alle konfigurierten Adressen geht und `nextRunDate` korrekt
  vorrückt.