tessera-ctl/docs/mandantentrennung-etappe3-auftrag.md

# Mandantentrennung — Etappe 3: Auftrag fuer die naechste Sitzung

Geschrieben am 2026-09-11 am Ende der Sitzung, die Etappe 2 abgeschlossen hat.
Zweck: Eine frische Sitzung soll Etappe 3 ohne Rueckfrage und ohne Neuermittlung
der Grundlagen beginnen koennen. Alles hier ist gemessen, nicht erinnert.

## Randbedingungen vom User (2026-09-11)

- **Dienstag, 2026-09-15, geht die erste voll funktionsfaehige Version live.**
  Live-Gehen braucht den Schalter NICHT — heute laeuft alpha mit dem
  BYPASSRLS-Stand und einem Mandanten, und das ist fuer den Betrieb
  unerheblich. Etappe 3 darf das Live-Gehen nicht blockieren.
- **Nicht nachfragen.** Alles machen, was ohne den User geht. Was nicht ohne
  ihn geht, am Ende benennen.
- **Beim Scharfschalten (Etappe 4) anhalten und fragen.** Das ist die einzige
  Ausnahme, und sie steht seit dem 2026-09-09.
- **Nach jedem abgeschlossenen Durchlauf pushen** (`git push` genuegt, die
  Push-URL zeigt auf localhost:3002).

## Stand beim Einstieg

- Etappe 2 abgeschlossen, alle zwoelf Bereiche gebunden, jeder einzeln
  verifiziert. Endstand 994 Tests / 62 Dateien, 137 Live-Pruefungen,
  Klassifikation 65 Paare / 68 ungebunden / 178 gebunden.
- WINDOWS #27 (Relations-Blindstelle der Bestandsaufnahme) ist als Quick-Task
  `260911-mkj` in Arbeit oder abgeschlossen — `git log` und
  `.planning/quick/260911-mkj-*/` pruefen. Nach dessen Abschluss: 72 Paare.
- Der Schalter ist AUS. `DATABASE_URL` zeigt auf Rolle `tessera`.

## Die zwei Produktentscheidungen (User, 2026-09-10)

1. **Anmeldenamen pro Mandant eindeutig**, nicht plattformweit. `m.schmidt`
   darf es bei Firma A und Firma B geben.
2. **Kollegen derselben Firma strikt getrennt.** Jeder sieht nur seine eigenen
   gespeicherten Suchen, Favoriten, Dashboard-Anordnung.

## Etappe 3 in drei Teilen — empfohlene Reihenfolge

### 3b zuerst: Benutzerdimension in den Regeln

**Erledigt (260911-nke, f0b531b/07fc653 plus der Dokumentationscommit dieser
Aufgabe):** Migration
`20260911120000_rls_user_dimension_personal_tables` bringt `current_user_id()`
und die Benutzerdimension in die Regeln der zehn persoenlichen Tabellen;
`forTenant(prisma, tenantId, userId?)` bekommt den optionalen dritten
Parameter, 34 Nutzer-CRUD-Aufrufstellen in acht Diensten reichen ihn durch.
Gemessene Zahl der umgedrehten Loch-Pruefungen: SECHS, nicht drei wie unten
noch angenommen. Endzahlen: Tests 1020/62 Dateien, Werkzeug
`rls-scratch-check.mjs` 203/203 bestanden (Baseline vor diesem Lauf: 137).
Siehe `docs/mandantentrennung-etappe2-fehlerrichtung.md`, Abschnitt
"Regelschluss Benutzerdimension (Etappe 3b, 260911-nke)". Der ursprüngliche
Auftragstext unten bleibt unveraendert stehen (historische Planungsgrundlage).

Warum zuerst: reiner Datenbank- und Helfer-Umbau, beruehrt den Anmeldeweg
NICHT, und schliesst die Klasse von Befunden, die in sieben Bereichen als
"Policy hat keine Benutzerdimension" festgehalten wurde.

Gemessene Grundlagen:
- `forTenant(prisma, tenantId)` in `apps/api/src/prisma/prisma-tenant.extension.ts:111`
  setzt genau EINE Sitzungsvariable: `set_config('app.current_tenant', ..., true)`.
  `current_tenant_id()` ist in `20260618112133_rls_policies` definiert.
