# M3 SaaS-Basis Vorbereitung

Stand: 2026-07-12

M3 fuehrt Mandanten, Benutzer, Mitgliedschaften und Grundeinstellungen additiv
ein. Die bestehende Legacy-App bleibt dabei lauffaehig und wird noch nicht auf
das neue Modell umgestellt.

## Ziel

- Einen Default-Tenant fuer den aktuellen Bestand erzeugen.
- Login-Benutzer und Kaffee-Teilnehmer fachlich trennen.
- Rollen tenant-spezifisch vorbereiten.
- Bestehende `kl_Mitarbeiter` ohne Datenverlust in `participants` spiegeln.
- Die Grundlage fuer Registrierung und Login schaffen, ohne die Legacy-Auth
  sofort zu ersetzen.

## Nicht-Ziele fuer den ersten M3-Schritt

- Kein kompletter Login-Umbau in einem Schritt.
- Keine Migration von Einzahlungen und Kaffeeverbrauch nach `ledger_entries`;
  das gehoert zu M4.
- Kein Design- oder Layout-Umbau.
- Kein Billing, keine Tarife, keine E-Mail-Verifikation im ersten Schritt.
- Kein produktiver Tenant-Wechsel in bestehenden Legacy-Seiten.

## Umgesetzter erster Schritt

Umgesetzte Migration:

```text
database/migrations/0002_saas_identity_tenants.sql
```

Tabellen:

- `tenants`
- `tenant_settings`
- `users`
- `tenant_memberships`
- `participants`

Ergaenzende Skripte:

```text
scripts/backfill-default-tenant.php
scripts/check-m3-saas-basis.php
```

Wichtige Regeln:

- `users` sind Login-Konten.
- `participants` sind Kaffeelisten-Teilnehmer.
- Ein `participant` kann optional auf einen `user` zeigen.
- Rollen liegen in `tenant_memberships`, nicht in `participants`.
- `participants.legacy_mitarbeiter_id` speichert die alte ID aus
  `kl_Mitarbeiter`.
- Geldwerte in neuen Settings als Cent-Integer speichern.
- Die Migration ist rein additiv; bestehende Legacy-Seiten fragen weiter die
  bisherigen `kl_*`-Tabellen ab.

## Default-Tenant

Fuer den Bestand wird ein erster Tenant angelegt:

```text
slug: default
name: Kaffeeliste Bestand
status: active
timezone: Europe/Berlin
locale: de-DE
currency_code: EUR
```

Die Werte koennen spaeter in einer Tenant-Einstellungsseite angepasst werden.

## Backfill

Ein separates Skript spiegelt die bestehenden Mitarbeiter:

```text
scripts/backfill-default-tenant.php
```

Vorgang:

1. Default-Tenant anlegen oder laden.
2. `tenant_settings` aus `kl_config` erzeugen.
3. Fuer jede Zeile aus `kl_Mitarbeiter` einen `participant` anlegen oder
   aktualisieren.
4. Fuer aktive Admins optional einen `user` und eine `tenant_membership`
   erzeugen.
5. `admin = 1` als Rolle `admin` abbilden; ein konfigurierter erster Benutzer
   kann Rolle `owner` erhalten.

Der Backfill muss idempotent sein und darf keine bestehenden Legacy-Daten
loeschen.

Ausgefuehrter Dev-Stand:

- Default-Tenant `default` wurde angelegt.
- 9 Legacy-Mitarbeiter wurden als `participants` gespiegelt.
- 2 aktive Admin-/Owner-Logins wurden als `users` und
  `tenant_memberships` angelegt.
- Ein zweiter Backfill-Lauf blieb idempotent.

## Erste Akzeptanzkriterien

- Migrationen laufen mehrfach ohne Fehler: erfuellt.
- Default-Tenant existiert genau einmal: erfuellt.
- `tenant_settings` enthalten Preis pro Strich und bestehende PayPal-Optionen:
  erfuellt.
- Jeder bestehende `kl_Mitarbeiter` hat genau einen `participant`: erfuellt.
- `participants.legacy_mitarbeiter_id` ist gesetzt: erfuellt.
- Admins werden als tenant-scoped Rolle abgebildet: erfuellt.
- Golden-Master und HTTP-Smoke bleiben gruen: erfuellt.

## Risiken

| Risiko | Gegenmassnahme |
| --- | --- |
| Login-User und Kaffee-Teilnehmer werden vermischt | `users` und `participants` strikt getrennt halten |
| Mehrfacher Backfill erzeugt Duplikate | Eindeutige Constraints und Upsert-Logik |
| Legacy-App bricht durch neue Tabellen | M3 nur additiv, keine Legacy-Queries umstellen |
| Rollen werden global statt tenant-scoped | Rollen ausschliesslich in `tenant_memberships` speichern |
| Falsche Owner-Zuordnung | Owner per Env-Konfiguration oder manuell dokumentierter Entscheidung setzen |

## Empfohlene Reihenfolge

1. Migration `0002_saas_identity_tenants.sql` erstellen: erledigt.
2. `scripts/backfill-default-tenant.php` erstellen: erledigt.
3. Backfill gegen die Dev-Datenbank ausfuehren: erledigt.
4. Kontrollskript fuer Tenant/Participant/Role-Counts schreiben: erledigt.
5. Golden-Master und HTTP-Smoke ausfuehren: erledigt.
6. Danach Login-/Registrierungsrouten planen: naechster Schritt.