Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-P20b.md
T

7.7 KiB

R-P20b · Zentraler Tenant-Bootstrap + SHK-Defaults v2

Typ Dev (Code)
Owner Raffael
Phase P20 — Onboarding-Nachzug / M158
Cycle/Fenster v2-W1 · 2026-07-15 → 2026-07-17
Status In Review · umgesetzt · 8/8 DoD = 100 %

Abhängigkeiten & Parallelität

  • Blocked by: keine offenen Blocker. R-CR1, R-P2a, R-P2b, R-P8a, R-P12a und AK-P20 sind Done.
  • Blocks: VR-P32d konsumiert die stabilen Pipeline-Defaults. R-P12c läuft unabhängig und materialisiert später die Automation-Platzhalter.
  • Betroffene Contracts: Tenant-/User-Erzeugung, RLS-Kontext, globale Admin-Rolle, typisierte Pipeline-/Onboarding-/Automation-Tabellen.
  • Migration: kein neues Prisma-Modell. Der dauerhafte Versionsmarker nutzt IdempotencyKey. Forward-only-Migrationen materialisieren den globalen Checklist-Katalog und härten die bereits vorhandenen Registration-/User-/Invitation-Invarianten sowie den öffentlichen Invite-Resolver.

Was wir bauen

Einen zentralen Lifecycle für neue Workspaces. Tenant, Owner-Mitgliedschaft, exakt eine Owner-Rolle und alle SHK-Defaults werden unter gebundenem Tenant-/User-RLS-Kontext in einer Transaktion angelegt. Der Tenant wird erst im letzten Transaktionsschritt aktiv. Fehler rollen alles zurück; Mail, Billing, Cache, Events und Plugin-Hooks laufen erst nach Commit.

Signup / Neuer Workspace ─┐
                          ├─> atomarer Bootstrap ─> Tenant aktiv ─> Post-Commit-Sideeffects
Owner-Claim Reservierung ─┘

Admin-/Lead-Reservierung ohne Owner ─> Tenant bleibt inaktiv ─> späterer Owner-Claim

Einladungen legen keinen Tenant an. Normale Member-Einladungen starten den Bootstrap nie; ausschließlich ein verifizierter OWNER-Claim darf eine bereits vorhandene inaktive pending_owner-Reservierung atomar provisionieren und aktivieren. Bereits bestehende aktive Tenants werden nicht nachträglich migriert.

Definition of Done

  • Versionierte, schema-validierte SHK-Konfiguration mit stabilem Digest; kein SEED_*-Runtime-Schalter
  • RLS-gebundener, atomarer und idempotenter Bootstrap; Tenant.active=true erst zuletzt, Marker über IdempotencyKey
  • Signup, neuer Workspace und Owner-Claim verwenden denselben Service; ownerlose Admin-/Lead-Anlage bleibt inaktive Reservierung
  • Owner erhält nur globale Admin; fünf editierbare Tenant-Rollen werden mit konservativer Rechte-Matrix angelegt
  • Drei Sales-Pipelines werden angelegt; Wärmepumpe ist Default, bestehende validierte Stage-Baseline wird wiederverwendet
  • Vorhandene Custom-Field-, Projekt-, Abnahme-, Formular- und Checklist-Defaults laufen innerhalb derselben Transaktion
  • Drei unveröffentlichte Automation-Metadaten-Platzhalter werden ohne unbekannte Nodes oder erfundene Parameter angelegt
  • Rollback-, Replay-, RLS-Isolation-, Entry-Point- und Performance-Tests grün; kein Bestands-Tenant wird verändert

Technische Bausteine

  • Pure Config + Zod-Schema unter apps/web/app/domain/tenant-bootstrap/.
  • Zentraler Server-Service mit vorbereiteter User-ID/Passworthash außerhalb der DB-Transaktion.
  • createTenant() reicht den aktiven Prisma.TransactionClient explizit an setup weiter.
  • Marker: partitionKey=tenant:<id>, scope=tenant-bootstrap, key=shk-v2, requestHash=<config-digest>, permanenter erfolgreicher Response-Body.
  • Kein Promise.all innerhalb der interaktiven Prisma-Transaktion.
  • Globale Checklist-Definition ist Deploy-/Migrationskatalog; Runtime erzeugt nur Tenant-/User-Sessions.
  • Keine neue Route oder UI: bestehende Signup-/Workspace-/Admin-Flächen bleiben die Reachability-Grenze; kein Sidebar-/Mobile-/Portal-Eintrag nötig.

Quellen

  • .planning/ticket-docs/R-CR1.md
  • .planning/ticket-docs/R-P2a.md, R-P2b.md, R-P8a.md, R-P12a.md, AK-P20.md
  • docs/security/RLS-HARDENING-2026-07-13.md
  • docs/ARCHITECTURE-DECISIONS.md → AD-1, AD-12, AD-21

