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:

```text
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:

```text
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).