- Es gibt KEIN `app.current_user` und KEIN `current_user_id()` — nirgends in
  Migrationen oder Quelltext.
- **14 Modelle tragen eine `userId`-Spalte:** CalendarSource, DashboardLayout,
  FavoriteLink, GroupMembership, ModuleGrant, PasswordResetToken, SearchProvider,
  TenderEmailConfig, TenderMatch, TenderNotificationPref, TenderRssFeedSource,
  TenderSavedSearch, TenderTriage, WidgetInstance. NICHT alle davon sind
  "persoenliche Daten": GroupMembership und ModuleGrant sind
  Verwaltungsobjekte (ein Admin darf sie fuer andere sehen),
  PasswordResetToken ist ein Anmelde-Artefakt, TenderMatch wird vom
  Hintergrunddienst je Treffer geschrieben. Die Benutzerdimension gehoert
  auf die ZEHN echten Nutzerobjekte; welche das sind, ist je Modell zu
  entscheiden und am Ort zu begruenden — Vorgabe aus den Bereichs-Kritiken:
  CalendarSource, DashboardLayout, FavoriteLink, SearchProvider (persoenliche
  Zeilen), TenderEmailConfig, TenderNotificationPref, TenderRssFeedSource
  (persoenliche Zeilen), TenderSavedSearch, TenderTriage, WidgetInstance.
- Der Anwendungscode trennt heute bereits korrekt nach Benutzer (in jedem
  Bereich stichprobenartig belegt, Besitzpruefungen in ldap/dkv/dashboard/
  calendar/favorites/auth als Tests festgenagelt). Die Datenbank tut es
  nicht. Das zweite Netz fehlt.

Bauform, an der es sich zu orientieren gilt:
- Zweite Sitzungsvariable `app.current_user`, Funktion `current_user_id()`
  nach dem Muster von `current_tenant_id()`.
- `forTenant()` bekommt einen optionalen dritten Parameter `userId` (oder
  ein Schwesterhelfer `forTenantAndUser()` — Entscheidung im Plan, mit
  Begruendung; Praezedenz fuer "Helfer erweitern statt zweiten bauen" ist
  `withTenantTransaction()`). Hintergrunddienste und Verwaltungswege rufen
  weiter ohne userId; nur die Nutzer-CRUD-Wege setzen ihn.
- Regeln der zehn Tabellen: Lesen `tenantId = current_tenant_id() AND
  (current_user_id() IS NULL OR userId = current_user_id())` — damit ein
  Aufruf OHNE gesetzten Benutzer (Admin, Hintergrunddienst) weiter alles
  des Mandanten sieht. Schreiben analog. Das IS-NULL-Muster ist die Form aus
  der #19-Loesung (260910-jab), dort fuer plattformweite Zeilen.
- Messen, nicht annehmen: `rls-scratch-check.mjs` bekommt einen Abschnitt
  je umgestellter Tabelle, ueber den GENERIERTEN Client, mit
  schemagleicher Wegwerf-Tabelle (Spaltenvergleich zur Laufzeit —
  `createdAt`/`updatedAt`-Falle aus 260910-krx).
- Die drei loch-behauptenden Pruefungen aus `tenders` und `dashboard`
  ("Policies haben keine Benutzerdimension", z. B.
  `tendersavedsearch-fremder-nutzer-desselben-mandanten-sichtbar`)
  UMDREHEN, nicht loeschen — Muster aus 260910-jab.

### 3a danach: Anmeldenamen pro Mandant

Warum danach: aendert das Schema UND den Anmeldeweg, ist der riskanteste
Teil, und braucht 3b nicht.

Gemessene Grundlagen:
- `User.username String @unique` und `User.email String? @unique`
  (`schema.prisma:31-32`) — plattformweit.
- Die drei SECURITY-DEFINER-Funktionen in
  `20260909160000_auth_lookup_functions`: `auth_lookup_user_by_username(p_username)`,
  `auth_lookup_user_by_email(p_email)`, `auth_lookup_reset_token(p_token)`.
  Jede sucht ueber EINE Gleichheitsbedingung mit `LIMIT 1`. Der Mandant
  kommt erst AUS der gefundenen Zeile.