Rollback-Pfad

Code-Rollback entfernt die neuen Entry-Point-Aufrufe; unvollständige Transaktionen hinterlassen keine Teilzustände. Die Forward-only-Migrationen bleiben bestehen und haben jeweils Inverse-SQL als Kommentar. Nach erfolgreichem Bootstrap werden Defaults nicht automatisch rückwärts gelöscht, weil Tenant-Änderungen erhalten bleiben müssen.

Umsetzungs-Notiz

2026-07-15 · In Review · R-P20b: 8/8 DoD = 100 % done · 0 offen · 0 blockiert.

  • Proof Code: SHK-Konfiguration und atomare Provisionierung e8db1ac6d, b01dee994, b4c531c48; Entry-Points, Owner-Claims und Einladungsmail 7f334082e, e8838dc0c, a9c25c1b9, f1d85ccb1; DB-/RLS-/CI-Härtung d041a7d08, 3e3b15a20; Replay-, Lockout- und Diagnose-Härtung 1dd2325b1, 7d77da104, 1d4ee37b0, a7e613dcc.
  • Proof Lieferung: PR #119, Feature-Head 93af473c8, normaler Merge-Commit 357d3139e3 mit zwei Eltern; kein Squash. Alle 13 PR-Checks sowie Accessibility-Run 10162 waren grün.
  • Proof Tests: pnpm typecheck, pnpm lint, pnpm test (5.418 grün, 53 übersprungen), Tenant-Coverage 99,43 % Statements/96,66 % Branches, pnpm run verify:tenant-policy-contract (268/268), pnpm run verify:rls-release-readiness (225/225 Modelle), Live-RLS (39 + 7 Bootstrap-Fälle), Migrations-Parität, Identity-/Invite-Migration (13/13), SHK-Migration (9/9), prisma validate, Builds und Runtime-Closures grün.
  • Proof Staging: Deploy-Run 10163 auf Revision 357d3139e3 erfolgreich. One-shot-Migration, Core-Health, abhängige Services, Sentry-Markierung und CDN-Purge waren grün; kein Produktions-Deploy wurde ausgelöst.
  • Der vollständige Bootstrap läuft für Self-Service, neue Workspaces und verifizierte Owner-Claims über denselben atomaren Service. Ownerlose Reservierungen bleiben bis zum Claim inaktiv; Bestands-Tenants werden nicht verändert.

2026-07-20 · Stand-Audit (Akeshan) · R-P20b: 8/8 DoD = 100 % bestätigt · 0 offen · 0 blockiert.

  • Alle 8 DoD-Punkte gegen den realen Code verifiziert, nicht nur gegen die Haken: SHK-v2-Config mit Zod-Schema und stabilem Digest (apps/web/app/domain/tenant-bootstrap/shk-v2.config.ts, kein SEED_* im Modul), atomarer RLS-gebundener Bootstrap mit IdempotencyKey-Marker und active=true als explizit letztem Write (tenantBootstrapService.server.ts §bootstrapShkV2TenantWithTx), gemeinsamer Service für Signup (authService.ts), Workspace-Anlage (TenantsApi.ts) und ownerlose Reservierung (admin/accounts/new), Admin + 5 Tenant-Rollen, 3 Pipelines mit Wärmepumpe-Default, alle Default-Provisioner am selben tx-Client, 3 Automation-Platzhalter (.length(3)-Schema), Test-Suite inkl. Live-RLS-Integration und Performance-Contract.
  • Alle 13 Proof-Commits sowie Merge-Commits 357d3139e3 (PR #119) und bf318a0083 (PR #120) existieren und sind Ancestors von main. Migration 20260715030000_tenant_bootstrap_shk_v2 mit Inverse-SQL-Kommentaren und RLS-bewusstem ACL-Guard vorhanden.
  • Post-RLS-Cutover-Check: Umsetzung erfolgte nach dem 14.07.-Cutover, Kontextbindung durchgängig via runWithRlsContext; kein Regressions-Risiko gefunden. Kein Drift zwischen Doc, Plane und Code. Kein design-nachzug (kein UI-Ticket). Status In Review bleibt bewusst bis zum Sign-off.

2026-07-29 · Dependency-Nachzug aus R-P2a.

Konfigurierte Pflichtfelder werden im Signup jetzt vor dem gemeinsamen Tenant-Bootstrap unabhängig vom Passwortzweig geprüft. Leere Firma oder leerer Vor-/Nachname können den atomaren SHK-Provisionierungsservice damit nicht mehr erreichen. Bootstrap-, Replay-, RLS- und Default-Verträge bleiben unverändert.

Fortschritt: R-P20b bleibt bei 8/8 DoD = 100 % done.