diff --git a/docs/superpowers/specs/2026-08-03-cashbox-export-design.md b/docs/superpowers/specs/2026-08-03-cashbox-export-design.md new file mode 100644 index 0000000..0b70c9b --- /dev/null +++ b/docs/superpowers/specs/2026-08-03-cashbox-export-design.md @@ -0,0 +1,185 @@ +# 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___."`), 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.