Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/ticket-docs/VA-P26a.md
T

5.2 KiB

VA-P26a · P26 Customer-Portal: Auth/Magic-Link + Projekt-Sicht + Status-Mails ⭐

Typ Dev (Code)
Owner Akeshan
Phase P26 — Customer-Portal · v2-P6 (ex-P18)
Cycle/Fenster v2-W2 — KWP/Portal/Mobile-Start · fällig 2026-07-21
Status geplant

Abhängigkeiten & Parallelität

  • Blocked by: AK-P4a (FileEntityLink — Doc-Freigabe + Portal-Uploads), R-P6 (CRM), R-P9a (Projekt — Project-Stages/Stage-Trigger)
  • Blocks: VA-P26b (Upload/Reklamation/Skalierung baut auf der Portal-Auth-Schicht auf)
  • Läuft parallel zu: Raffaels VR-P5/KWP im selben Fenster v2-W2 — disjunkte Domänen. Eigene prisma/schema/customer-portal.prisma (AD-21); crm.prisma/project.prisma/files.prisma nur über FK.
  • Konflikt-Risiko: mittel — eigene Auth-Schicht parallel zum TenantUser-Auth (NICHT geteilt); strikte Cookie-/Route-Trennung erforderlich.

Was wir bauen

Die eigene Auth-Schicht des Customer-Portals (⭐ einzige extern sichtbare Endkunden-Oberfläche, höchster Polish): eine strikt von TenantUser getrennte PortalUser-Klasse (eigene Cookies, eigene Routes unter /portal/<tenant>/…, keine Permission-Vermischung), Magic-Link primär. Endkunden sehen nur eigene Projekte / konfigurierte Stages / freigegebene Dokumente; fehlender Zugang → 404 (keine Existenz-Offenlegung). Bei project.stage_changed gehen Auto-Status-Mails raus (debounced, bedingungsgesteuert).

Benötigte Screens (Backend bedient — Design liefert D-P26, externer Polish)

Screen [Route] Kern-Inhalt
Endkunde · Login [/portal/{tenant}/login · /login/magic-sent] Magic-Link primär, Passwort sekundär, „Magic-Link gesendet"-Bestätigung, kein User-Enumeration
Endkunde · Setup/Verify/Reset [/portal/{tenant}/setup/{token} · /verify-email/{token} · /forgot-password · /reset-password/{token}] Erstzugang-Setup, E-Mail-Verifizierung, Passwort-Vergessen/-Reset
Endkunde · Portal-Dashboard [/portal/{tenant}] Übersicht eigene Projekte + Status, freigegebene Dokumente, Schnellaktionen
Endkunde · Projekte-Liste [/portal/{tenant}/projects] Liste eigener Projekte (Name, Stage/Fortschritt, letztes Update)
Endkunde · Project-Detail [/portal/{tenant}/projects/:id] Fortschritt (nur sichtbare Stages), freigegebene Dokumente (Download)
Tenant-Admin · Mail-Template-Editor [/admin/portal/email-templates] Auto-Status-Mail-Vorlagen je Stage-Event, Variablen, Vorschau

Definition of Done

  • Eigene PortalUser-Klasse strikt getrennt von TenantUser (eigene Cookies/Routes, keine Permission-Vermischung); Magic-Link primär
  • Endkunde sieht nur eigene Projekte / konfigurierte Stages / freigegebene Dokumente; fehlender Zugang → 404 (keine Existenz-Offenlegung)
  • Auto-Status-Mails bei project.stage_changed (Debounce; Bedingungen: sichtbare Stage / aktiver Access / Pref / nicht frozen)
  • Härtung: Rate-Limits, Captcha, kein User-Enumeration, wasserdichte Cookie-Trennung
  • Wiederverwendung v1: Auth-Pattern (parallel, NICHT geteilt), Sende-Domain (Auto-Mails), notify(), Tenant-Lifecycle (frozen→read-only)
  • RLS auf allen Portal-Tabellen (über Tenant); Access-Filter serverseitig

Technische Bausteine

  • Entities (eigene prisma/schema/customer-portal.prisma, AD-21): PortalUser (eigene Identitäts-Klasse, NICHT TenantUser), Portal-Session/-Cookie-Modell (SameSite, getrennt), Magic-Link-Token + Setup/Verify/Reset-Token, PortalProjectAccess (welcher PortalUser sieht welches Projekt), PortalStageVisibility-Konfig, PortalEmailTemplate je Stage-Event. project.prisma/crm.prisma/files.prisma nur über FK (AD-21).
  • Auth-Trennung: eigene Cookies, eigene Middleware-Kette unter /portal/<tenant>/…; Auth-Pattern aus v1 kopiert, nicht geteilt (kein Cross-Routing, keine Permission-Vermischung). Fehlender Zugang → 404 statt 403 (keine Enumeration).
  • Auto-Status-Mails: Listener auf project.stage_changed (v1-Project-Stage-Trigger) → debounced Job; Bedingungs-Resolver (sichtbare Stage / aktiver Access / Pref / nicht frozen); Versand über v1-Sende-Domain; Templates aus PortalEmailTemplate.
  • Härtung: Rate-Limits + Captcha auf allen Auth-Routes; RLS auf Tenant-Tabellen; is_demo_data auf seedbaren Portal-Demos.

Quellen (granular)

  • ROADMAP-V2.md → §v2-P6 Customer-Portal (Auth-Trennung/Magic-Link/Status-Mails = Hauptquelle; Depends-on/Success-Criteria/Recut)
  • ENTITY-MODEL.md → Domäne 5 (Project-Stages) + Domäne 4 Files/FileEntityLink (Doc-Freigabe in P4 vorbereitet); PortalUser = parallele Auth-Klasse (kein geteiltes Auth-Modell)
  • ROADMAP.md → Phase 26 · PHASE-SOURCES.md → Phase 26 (M141 Auth/Magic-Link, M142 Projekt-Sicht + Status-Mails)
  • designer-briefs/P26-customer-portal.md (⭐ externer Polish, Auth-Trennung, 404-State, Mail-Template-Editor)
  • _bmad-output/specs/M15-customer-portal.md (Portal)

Dev-Nachzug (nach Davids D-P26-Delta)

  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/PHASE-SOURCES nachgezogen
  • Plane-Ticket VA-P26a aktualisiert