M3 Tenant-Aufloesung per App-Session ergaenzen

- Mandantenauswahl fuer Benutzer mit mehreren Tenants bauen
- feste Tenant-Domains ohne Wildcard-Abhaengigkeit vorbereiten
- Login, Backfill, Smoke-Checks und M3-Dokumentation aktualisieren

docs/m3-saas-basis-vorbereitung.md

@@ -32,6 +32,7 @@ Umgesetzte Migrationen:
 database/migrations/0002_saas_identity_tenants.sql
 database/migrations/0003_saas_auth_account_fields.sql
 database/migrations/0004_saas_auth_tokens.sql
+database/migrations/0005_saas_tenant_resolution.sql
 ```
 
 Tabellen:
@@ -41,6 +42,7 @@ Tabellen:
 - `users`
 - `tenant_memberships`
 - `participants`
+- `tenant_domains`
 
 Ergaenzende Skripte:
 
@@ -50,6 +52,7 @@ scripts/check-m3-saas-basis.php
 scripts/check-m3-auth-flow.php
 scripts/check-m3-settings-flow.php
 scripts/check-m3-password-email-flow.php
+scripts/check-m3-tenant-resolution-flow.php
 ```
 
 Wichtige Regeln:
@@ -97,9 +100,12 @@ Vorgang:
    erzeugen.
 5. `admin = 1` als Rolle `admin` abbilden; ein konfigurierter erster Benutzer
    kann Rolle `owner` erhalten.
+6. Verwaiste `participants` mit nicht mehr vorhandener `legacy_mitarbeiter_id`
+   aus dem Default-Tenant entfernen.
 
 Der Backfill muss idempotent sein und darf keine bestehenden Legacy-Daten
-loeschen.
+loeschen. Geloescht werden nur SaaS-Spiegelungen, deren Legacy-Mitarbeiter in
+`kl_Mitarbeiter` nicht mehr existiert.
 
 Ausgefuehrter Dev-Stand:
 
@@ -120,6 +126,7 @@ login.php
 register.php
 konto.php
 logout.php
+mandant-auswahl.php
 passwort-vergessen.php
 passwort-zuruecksetzen.php
 email-verifikation-senden.php
@@ -131,6 +138,10 @@ Umgesetzter Umfang:
 - Registrierung legt Tenant, Owner-User, Default-Settings, Membership und
   Owner-Participant in einer Transaktion an.
 - Login prueft `users.password_hash`, aktive Membership und aktiven Tenant.
+- Hat ein User genau einen aktiven Mandanten, wird dieser direkt in die Session
+  gelegt.
+- Hat ein User mehrere aktive Mandanten, fuehrt der Login zur
+  Mandantenauswahl.
 - Logout beendet die neue PHP-Login-Session.
 - `konto.php` zeigt den aktuellen SaaS-Kontext fuer den angemeldeten User.
 - `functions.php` akzeptiert eine SaaS-Login-Session als erste Identitaetsquelle,
@@ -145,10 +156,28 @@ Umgesetzter Umfang:
 
 Noch offen im M3-Auth-Scope:
 
-- Tenant-Aufloesung ueber Subdomain oder Custom Domain.
 - Weitergehende Rollenmatrix fuer spaetere SaaS-Seiten.
 - Produktiver Mailversand fuer Reset- und Verifikationslinks.
 
+## Tenant-Aufloesung
+
+Entscheidung fuer den Webspace-Betrieb:
+
+- Keine Wildcard-Subdomains im ersten Schritt.
+- Primaere App-Adresse ist eine zentrale App-Domain wie `app.kaffeeliste.de`.
+- Der aktive Mandant wird nach Login ueber `tenant_memberships` und die PHP-
+  Session gesetzt.
+- Bei genau einem Mandanten wird automatisch weitergeleitet.
+- Bei mehreren Mandanten nutzt der User `mandant-auswahl.php`.
+- `tenant_domains` ist vorbereitet fuer spaeter gezielt eingerichtete feste
+  Domains oder Subdomains, aber nicht Voraussetzung fuer den Start.
+
+Noch offen:
+
+- `APP_PRIMARY_HOST` in der Zielumgebung setzen.
+- Produktive Domain-/Zertifikatspruefung fuer einzelne feste Domains
+  definieren.
+
 ## Rollen und Grundeinstellungen
 
 Umgesetzte Dateien:
@@ -183,6 +212,7 @@ Umgesetzter Umfang:
 - Owner-/Admin-Grundeinstellungen koennen aktualisiert werden: erfuellt.
 - Passwort-Reset und E-Mail-Verifikation funktionieren mit Single-Use-Tokens:
   erfuellt.
+- Mandantenauswahl funktioniert fuer User mit mehreren Mandanten: erfuellt.
 - Golden-Master und HTTP-Smoke bleiben gruen: erfuellt.
 
 ## Risiken
@@ -209,6 +239,9 @@ Umgesetzter Umfang:
 10. Migration `0004_saas_auth_tokens.sql` erstellen: erledigt.
 11. Passwort-Reset und E-Mail-Verifikation bauen: erledigt.
 12. Password-/E-Mail-Flow-Kontrollskript schreiben: erledigt.
-13. Golden-Master und HTTP-Smoke ausfuehren: erledigt.
-14. Tenant-Aufloesung planen:
+13. Migration `0005_saas_tenant_resolution.sql` erstellen: erledigt.
+14. Mandantenauswahl und zentrale Session-Aufloesung bauen: erledigt.
+15. Tenant-Resolution-Kontrollskript schreiben: erledigt.
+16. Golden-Master und HTTP-Smoke ausfuehren: erledigt.
+17. Produktiven Mailversand oder Landingpage vorbereiten:
    naechster Schritt.