# 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//…`, **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//…`; 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