- Aufrufer: `auth.service.ts:95,110,218` und `user.service.ts:33`.
- Bewusst ungebundene Stellen, die genau an dieser plattformweiten
  Eindeutigkeit haengen und mit 3a fallen: `ldap.service.ts`
  `resolveEmailForWrite` (260909-ipc, Befund A), die P2002-Kollisionskette in
  `tenders`/`user` (unsichtbare Zeile -> falsches "frei" -> harter Fehler),
  `user.service.ts` `findByUsername` (null Aufrufer, 260910-das).

Bauform:
- Schema: `@@unique([tenantId, username])`, `@@unique([tenantId, email])`
  statt `@unique`. Migration mit Datenpruefung davor (heute ein Mandant,
  also keine Kollision moeglich — trotzdem messen).
- Der Anmeldeweg muss den Mandanten kennen, BEVOR er die Zeile sucht.
  Zwei uebliche Wege: (i) eigene Adresse je Mandant (Subdomain
  `firma-a.tessera.ctl.de` -> Mandant aus dem Host), (ii) Mandantenwahl
  beim Login. **Das ist eine Produktfrage, die der User NICHT beantwortet
  hat.** Empfehlung fuer die Planung: (i), weil Tessera hinter Nginx Proxy
  Manager laeuft und Subdomains dort trivial sind, und weil (ii) den
  Anmeldenamen als Geheimnis schwaecht. Wenn die Planung das anders sieht,
  ist es einer der Punkte, die am Ende dem User genannt werden.
- Die drei Funktionen bekommen eine zweite Gleichheitsbedingung
  (`p_tenant_id`) — ENGER, nicht weiter. Die Kopfkommentare in
  `docs/mandantentrennung-datenbankrolle.md` nachziehen.
- Bis der Mandant vor der Suche bekannt ist, laesst sich 3a NICHT
  scharfschalten. Deshalb ist 3a fuer Dienstag NICHT noetig: mit einem
  Mandanten ist plattformweit = pro Mandant.

### 3c zuletzt: Systemkontext fuer die Hintergrunddienste

