UC00 Backend-Stabilisierung¶
Stand: 10.08.2026 20:00 Branch: main Status: In Bearbeitung
| Datum, Uhrzeit | Version | Änderung | Autor |
|---|---|---|---|
| 10.08.2026 20:00 | 1.7 | Sicheren UC00-Merge-Stand nach main übernommen und aktuellen Übergang nachgeführt |
Codex |
| 10.08.2026 19:46 | 1.6 | Backend-Build wiederhergestellt, AWS-KMS-TOTP-Pfad unit-getestet, vierte Migration ausgerollt und sichere Vertragsvorbereitung als nächstes Integrationspaket abgegrenzt | Codex |
| 09.08.2026 17:32 | 1.5 | Globale E-Mail- und Einladungstokenlogik mit elf Unit-Tests, dritter Migration und achter Datenbankprüfung nachgeführt | Codex |
| 09.08.2026 16:40 | 1.4 | Datenbank-Rollout, sicheren Basis-Seed sowie getrennte Prisma-Runtime-Clients und Kontextwrapper nachgeführt | Codex |
| 09.08.2026 14:41 | 1.3 | Formal validiertes Prisma-v4-Zielschema übernommen und initiale Migration als nächsten Schritt festgelegt | Codex |
| 09.08.2026 14:24 | 1.2 | Akzeptierte RLS-Strategie als Grundlage für UC00-Zielschema und Migration nachgeführt | Codex |
| 09.08.2026 14:12 | 1.1 | Nächsten Datenbank- und Seed-Schritt auf das gemäss ADR-010 führende Migrationsverfahren umgestellt | Codex |
| 01.08.2026 14:55 | 1.0 | Kopfbereich vereinheitlicht | David Mittig |
Ziel dieses Branches¶
Dieser Branch diente dazu, den vorhandenen UC00-Backend-Stand praktisch lauffähig zu machen, zu prüfen, zu korrigieren und nachvollziehbar zu dokumentieren.
stabilize-uc00-backend
Der Branch wurde am 01. August 2026 in main gemergt.
Die Stabilisierung wird seitdem direkt auf main in kontrollierten Arbeitspaketen fortgeführt. Historische Prüfergebnisse bleiben als solche erhalten; der aktuelle verbindliche Stand steht im UC00-Dossier, im Projektstatus und in der Abschlusscheckliste.
Nicht Ziel dieses Branches war der Ausbau neuer Fachfunktionen für UC01. Zuerst sollte der technische UC00-Kern stabil sein.
Architekturentscheid Datenbank-Hosting¶
Supabase wird aktuell nur als Entwicklungsumgebung verwendet.
Für die spätere Produktivumgebung soll die Anwendung möglichst generisch PostgreSQL-fähig bleiben. Ein späterer Betrieb bei einem anderen Hoster, zum Beispiel Hetzner, soll nicht durch harte Supabase-Abhängigkeiten erschwert werden.
Leitlinien:
- Prisma soll möglichst normales PostgreSQL verwenden.
- Supabase-spezifische Funktionen dürfen nur verwendet werden, wenn sie bewusst entschieden und dokumentiert sind.
- Konfigurationen sollen über
.envaustauschbar bleiben. .env.exampledarf Supabase als Dev-Beispiel enthalten, soll aber nicht suggerieren, dass Supabase die einzige Zielplattform ist.- Migrations-, Seed- und Deployment-Dokumentation soll später generisch PostgreSQL-fähig bleiben.
- Auth, Tenant-Isolation und Geschäftslogik sollen nicht von Supabase-spezifischen Annahmen abhängig sein.
Ausgangslage¶
Im Repository sind bereits vorhanden:
- Backend-Grundstruktur mit NestJS
- Prisma-Schema für PostgreSQL
- Module für Auth, Tenants, Users und Onboarding
- Security-Basis mit Helmet, CORS, Cookie Parser und ValidationPipe
- Auth-Logik mit Login, Logout, Refresh Token, 2FA und Invitation Redeem
- Tenant-Logik mit Erstellung, Suche, Statuswechsel und Planverwaltung
- Dokumentation zur geplanten Architektur
Zum damaligen Ausgangszeitpunkt extern vorhanden:
- Die 18 Tabellen sind auf Supabase als Dev-Datenbank installiert.
Zum damaligen Ausgangszeitpunkt noch nicht praktisch nachgewiesen:
- Verbindung des Backends zur vorhandenen Supabase-Dev-Datenbank
- Abgleich von
backend/prisma/schema.prismagegen den realen Supabase-Stand - Seed eines SuperAdmins
- vollständiger UC00-Testfluss
Zum damaligen Ausgangszeitpunkt praktisch nachgewiesen:
- Installation der Abhängigkeiten
- Prisma Client Generierung
- TypeScript Build
- Testlauf wurde gestartet, aktuell sind noch keine Tests vorhanden
Prüfreihenfolge¶
1. Lokale Backend-Basis prüfen¶
Ausführen im Ordner backend:
npm install
npm run prisma:generate
npm run build
npm test
Ziel:
- Abhängigkeiten werden installiert
- Prisma Client wird erzeugt
- Backend kompiliert ohne Fehler
- vorhandene Tests laufen oder fehlende Tests werden sichtbar
Status:
Teilweise abgeschlossen
Ergebnis bisher:
npm installerfolgreichnpm run prisma:generateerfolgreichnpm run builderfolgreich nach Korrektur der Auth-DTO-Dateistrukturnpm testausgeführt, aber keine Tests vorhanden
Aktueller Stand: Datenbank und Basis-Seed sind mit vier Migrationen ausgerollt. Fünf Prisma-Kontextwrapper-, elf E-Mail-/Einladungs-, drei AWS-KMS-TOTP- und drei Tenant-Service-Unit-Tests sind erfolgreich. Der Backend-Build ist nach Prisma-Client-Erzeugung erfolgreich; die vollständige Vertragsintegration bleibt offen.
2. Konfiguration prüfen¶
Zu prüfen:
- Existiert eine vollständige
.env.example? - Sind
DATABASE_URLfür Plattform-Runtime,DATABASE_TENANT_URLfür Tenant-Runtime undDIRECT_URLausschliesslich für Migrationen dokumentiert? - Ist gleichzeitig klar dokumentiert, dass Supabase nur Dev-Umgebung ist?
- Sind JWT-Schlüssel und Cookie-/CORS-Einstellungen klar beschrieben?
- Sind Entwicklungswerte von Produktionswerten getrennt?
- Ist dokumentiert, dass
.envnicht committet werden darf?
Status:
In Bearbeitung
3. Prisma und Supabase abgleichen¶
Die frühere 18-Tabellen-Ausgangsbasis wurde nach einer vollständigen Inventur ohne Fach- oder Personendaten kontrolliert ersetzt. Das Prisma-v4-Zielschema ist mit 35 Fachtabellen und vier versionierten Migrationen ausgerollt.
Zu prüfen:
- Passt
backend/prisma/schema.prismazum realen Supabase-Stand? - Passt
backend/prisma/schema.prismazum SQL-Stand indatabase/schema-final.sql? - Sind ENUMs, Tabellen, Relationen und Spaltennamen konsistent?
- Bestätigt
prisma migrate statusdie eingecheckte Migrationsfolge? - Funktionieren
prisma validate,prisma generate, Migrationsvalidator und RLS-Basisprüfung weiterhin? - Entstehen Supabase-spezifische Annahmen, die einen späteren Wechsel auf generisches PostgreSQL erschweren würden?
Status:
Teilweise abgeschlossen: Datenbank nachgewiesen, vollständige Backend- und Runtime-Login-Prüfung offen
4. Basis-Seed und kontrollierte Testdaten für UC00 vorbereiten¶
Ziel:
Der automatische Basis-Seed enthält ausschliesslich nicht personenbezogene Referenzdaten. Benutzer, Tenants und Token werden für Integrations- und End-to-End-Tests getrennt, kontrolliert und vollständig rücksetzbar aufgebaut.
Minimal benötigte Testdaten:
| Kontrolliertes Testdatenobjekt | Zweck | Pflicht für UC00 |
|---|---|---|
| SuperAdmin | Einstieg in die Systemverwaltung | Ja |
| Test-Tenant | Mandant für den UC00-Testfluss | Ja |
| Tenant-Admin-Einladung | Prüfung des Einladungsprozesses | Ja |
| Tenant-Admin | Prüfung Login und Tenant-Kontext | Ja |
| Testkunde | Vorbereitung für späteren UC01-Durchstich | Nein, aber sinnvoll |
| Testflasche | Vorbereitung für späteren UC01-Durchstich | Nein, aber sinnvoll |
| TÜV-Testworkflow | Vorbereitung für späteren UC01-Durchstich | Nein, aber sinnvoll |
Wichtige Regeln:
- Seed-Daten dürfen keine echten Kundendaten enthalten.
- Automatische Seed-Passwörter und dauerhaft angelegte Testkonten sind unzulässig.
- Der Referenz-Seed muss idempotent sein, also mehrfach ausführbar ohne Dubletten zu erzeugen.
- UC00- und spätere UC01-Testdaten bleiben vom Referenz-Seed getrennt.
- Der Seed soll keine harte Bindung an Supabase-spezifische Mechanismen enthalten.
Status:
Basis-Seed abgeschlossen; fachlicher Testdatenaufbau offen
Ergebnis:
backend/prisma/seed.tsauf drei globale Benachrichtigungsvorlagen und vier Plan-Features begrenzt- keine Benutzer, Tenants, Passwörter oder Token im automatischen Seed
- Basis-Seed am 09. August 2026 erfolgreich gegen die Entwicklungsdatenbank ausgeführt
5. UC00-Testprotokoll detailliert¶
A. Vorbereitung¶
| Schritt | Erwartung | Status |
|---|---|---|
.env aus .env.example erstellt |
lokale Werte vorhanden | offen |
| Dev-Datenbank-Verbindungen eingetragen | getrennte Plattform-, Tenant- und Migrationszugänge gesetzt | in Bearbeitung |
| Prisma Client generiert | keine Fehler | erledigt |
| Backend Build | keine TypeScript-Fehler | erledigt – am 10.08.2026 erfolgreich |
| API lokal gestartet | http://localhost:3000/v1 erreichbar |
offen |
B. SuperAdmin¶
| Schritt | Erwartung | Status |
|---|---|---|
| SuperAdmin kontrolliert als Testvoraussetzung angelegt | User mit Rolle superadmin existiert |
offen |
| SuperAdmin Login | Access Token und Refresh Cookie werden erzeugt | offen |
| Ungültiges Passwort | generische 401-Antwort | offen |
| Logout | Refresh Token wird widerrufen | offen |
C. Tenant-Management¶
| Schritt | Erwartung | Status |
|---|---|---|
| Tenant erstellen | neuer Tenant mit Status contract_pending |
offen |
| Tenant-Liste abrufen | Tenant erscheint in Liste | offen |
| Tenant anzeigen | Detaildaten werden geliefert | offen |
| Tenant-Status ändern | erlaubter Statusübergang funktioniert | offen |
| Ungültiger Statusübergang | 400-Fehler | offen |
| Tenant-Plan abrufen | Planlimits werden berechnet | offen |
| Tenant-Plan ändern | Plan wird aktualisiert | offen |
| Downgrade-Konflikt | wird erkannt und blockiert | offen |
D. Invitation und Tenant-Admin¶
| Schritt | Erwartung | Status |
|---|---|---|
| Tenant-Admin-Einladung erzeugen | Invitation Token existiert | offen |
| Einladung einlösen | Tenant-Admin bleibt bis zur abgeschlossenen Zwei-Faktor-Einrichtung invited |
offen |
| Bereits verwendete Einladung erneut nutzen | 410-Fehler | offen |
| Tenant-Admin Login | Login funktioniert im Tenant-Kontext | offen |
E. Token und Sicherheit¶
| Schritt | Erwartung | Status |
|---|---|---|
| Refresh Token | Access Token wird erneuert | offen |
| Refresh Token Rotation | alter Refresh Token wird widerrufen | offen |
| Wiederverwendung alter Refresh Token | Sicherheitsfall wird erkannt | offen |
| Rollenprüfung SuperAdmin-Endpunkte | Nicht-SuperAdmin wird blockiert | offen |
| Tenant-Isolation | fremder Tenant-Zugriff wird blockiert | offen |
6. Tests ergänzen¶
Priorität:
- AuthService
- TenantsService
- Guards und Rollenprüfung
- Invitation Redeem
- Refresh Token Rotation
Status:
Offen
Abnahmekriterien für diesen Branch¶
Der Branch gilt als erfolgreich stabilisiert, wenn folgende Punkte erfüllt sind:
npm installläuft ohne kritische Fehlernpm run prisma:generateläuft erfolgreichnpx prisma db pullkann den realen Dev-Datenbank-Stand lesen- Abweichungen zwischen Prisma-Schema und Dev-Datenbank sind geprüft und bewertet
- Es ist bewertet, ob Supabase-spezifische Annahmen bestehen
npm run buildläuft erfolgreich- vorhandene oder neue Tests laufen nachvollziehbar oder fehlende Tests sind dokumentiert
- eine Dev-Datenbank kann verbunden werden
- ein SuperAdmin kann kontrolliert als Testvoraussetzung angelegt und entfernt werden
- ein Tenant kann erstellt werden
- ein Tenant-Admin kann eingeladen und aktiviert werden
- Login, Refresh Token und Logout funktionieren
- die notwendigen Schritte sind in der Entwicklerdokumentation beschrieben
Testprotokoll¶
| Datum | Bereich | Ergebnis | Bemerkung |
|---|---|---|---|
| 2026-05-02 | Backend Install | erfolgreich | npm install hat 778 Pakete installiert; 30 Vulnerabilities gemeldet |
| 2026-05-02 | Prisma Generate | erfolgreich | Prisma Client v5.22.0 erzeugt |
| offen | Supabase db pull | offen | noch nicht geprüft |
| 2026-05-02 | Build | erfolgreich | nach Verschieben der Auth-DTOs in auth/dto |
| 2026-05-02 | Tests | keine Tests vorhanden | Jest läuft, findet aber keine *.spec.ts Dateien |
| offen | Dev-Datenbank | offen | 18 Tabellen sind bereits installiert |
| offen | UC00 Flow | offen | noch nicht geprüft |
| 2026-08-01 | 2FA-Setup-Flow | implementiert ✅ | POST /auth/2fa/setup, POST /auth/2fa/verify-setup, POST /auth/2fa/disable |
| 2026-08-01 | MailService | implementiert ✅ | nodemailer, sendInvitation(), sendRecoveryCodes() via SMTP |
| 2026-08-01 | OnboardingService | implementiert ✅ | getStatus, saveStep (company_profile / contact / invite_admin), complete |
| 2026-08-01 | Seed-Script | erstellt ✅ | prisma/seed.ts – SuperAdmin + Test-Tenant + PlanFeatures (upsert, idempotent) |
| 2026-08-01 | P1-Push nach main | erfolgreich ✅ | Business-Logik via MCP in GitHub main gepusht (2 Commits) |
| 2026-08-09 | Entwicklungsdatenbank | erfolgreich | Zwei Migrationen, 35 RLS-geschützte Fachtabellen und sieben Referenzdatensätze nachgewiesen |
| 2026-08-09 | RLS-Basisprüfung | erfolgreich | Sieben Laufzeitprüfungen mit vollständigem Rollback bestanden |
| 2026-08-09 | Prisma-Kontextwrapper | erfolgreich | Getrennte Clients, Konfigurationssperren und transaktionslokaler Kontext mit fünf Unit-Tests geprüft |
| 2026-08-09 | E-Mail-Identität und Einladungstoken | erfolgreich | Zentrale Normalisierung, globale Konfliktprüfung, ausschliessliche Hashspeicherung und kontrollierte Datenbankkonflikte mit elf Unit-Tests geprüft |
| 2026-08-09 | E-Mail-Schutzmigration | erfolgreich | Dritte Migration ausgerollt und global eindeutige offene Einladungsadresse als achte Datenbank-Laufzeitprüfung bestanden |
| 2026-08-10 | Backend-Build | erfolgreich | Nach prisma generate ohne TypeScript-Fehler abgeschlossen |
| 2026-08-10 | AWS-KMS-TOTP-Pfad | in Bearbeitung | Verschlüsselung und Entschlüsselung mit gebundenem Kontext sowie drei Unit-Tests umgesetzt; produktive Schlüssel-, Rechte-, Rotations- und Ausfallnachweise offen |
| 2026-08-10 | Vertragskontaktmigration | erfolgreich | Vierte additive Migration kontrolliert angewendet; prisma migrate status und Inventar bestätigen vier abgeschlossene Migrationen ohne Fach- oder Personendaten |
| 2026-08-10 | Sichere Tenant-Vorbereitung | in Bearbeitung | Pflicht-Plan, getrennte Vertragskontaktdaten und kontrollierte Einladungssperren mit drei Unit-Tests umgesetzt; Vollständigkeitssperre beim Abschluss, Benutzer-Voranlage, Einladung und Vertragsabschluss offen |
Nächster konkreter Schritt¶
Die P1-Basis mit vier Migrationen, erfolgreichem Backend-Build, AWS-KMS-TOTP-Pfad und sicherem Tenant-Vorbereitungspaket ist lokal nach main übernommen. Die Veröffentlichung und der dadurch ausgelöste Cloudflare-Build sind getrennt nachzuweisen.
npm run prisma:generate
npm test -- --runInBand
npm run build
prisma db push ist für die gemeinsame Entwicklungsdatenbank nicht mehr zulässig. Als Nächstes wird das sichere Tenant-Vorbereitungspaket gegen die migrierte Entwicklungsdatenbank integriert. Danach folgen Benutzer-Voranlage und Admin-Einladung sowie die beiden vollständigen Vertragsabschlusswege mit Dokument- und Auditnachweis.