kaffeekasse-saas/docs/m6-import-export-mail.md

M6 Import, Export und Mail

Stand: 2026-07-15

M6 macht die Admin-/Treasurer-Flows produktionsreif: CSV-Import, PDF-/Listenexport, Mailversand und Jahresprozesse laufen tenant-sicher gegen das neue Modell statt gegen Legacy-Tabellen direkt.

CSV-Import

Umgesetzte Dateien:

database/migrations/0008_saas_payment_imports.sql
app/imports.php
csvupload.php

Ziel: Zahlungsimport mit echter Vorschau, Dublettenprüfung und Audit-Trail, statt sofortiger Verarbeitung ohne Bestätigungsschritt wie im Legacy-Stand.

Umfang:

• Neue Tabellen payment_import_batches und payment_import_rows (siehe Kernschema im Umstrukturierungsplan) protokollieren jeden Import: Datei, Prüfsumme, Zeitpunkt, jede einzelne Zeile mit Rohwerten, erkanntem Mitglied, Status und – nach Bestätigung – der erzeugten Ledger-Zeile.
• Zweistufiger Ablauf: Hochladen erzeugt eine Vorschau (status = previewed) ohne jede Buchung; erst der zweite Schritt „Import bestätigen“ committet die als matched erkannten Zeilen (status = committed).
• Zeilen werden klassifiziert: matched (wird gebucht), duplicate (gleicher Teilnehmer, gleicher Betrag, gleicher Tag existiert bereits als nicht-stornierte Ledger-Zahlung), unmatched (kein Mitglied per paypal_name oder display_name gefunden), invalid (Betrag oder Datum nicht parsebar).
• Zuordnungsregel entspricht der Legacy-Logik: Name aus der CSV wird gegen paypal_name oder display_name verglichen (case-insensitiv).
• Buchung folgt demselben Zweig-Muster wie die übrige Sammelerfassung: Für Teilnehmer mit legacy_mitarbeiter_id (Default-Mandant) wird zusätzlich eine kl_Einzahlungen-Zeile geschrieben und gespiegelt; alle anderen Mandanten werden direkt über ledger_record_payment() gebucht.
• Zugriffskontrolle ergänzt: Die Seite hatte zuvor gar keine Prüfung außer CSRF. Jetzt gilt dieselbe Rollen-/Legacy-Fallback-Logik wie bei einzahlung.php (owner, admin, treasurer).
• Upload-Härtung aus M2 (Größen-/Typprüfung, Speicherung außerhalb des direkt erreichbaren Codes unter var/uploads, Löschung nach Verarbeitung) bleibt erhalten.

Live gegen die Dev-Datenbank getestet: Upload mit drei Testzeilen (Treffer, unbekannter Name, ungültiger Betrag), Vorschau-Klassifizierung geprüft, Import bestätigt (Dual-Write und Ledger-Spiegelung korrekt), erneuter Upload derselben Datei erkennt die bereits importierte Zeile korrekt als Dublette. Testdaten anschließend entfernt.

PDF-/Listenexport

Umgesetzte Dateien:

TCPDF/include/ (neu vendort)
TCPDF/fonts/ (nur die 14 PDF-Standard-Fonts, neu vendort)
exportKaffeeliste.php
scripts/http-smoke.php

Ziel: Der bestehende zweiseitige Kaffeeliste-Ausdruck (Vieltrinker-/ Wenigtrinker-Seite mit Wasserzeichen) bleibt optisch erhalten, liest aber tenant-sicher aus dem Ledger statt aus Legacy-Tabellen.

Umfang:

• TCPDF war im Repo nur teilweise vorhanden (include/-Verzeichnis und Font-Definitionen fehlten komplett, siehe M0/M1). Nachvendort wurden nur include/ und die 14 PDF-Standard-Fonts (Helvetica, Courier, Times, Symbol, ZapfDingbats – die einzigen tatsächlich genutzten) aus dem offiziellen TCPDF-6.6.2-Release, nicht die vollen ~25 MB an Unicode-Fonts, die für diesen Export nicht gebraucht werden.
• exportKaffeeliste.php hatte zuvor überhaupt keine Zugriffskontrolle (nicht einmal einen checkKaffeelisteAdmin-Aufruf) und band config.php direkt statt der gemeinsamen Bootstrap-Kette ein. Jetzt gilt dieselbe Rollen-/Legacy-Fallback-Logik wie bei den anderen Treasurer-Seiten. Zusätzlich nutzt die Seite bewusst keine Ledger-native Fensterprüfung mit dem alten Legacy-Anker (jüngstes Datum in kl_Kaffeeverbrauch) mehr, sondern durchgängig ledger_fetch_participants_by_window_marks() mit tenant_settings.sheet_window_days – für alle Mandanten einheitlich, da es sich um einen reinen Lesereport ohne Schreibpfad handelt (siehe Cutover-Notiz: keine Notwendigkeit, hier Legacy-Verhalten 1:1 zu bewahren).
• Guthaben kommt direkt aus der vorab geladenen Teilnehmerzusammenfassung (balance_cents) statt aus zwei separaten Datenbankabfragen pro Zeile (N+1-Muster im Original).
• Preis pro Strich kommt aus tenant_settings.mark_price_cents statt aus kl_config.
• scripts/http-smoke.php prüft den PDF-Export jetzt als regulären Check (gültige PDF-Antwort) statt als bekannten offenen Punkt.

Live getestet: gültiges zweiseitiges PDF (58 KB) mit korrektem Content-Type: application/pdf, Namen und Salden im PDF-Textstream stichprobenartig verifiziert (unkomprimierte Testausgabe), Vieltrinker-/ Wenigtrinker-Aufteilung stimmt mit den Ledger-Daten überein.

Prüfstatus

• Golden Master: grün mit 104 Assertions.
• M4 Ledger-Migration: grün mit 73 Assertions.
• M4 Ledger-Service: grün mit 115 Assertions.
• HTTP-Smoke: grün mit 24 geprüften Seiten (PDF-Export jetzt regulär statt bekannter offener Punkt).