**Erledigt (260914-eym, 3d64567/6e2a641 plus der Dokumentationscommit dieser
Aufgabe):** Migration `20260914120000_rls_system_context_read` bringt
`is_system_context()` (COALESCE, STABLE) und je eine zusaetzliche, NUR
lesende Regel `system_read_policy ... FOR SELECT` auf FUENF Tabellen —
DkvModuleConfig, LdapConfig, LdapFieldMapping, TenderMatch, TenderSavedSearch
(nicht sechs: SmtpConfig traegt keine, weil der Mail-Startpfad ENTFERNT und
nicht umgestellt wurde). Helfer `forSystem(prisma)` als Schwesterhelfer von
`forTenant()` (setzt `app.system_context = 'true'` und die beiden anderen
Variablen ausdruecklich leer; `forTenant()`/`withTenantTransaction()` setzen
umgekehrt `app.system_context = ''`). Die sechs Faelle: DKV-Planer je
Mandant (Auftrag `dkv-inbox-poll:<tenantId>`, WINDOWS #21 geschlossen);
Mail-Transport je Versand nach Mandant des Empfaengers, Startpfad und
Mailer-Fabrik geloescht (WINDOWS #30 geschlossen); ldap mit ZWEI
Systemkontext-Lesern (`getAllActiveConfigs`, Nachverschluesselung — die
Schreibzeile je Altzeile gebunden); digest und matching ueber den
Systemkontext, Schleifen gebunden; admin-seed nur dokumentiert (liest
ausserhalb der Schleife nur `Tenant`, keine Regel, Datei unveraendert).
Detektor mit fuenfter Erkennungsform und Erlaubnisliste (4 Dateien, 5
Aufrufe, exakt). Endzahlen: Tests 1054/64 Dateien, Typpruefung sauber,
Werkzeug `rls-scratch-check.mjs` 253/253 bestanden (Baseline vor diesem
Lauf: 203). Siehe `docs/mandantentrennung-etappe2-fehlerrichtung.md`,
Abschnitt "## Systemkontext (Etappe 3c, 260914-eym)" mit (y1)-(y5). Der
urspruengliche Auftragstext unten bleibt unveraendert stehen (historische
Planungsgrundlage).

Sechs Faelle, alle im Abschnitt "Der Hintergrunddienst als Falle" der
Klassifikation und in den Bereichs-Kritiken:
- `dkv-scheduler` / `loadAnyActiveConfigForScheduler()` (WINDOWS #21) —
  heute bereits falsch (willkuerlicher Mandant).
- `mail.module` / `loadAnySmtpConfigForStartupTransport()` (WINDOWS #30) —
  dieselbe Form.
- `ldap-config.service` `getAllActiveConfigs()` / `onApplicationBootstrap`
  — heute korrekt, verstummt spaeter.
- `tender-digest.scheduler`, `tender-matching.service` — uebergreifende
  Haelften an Etappe 3 uebergeben (260909-laa).
- `admin-seed.service` `ensureDefaultGroupsForAllTenants` — Schleife ueber
  alle Mandanten, Rumpf bereits gebunden.

Bauform: Ein benannter Systemkontext (z. B. `forSystem(prisma)`), der eine
DRITTE Sitzungsvariable `app.system_context = 'true'` setzt, und Regeln,
die diesen Kontext fuer LESENDE Zugriffe zulassen (`OR current_setting(
'app.system_context', true) = 'true'`). Schreibzugriffe innerhalb der
Schleife bleiben je Mandant gebunden. Der DKV- und der SMTP-Startpfad
werden dann zu "einmal-abfragen-viele-bedienen" — das ist die in 07-04
zurueckgestellte Mehrmandanten-Planung und der einzige echte
Funktionsausbau in Etappe 3.

## Was NICHT ohne den User geht

- **3a, Weg (i) vs. (ii):** wie der Mandant beim Login bestimmt wird.
- **Etappe 4:** Scharfschalten. Ausdruecklich.

## Werkzeuge und Fallen (aus Etappe 2, jede mindestens einmal erlebt)

- `git status` ist die Wahrheit, nicht der Agentenbericht. Zwei Agenten
  brachen am Sitzungslimit NACH getaner Arbeit ab.
- Ein `grep -c` ist eine Behauptung. Vier Kopfzahlen schrumpften beim
  Hineinsehen.
- Eine nicht committete Messung ist kein Beleg (zweimal passiert).
- Zusammenfassungen behaupten N, wo N-1 geliefert ist (zweimal passiert).
- Handgepflegte Dokumentstellen werden uebersprungen — Gates ABLEITEN.
- Roh-SQL ist nicht der generierte Client (Wegwerf-Tabelle ohne
  `createdAt`/`updatedAt`).
- Ein Plan-Pruefer, der "plausibel" sagt, hat nicht geprueft.
- `git add` mit mehreren Pfaden, einer davon geloescht, scheitert still.
- Der Datenbank-Container hat keinen Host-Port: IP per `docker inspect`
  frisch ermitteln, `tessera:tessera_dev`. Prisma-Binary aus
  `apps/api/node_modules/.bin/prisma`, NICHT `npx prisma` (zieht Prisma 8).
- Kein `mailhog` lokal — `ENOTFOUND mailhog` ist Umgebung, kein Defekt.
- Backticks in Heredoc-Python werden von der Shell ausgewertet — Skripte
  in eine Datei schreiben, dann ausfuehren.
- Eine Mock-Fabrik ohne den neuen Export wirft erst beim ZUGRIFF
  (vitest-Proxy) — jede Spec, deren Pruefling `forSystem` importiert,
  braucht den Export im Mock (260914-eym: sechs Spec-Dateien).
- Ein Gate mit `grep -rh ... | grep -v spec` filtert KEINE Spec-Dateien
  (`-h` laesst den Dateinamen weg, `spec` steht nicht im Zeilentext) —
  Proben in einer Spec zaehlen mit; Empfaengernamen in Proben deshalb
  anders waehlen als im Produktivcode (260914-eym, `sysPrisma`).

## Einstieg

`/gsd-resume-work`, dann `/gsd-quick` fuer 3b mit `--validate`. Planer,
Plan-Pruefer, Executor, Verifizierer — die Kette vollstaendig, jede
Lieferung wurde in Etappe 2 vom jeweils naechsten Schritt gefangen, nie
vom eigenen.