--- module: 15 title: Customer-Portal (Endkunden-Login) phase: 1 status: detail-spec-draft last_updated: 2026-05-08 session_source: brainstorming-session-2026-05-07-2206.md related_lps: [LP-1, LP-2, LP-3, LP-7, LP-9, LP-10, LP-13] spec_style: requirements-pur --- # Modul 15 — Customer-Portal (Endkunden-Login) > **Detail-Spec gemäß LP-9.** Endkunden-Sicht auf eigene Projekte, Dokumente und Status. Kritisch für Geerkens-Launch (User-Korrektur). Eigene Auth-Schicht parallel zu M27 (separate `PortalUser`-Klasse, **NICHT** `TenantUser`). URL-Schema `app.hivegrid.de/portal/{tenant}/...`. ## Themenblöcke ``` A. Datenmodell (Portal, PortalUser, Auth, ProjectAccess, Documents) B. Menü-Struktur und Routes (Portal-Seite + Tenant-Admin-Seite) C. Auth-Schicht (Magic-Link + Pwd, Setup-Flow, Session) D. Portal-Endkunden-Views (Dashboard, Projekte, Dokumente, Upload) E. Tenant-Admin-Konfiguration (Phasen-Sichtbarkeit, Doc-Freigabe, Templates, Branding) F. PortalUser-Lifecycle (Anlage, Einladung, Reset, Entfernen) G. Auto-Status-Mails bei Phasenwechsel H. Integration mit anderen Modulen I. Permissions-Anwendung (Tenant-Seite + Portal-Seite) J. DSGVO / Lösch-Workflow K. Klartext-Hinweise/-Fehler L. Phase 2 / spätere Features ``` --- ## Block A — Datenmodell ### Architektur-Entscheidung PortalUser ist **eigene User-Klasse**, vollständig getrennt vom internen `TenantUser` aus M27. Begründung: - Andere Auth-Anforderungen (Magic-Link primär, kein 2FA-Pflicht, kein Tenant-Admin-Konzept) - Andere Permissions (nur eigene Projekte sehen, keine Modul-Permissions) - Andere Lifecycle-Events (keine Onboarding-Wizards, kein Tenant-Switcher) - Andere DSGVO-Klassifizierung (Endkunde = Datensubjekt, MA = Mitarbeiter) - Vermeidung von Permission-Eskalation (Endkunde darf niemals versehentlich Tenant-Permissions erhalten) ### Kern-Entitäten ``` Portal — ein Portal pro Tenant (Phase 1: Default-Portal pro Tenant) PortalUser — Endkunde mit Login PortalUserRegistration — Setup-Flow-Token (erstes Login + Pwd-Setzen + Profil) CustomerPortalAccount — Account-Daten zu PortalUser (Pwd-Hash, Profil, Status) CustomerPortalMagicLinkToken — kurzlebige Login-Token CustomerPortalSession — Server-Side-Session pro PortalUser CustomerPortalProjectAccess — welcher PortalUser sieht welches Project CustomerPortalProjectDocument — welche Files innerhalb eines Project sind freigegeben PortalConfiguration — Tenant-Konfiguration (Phasen-Sichtbarkeit, Doc-Freigabe-Defaults, Branding) PortalEmailTemplate — Auto-Status-Mail-Templates pro Tenant ``` ### Portal - `id`, `tenant_id` (unique pro Tenant in P1 — ein Default-Portal), `created_at`, `updated_at` - `slug` (default `portal`, in P1 nicht änderbar — URL-Schema-Stabilität) - `name` (User-sichtbar, z.B. „Geerkens Kundenbereich") - `is_default` (true für P1) - `enabled` (Boolean — Tenant kann Portal deaktivieren ohne Daten-Verlust) - `archived_at` **Phase 2:** mehrere Portale pro Tenant mit unterschiedlichem Branding/Slug. ### PortalUser - `id`, `tenant_id`, `portal_id`, `created_at`, `updated_at`, `created_by_user_id` (TenantUser, der Zugang anlegte) - `email` (Pflicht, unique pro Portal — Login-Identifier) - `first_name`, `last_name` (Pflicht) - `phone` (optional) - `language` (DE/EN, default DE — für Auto-Mails) - `linked_contact_id` (FK auf `Contact` aus M1 — verknüpft mit Stammdaten, optional, kann nachträglich verknüpft werden) - `linked_company_id` (FK auf `Company` aus M1, optional) - `status` (Enum: `pending_setup | active | disabled | deleted`) - `last_login_at` - `archived_at` **Wichtig:** `linked_contact_id` ist optional, weil PortalUser auch unabhängig vom CRM angelegt werden kann (z.B. Bauherr ohne CRM-Eintrag). Verknüpfung empfohlen für vollen Funktionsumfang. ### CustomerPortalAccount - `id`, `portal_user_id` (1:1) - `password_hash` (nullable — Magic-Link-Only-Modus möglich) - `password_set_at` - `email_verified_at` - `failed_login_attempts`, `locked_until` - `last_password_reset_at` - `terms_accepted_at` (DSGVO) - `marketing_opt_in` (Boolean, default false) ### CustomerPortalMagicLinkToken - `id`, `portal_user_id`, `tenant_id` - `token_hash` (64-Zeichen, kryptographisch sicher, URL-safe — gespeichert als Hash) - `purpose` (Enum: `login | setup | password_reset | email_verification`) - `created_at`, `expires_at`, `used_at` (NULL bis Verwendung) - `requested_ip`, `requested_user_agent` **Lebenszeiten:** - `login`: 15 Minuten - `setup`: 7 Tage - `password_reset`: 1 Stunde - `email_verification`: 24 Stunden ### CustomerPortalSession - `id`, `portal_user_id`, `tenant_id`, `portal_id` - `created_at`, `last_activity_at`, `expires_at` - `ip_address`, `user_agent` - `revoked_at` **Default-Lebenszeit:** 30 Tage Sliding-Window (analog M27 B.5, aber ohne 2FA-Re-Verify). ### PortalUserRegistration - `id`, `portal_user_id`, `tenant_id`, `setup_token_id` (FK auf MagicLinkToken mit `purpose=setup`) - `created_at`, `completed_at` - `created_by_user_id` (TenantUser) - `welcome_message` (Freitext aus Einladungs-Modal — wird in Setup-Mail eingebettet) ### CustomerPortalProjectAccess - `id`, `tenant_id`, `portal_user_id`, `project_id` - `granted_at`, `granted_by_user_id` (TenantUser) - `revoked_at` (Soft-Revoke — Zugriff entzogen, History bleibt) - `access_level` (Enum: `read_status_only | read_full` — `read_status_only` zeigt nur Phase, keine Files/Details; default `read_full`) **Indizes:** `tenant_id, portal_user_id`, `tenant_id, project_id`. **Wichtig:** Mehrere PortalUser können auf dasselbe Projekt Zugriff haben (z.B. Bauherr + Architekt). Ein PortalUser kann mehrere Projekte sehen. ### CustomerPortalProjectDocument - `id`, `tenant_id`, `project_id`, `file_id` (FK auf File aus M23) - `released_at`, `released_by_user_id` - `revoked_at` - `release_kind` (Enum: `manual | auto_by_doc_type | auto_by_acceptance` — wie wurde freigegeben) - `customer_visible_filename` (optional Override des Dateinamens für Endkunde) **Default-Logik:** Files aus Project sind **nicht** automatisch freigegeben. Tenant-Admin konfiguriert pro Doc-Typ (Angebot/Rechnung/Acceptance) automatische Freigabe-Regel; Einzel-Files können manuell freigegeben oder gesperrt werden. ### PortalConfiguration - `id`, `tenant_id`, `portal_id` (1:1 in P1) - `visible_pipeline_stages` (JSON pro Pipeline: `{ pipeline_id: [stage_id, stage_id, ...] }`) — welche Stages sieht der Endkunde - `stage_display_labels` (JSON: `{ stage_id: "Kunden-Label" }`) — Override für Klartext-Bezeichnung gegenüber Endkunde - `auto_release_doc_types` (JSON-Array: `["angebot", "rechnung", "acceptance_pdf"]` — diese Doc-Typen werden bei Anlage/Generierung automatisch freigegeben) - `auto_status_mail_enabled` (Boolean pro Stage-Wechsel-Event) - `branding_logo_file_id` (Phase 1: nutzt Tenant-Logo aus M27; Phase 2: Portal-eigenes Logo) - `branding_primary_color` (Phase 1: nutzt Tenant-Farbe; Phase 2: Portal-eigene Farbe) - `welcome_message_default` (Freitext — wird im Setup-Flow gezeigt) - `support_email` (Default = Tenant-Support-Email) - `support_phone` (optional) - `imprint_url`, `privacy_url` (Pflicht — Endkunde muss Tenant-Impressum + Datenschutz erreichen) - `terms_url` (optional, falls Tenant Sonder-AGB für Portal hat) ### PortalEmailTemplate - `id`, `tenant_id`, `portal_id` - `template_kind` (Enum: `setup_invitation | login_magic_link | password_reset | stage_changed | document_released | upload_received`) - `subject` (mit Platzhaltern: `{{customer_name}}`, `{{project_title}}`, `{{stage_name}}`, ...) - `body` (Markdown mit Platzhaltern) - `from_email_address_id` (FK auf verbundene Sending-Domain aus M9; default Tenant-Default) - `is_active` (Boolean) **Default-Templates** werden beim Tenant-Anlegen geseedet (DE-Klartext, Tenant-Admin kann anpassen). ### PortalSubscription* (Phase 2 — Stub) - Vorgesehen für Abos im Portal (Wartungs-Abo, Service-Pakete) — nicht in P1. --- ## Block B — Menü-Struktur und Routes ### Endkunden-Routes (öffentlich erreichbar) ``` /portal/{tenant}/ → Portal-Dashboard (Login-required) /portal/{tenant}/login → Login (Magic-Link + Pwd) /portal/{tenant}/login/magic-sent → Bestätigung „Link versendet" /portal/{tenant}/setup/{token} → Erst-Login-Setup (Pwd setzen, Profil) /portal/{tenant}/forgot-password → Pwd-Reset-Anfrage /portal/{tenant}/reset-password/{token} → Neues Pwd setzen /portal/{tenant}/verify-email/{token} → Email-Verification /portal/{tenant}/projects → Liste eigener Projekte /portal/{tenant}/projects/:id → Project-Detail (Endkunden-Sicht) /portal/{tenant}/documents → Alle freigegebenen Dokumente (Cross-Project) /portal/{tenant}/upload → Datei-Upload (z.B. Reklamations-Fotos) /portal/{tenant}/forms/:formSlug → Form ausfüllen (Reklamation, Service-Anfrage — über M5) /portal/{tenant}/settings/ → Profil + Pwd ändern + Email ändern /portal/{tenant}/settings/notifications → Email-Notification-Präferenzen /portal/{tenant}/settings/account-delete → DSGVO-Lösch-Antrag /portal/{tenant}/logout → Logout /portal/{tenant}/imprint → Impressum (verlinkt aus PortalConfiguration) /portal/{tenant}/privacy → Datenschutz ``` **Wichtig:** Portal-Routes nutzen **eigene Auth-Middleware** (`requirePortalUser`), unabhängig von M27 `requireTenantUser`. Cookies/Sessions sind getrennt — ein TenantUser mit aktiver M27-Session kann das Portal nicht ohne separaten PortalUser-Login betreten. ### Tenant-Admin-Routes (im Tenant-Workspace) ``` /{tenant}/admin/portal/ → Portal-Konfiguration (Phasen-Sichtbarkeit, Doc-Freigabe, Branding, Auto-Mails) /{tenant}/admin/portal/users → PortalUser-Verwaltung (Liste, Anlage, Reset, Entfernen) /{tenant}/admin/portal/users/:id → PortalUser-Detail /{tenant}/admin/portal/access → Cross-Project-Übersicht: welcher PortalUser sieht welches Project /{tenant}/admin/portal/email-templates → Auto-Status-Mail-Templates editieren /{tenant}/admin/portal/audit → Portal-Audit (Logins, Uploads, Doc-Zugriffe) ``` ### Tenant-Workspace-Erweiterungen (in bestehenden Modulen) - **Project-Detail (M4):** Sektion *„Customer-Portal"* mit: - Liste der PortalUser mit Zugang zu diesem Project - Button „PortalUser einladen" (öffnet Modal — kann aus verknüpftem Contact vorausgefüllt werden) - Pro File: Toggle „Im Customer-Portal freigegeben" (mit Wirkung auf `CustomerPortalProjectDocument`) - Toggle „Auto-Status-Mails an Kunde aktiv für dieses Project" (Override pro Project) - **Contact-Detail (M1):** Sektion *„Portal-Zugang"* mit: - Falls verknüpfter PortalUser: Status, Letzter Login, Liste sichtbarer Projekte - Falls nicht: Button „Portal-Zugang einladen" - **Deal-Detail (M3):** Toggle „Sales-Phase im Portal sichtbar" — aktiviert Portal-Zugang ab Lead/Deal-Phase (vor Project-Anlage) --- ## Block C — Auth-Schicht ### C.1 — Magic-Link-Login (primär) **Flow:** 1. Endkunde öffnet `/portal/{tenant}/login` 2. Tippt Email → Submit 3. System prüft: existiert PortalUser mit Email + Status `active` für diesen Tenant? - **Ja:** Token erzeugen, Email senden mit Link `/portal/{tenant}/auth/magic/{token}` (15 Min Lebenszeit, einmalig) - **Nein:** trotzdem „Link versendet" anzeigen (kein User-Enumeration), aber keine Mail senden 4. Endkunde klickt Link → Token-Validierung → Session erzeugt → Redirect zu `/portal/{tenant}/` **Rate-Limits:** - Pro Email: max. 3 Magic-Link-Anfragen / 15 Min - Pro IP: max. 10 / Stunde - Captcha (hCaptcha) ab 3. Anfrage in Folge **Klartext-Hinweise:** - Token abgelaufen: *„Der Link ist abgelaufen. [Neuen Link anfordern]"* - Token bereits genutzt: *„Dieser Link wurde bereits verwendet. [Neuen Link anfordern]"* - Email nicht zugestellt: *„Email nicht angekommen? Prüfe Spam-Ordner oder kontaktiere [Support-Email]."* ### C.2 — Email + Passwort (optional) - Endkunde kann beim Setup oder in Settings ein Pwd setzen - Pwd-Anforderungen analog M27 B.1 (NIST: 12 Zeichen min., HIBP-Check, Bcrypt Cost 12) - Login mit Email + Pwd → Session erzeugt - **Kein 2FA-Pflicht** in P1 für PortalUser - Rate-Limit: 5 Fehlversuche / 15 Min → 15 Min Lockout pro Email ### C.3 — Erst-Login-Setup (`/portal/{tenant}/setup/{token}`) **Flow:** 1. TenantUser legt PortalUser an + verschickt Setup-Einladung → System erzeugt `PortalUserRegistration` mit 7-Tage-Setup-Token 2. Endkunde klickt Link → Setup-Page lädt mit: - Begrüßungs-Klartext (Tenant-Welcome-Message) - Vorausgefüllte Email (read-only) - Vor-/Nachname (vorausgefüllt, editierbar) - Telefon (optional) - Sprache (Default DE) - Pwd-Setzen-Felder (mit Live-Validation und HIBP-Check) - Pwd-Skip-Option (*„Lieber per Magic-Link einloggen"* — Pwd kann später jederzeit gesetzt werden) - DSGVO-Klartext + Akzeptanz-Checkbox (Pflicht) - Marketing-Opt-In (optional) 3. Submit → PortalUser-Status auf `active`, Setup-Token verbraucht, Session erzeugt, Redirect zu `/portal/{tenant}/` **Token abgelaufen oder bereits genutzt:** Klartext + Funktion „Neuen Link bei [Tenant] anfordern" → erzeugt Support-Email. ### C.4 — Pwd-Reset (`/portal/{tenant}/forgot-password`) - Email eingeben → Magic-Link mit `purpose=password_reset` (1 Std) - Klick → neue Pwd setzen → alle aktiven Sessions invalidiert - Klartext analog C.1 (kein User-Enumeration) ### C.5 — Email-Verification - Beim Setup: Email gilt als verifiziert, weil Magic-Link erfolgreich war - Beim Email-Ändern in Settings: Verification-Token an neue Email, alter Email-Adresse Klartext-Hinweis-Mail - Bis Verification: alte Email bleibt aktiv ### C.6 — Session-Management - Server-Side-Sessions in Postgres (analog M27 B.5) - HTTP-only, Secure, SameSite=Lax Cookie - Cookie-Name **eindeutig vom TenantUser-Cookie getrennt** (`hg_portal_session` vs. `hg_session`) — verhindert Cross-Class-Verwechslung - 30 Tage Sliding-Window - Inaktivitäts-Timeout: 7 Tage ohne Aktivität → Re-Login - Bei Pwd-Änderung: alle Sessions invalidiert - Bei `PortalUser.status = disabled | deleted`: alle Sessions invalidiert - Session-Übersicht in `/portal/{tenant}/settings/`: Liste aktiver Sessions mit Logout-Funktion + globaler „Von allen Geräten abmelden" ### C.7 — Permission-Check pro Request - Middleware prüft auf jeder `/portal/{tenant}/...`-Route: - Existiert Session? - Ist Session valid + nicht revoked + nicht expired? - Ist `PortalUser.status = active`? - Ist `Portal.enabled = true`? - Ist `Tenant.status` nicht `suspended | deleted`? - Bei `tenant.status = frozen`: Read-Only-Modus (analog M27 A.5 — Login + Read OK, Upload + Form-Submit gesperrt mit Klartext) - Resource-Access-Check: bei Project-Detail-Aufruf wird `CustomerPortalProjectAccess` geprüft, bei File-Aufruf zusätzlich `CustomerPortalProjectDocument` - Bei fehlender Permission: 404 (nicht 403 — keine Existenz-Offenlegung gegenüber Endkunde) --- ## Block D — Portal-Endkunden-Views ### D.1 — Portal-Dashboard (`/portal/{tenant}/`) **Zu zeigende Daten:** - Begrüßung mit Vorname - Übersicht der eigenen Projekte (Anzahl aktiv, Anzahl abgeschlossen) - Liste der **letzten Status-Änderungen** über alle eigenen Projekte (chronologisch) - Liste der **zuletzt freigegebenen Dokumente** - Schnell-Aktionen (Funktionen): Projekt anschauen, Datei hochladen, Reklamation melden - Support-Kontakt (Tenant-Support-Email + ggf. Telefon aus PortalConfiguration) **Benötigte UI-Elemente:** - Anzeige der oben genannten Daten in sektionierter Form - Quick-Action-Funktionen für die genannten Schnell-Aktionen - Logout-Funktion erreichbar - Branding-Komponente (Logo + Primärfarbe aus PortalConfiguration) **Permissions:** - Erfordert aktive Portal-Session - Daten-Filter automatisch auf eigene Projekte (über `CustomerPortalProjectAccess`) **Klartext-Hinweise:** - Keine Projekte zugewiesen: *„Aktuell ist Ihnen kein Projekt zugewiesen. Bei Fragen kontaktieren Sie [Support-Email]."* ### D.2 — Projekte-Liste (`/portal/{tenant}/projects`) **Zu zeigende Daten pro Project:** - Project-Titel + Project-Nummer - **Aktuelle Phase** (mit Tenant-konfiguriertem Klartext-Label aus `stage_display_labels`) - Phasen-Fortschritt (visuelle Komponente — nur sichtbare Stages laut `visible_pipeline_stages`) - Zeitraum (Start + erwartetes Ende) - Baustellen-Adresse-Kurzform - Letzte Status-Änderung (Datum) - Anzahl freigegebener Dokumente - Verantwortlicher Ansprechpartner (PL aus M4 mit Email + Telefon) **Benötigte UI-Elemente:** - Listen- oder Karten-Anzeige (Designer entscheidet) - Filter-Funktion: aktiv / abgeschlossen / alle - Sortier-Funktion: zuletzt aktualisiert / Start-Datum / Phase - Such-Funktion (Volltext über Titel + Adresse) - Klick auf Eintrag → Project-Detail **Permissions / Datenfilter:** - Server-side gefiltert nach `CustomerPortalProjectAccess.portal_user_id = self` - Nur Einträge mit `revoked_at IS NULL` - Bei `access_level = read_status_only`: keine Detail-Verlinkung, nur Phase + Phasen-Fortschritt **Klartext-Hinweise:** - Leere Liste: *„Sie haben aktuell keinen Projekt-Zugang. Bei Fragen kontaktieren Sie [Support]."* ### D.3 — Project-Detail (`/portal/{tenant}/projects/:id`) **Zu zeigende Daten:** - Project-Titel + Project-Nummer - Aktuelle Phase (Klartext-Label) + Phasen-Fortschritt (sichtbare Stages) - Zeitraum + Baustellen-Adresse - PL als Ansprechpartner mit Klick-zum-Mailen-Funktion - **Status-Historie** (chronologisch, nur sichtbare Phasen-Wechsel) - **Freigegebene Dokumente** (Liste mit Download-Funktion + Datum + Doc-Typ) - **Mängel aus Acceptance** (falls vorhanden + freigegeben) - **Form-Submissions des Endkunden zu diesem Projekt** (eigene Reklamationen etc.) - Upload-Funktion für eigene Files (siehe D.5) - Reklamations-Form-Funktion (über M5 Form mit Project-Vorausfüllung) **Benötigte UI-Elemente:** - Sektionierte Anzeige der oben genannten Daten - Visuelle Phasen-Komponente (nur freigegebene Stages, Zwischenphasen werden zusammengefasst angezeigt — z.B. wenn 5 von 8 Stages sichtbar sind, dann 5 Schritte) - Dokument-Liste mit Download-Funktion pro Eintrag - Upload-Funktion (Drag-&-Drop + File-Picker, Mobile-Kamera-Direkt-Upload) - Map-Anzeige der Baustellen-Adresse (optional, falls Tenant-Maps-Integration aktiv) - Klartext-Anzeige zu Doc-Releases (*„Neu freigegeben am [Datum]"*) **Operationen:** - Dokumente runterladen (Audit-Log-Eintrag bei jedem Download) - File hochladen (siehe D.5) - Reklamation/Service-Anfrage absenden (siehe D.6) - Email an PL schreiben (öffnet Mail-Client mit `mailto:` — keine portal-eigene Compose in P1) **Permissions / Datenfilter:** - Resource-Check via `CustomerPortalProjectAccess` (404 bei fehlendem Zugang) - Nur Daten der `visible_pipeline_stages`-Liste - Nur Files mit aktivem `CustomerPortalProjectDocument`-Eintrag (`revoked_at IS NULL`) - Bei `access_level = read_status_only`: kein Detail-View, Redirect mit Klartext **Klartext-Hinweise:** - Project archiviert/abgeschlossen: Banner *„Dieses Projekt ist abgeschlossen. Bei Service-Anfragen melden Sie sich gerne — [Service-Funktion]."* (Portal bleibt nach Abschluss offen für Wartung/Service) - Project gelöscht/Zugang entzogen: 404 mit generischem *„Projekt nicht gefunden"* ### D.4 — Dokumente-Cross-View (`/portal/{tenant}/documents`) **Zu zeigende Daten:** - Liste aller freigegebenen Dokumente über alle eigenen Projekte - Pro Eintrag: Datei-Name (oder `customer_visible_filename`), Doc-Typ, Project-Zuordnung, Freigabe-Datum, Größe **Benötigte UI-Elemente:** - Tabellarische Liste - Filter-Funktion: Project, Doc-Typ, Zeitraum - Such-Funktion - Sortier-Funktion: Datum / Name / Project - Download-Funktion pro Eintrag - Bulk-Download (ZIP) — Phase 2 **Permissions / Datenfilter:** - Filter über Join `CustomerPortalProjectAccess` × `CustomerPortalProjectDocument` ### D.5 — Upload-Funktion (`/portal/{tenant}/upload`) **Zu zeigende Daten:** - Project-Auswahl (Dropdown der eigenen Projekte mit `read_full`-Access) - Optional: Kategorie-Auswahl (Reklamation, Foto, Anhang, Sonstiges) - Optional: Beschreibung (Freitext) - Datei-Auswahl **Benötigte UI-Elemente:** - Project-Selektor - Kategorie-Selektor - Beschreibungs-Feld - File-Picker + Drag-&-Drop-Zone - Mobile-Kamera-Direkt-Funktion - Multi-File-Upload (max. 10 gleichzeitig) - Progress-Indikatoren pro Datei - Klartext-Hinweis nach erfolgreichem Upload **Operationen:** - Datei wird in M23-Storage geschrieben (Pfad `tenants/{tenantId}/projects/{projectId}/portal-uploads/...`) - Eintrag in M23 mit Quelle = `customer_portal_upload` + `uploaded_by_portal_user_id` - Eintrag in Project-Activity-Stream mit Klartext: *„Kunde [Name] hat Datei [Filename] hochgeladen"* - Trigger M17: `portal.kunde_uploaded_file` (Automation-Engine) - Notification an PL via M22 (Push + Email-Digest) **Restriktionen:** - Max. 50 MB pro Datei (Tenant-konfigurierbar) - Erlaubte Mime-Types: Bilder (jpg/png/webp/heic), PDF, Office-Docs, Audio (m4a/mp3 für Sprach-Notiz) - Tenant-Admin kann pro Project Upload sperren - Bei `Tenant.status = frozen`: Upload-Funktion gesperrt mit Klartext **Klartext-Hinweise:** - Upload erfolgreich: *„Datei [Filename] wurde an [Tenant-Name] gesendet. Sie erhalten eine Bestätigung per Email."* - Datei zu groß: *„Die Datei ist größer als das erlaubte Maximum von 50 MB. Bitte komprimieren oder in mehrere Dateien aufteilen."* - Mime-Type nicht erlaubt: *„Dieser Dateityp ist nicht erlaubt. Erlaubte Typen: [Liste]."* - Project-Auswahl leer: *„Aktuell ist kein Projekt für Uploads verfügbar."* ### D.6 — Forms (Reklamation, Service-Anfrage) - Tenant-Admin definiert Forms via M5 (Subtyp `portal_form`) - Endkunde ruft `/portal/{tenant}/forms/:formSlug` auf - Form-Submission wird mit `portal_user_id` + ggf. `project_id` versehen - Trigger M17: `portal.kunde_replied` - Eintrag im Project-Activity-Stream ### D.7 — Settings (`/portal/{tenant}/settings/`) **Profil:** - Vor-/Nachname editieren - Telefon editieren - Sprache wechseln - Email ändern (mit Verification an neue + Hinweis-Mail an alte) **Sicherheit:** - Pwd setzen / ändern (HIBP-Check) - Pwd entfernen (Magic-Link-Only-Modus) - Aktive Sessions verwalten (Logout pro Session, Global-Logout) **Notifications:** - Email-Präferenzen pro Event-Typ (Stage-Wechsel / Doc-Freigabe / Upload-Bestätigung) - Marketing-Opt-In-Toggle (NUR falls Tenant Marketing-Mails versendet) **Account:** - Daten-Export (DSGVO — JSON-Download aller eigenen Daten, siehe Block J) - Account-Löschung (siehe Block J) --- ## Block E — Tenant-Admin-Konfiguration ### E.1 — Portal-Konfiguration (`/{tenant}/admin/portal/`) **Zu zeigende Daten:** - Portal-Status (aktiv / deaktiviert) - Portal-Name + Slug (Slug read-only in P1) - Phasen-Sichtbarkeit pro Pipeline (welche Stages sieht Endkunde) - Stage-Klartext-Labels (Override für Endkunden-Sicht) - Doc-Typen mit Auto-Freigabe - Auto-Status-Mail-Settings pro Stage-Wechsel-Event - Branding (P1: nutzt Tenant-Branding aus M27; Portal-eigenes Branding ist P2) - Welcome-Message-Default - Support-Email + Telefon - Pflicht-Links (Impressum, Datenschutz) **Benötigte UI-Elemente:** - Sektion „Phasen-Sichtbarkeit pro Pipeline": - Pipeline-Selektor - Pro Stage Toggle: sichtbar im Portal ja/nein - Pro Stage Text-Input für Klartext-Label-Override (Platzhalter zeigt Original-Stage-Name) - Klartext: *„Aktivieren Sie nur die Phasen, die für den Kunden relevant sind. Interne Phasen wie ‚Disposition' bleiben verborgen."* - Sektion „Doc-Typen-Auto-Freigabe": - Multi-Select-Toggle pro Doc-Typ aus Tenant-Doc-Type-Liste (z.B. Angebot, Rechnung, Acceptance-PDF, Bauplan) - Klartext: *„Beim Erzeugen oder Hochladen von Dokumenten dieses Typs wird der Kunde automatisch Zugriff erhalten."* - Sektion „Auto-Status-Mails": - Pro Pipeline + Stage-Wechsel-Event Toggle „Mail an Kunde versenden" - Auto-Mail-Template-Auswahl - Klartext-Beispiel-Vorschau mit Platzhaltern - Sektion „Pflicht-Links": Eingaben für Impressum-URL, Datenschutz-URL, AGB-URL (Tenant-Default oder eigene URLs) **Operationen:** - Portal aktivieren / deaktivieren (mit Warnung: alle PortalUser können nicht mehr einloggen) - Phasen-Sichtbarkeit speichern - Auto-Mail-Settings speichern - Branding-Override (P2) ### E.2 — PortalUser-Verwaltung (`/{tenant}/admin/portal/users`) **Zu zeigende Daten pro PortalUser:** - Avatar / Initialen - Name - Email - Status (`pending_setup | active | disabled | deleted`) - Anzahl zugewiesener Projekte - Letzter Login - Verknüpfter Contact (falls vorhanden) - Erstellt-Datum + Erstellt-von **Benötigte UI-Elemente:** - Tabellarische Listen-Anzeige - Filter: Status, Erstellt-Zeitraum, mit/ohne Contact-Verknüpfung - Such-Funktion (Email, Name) - Sortier-Funktion - Bulk-Auswahl - Bulk-Actions: Deaktivieren / Aktivieren / Setup-Mail erneut senden / Hard-Delete (mit DSGVO-Hinweis) - Funktion „Neuen PortalUser anlegen" (Modal) **Operationen:** - PortalUser anlegen (siehe F.1) - Bestehenden PortalUser editieren - Setup-Mail erneut senden (bei `pending_setup` mit abgelaufenem Token) - Pwd-Reset-Mail erzwingen - Deaktivieren (Status `disabled`, alle Sessions invalidiert) - Reaktivieren - Hard-Delete (DSGVO-Workflow) - Liste der Project-Accesses anzeigen + revoke ### E.3 — PortalUser-Detail (`/{tenant}/admin/portal/users/:id`) **Zu zeigende Daten:** - Stammdaten (Email, Name, Telefon, Sprache, Status, Verknüpfter Contact) - Account-Status (Pwd gesetzt? Email verifiziert? Letzter Login? Letzter Pwd-Reset?) - Project-Access-Liste (alle CustomerPortalProjectAccess + access_level) - Doc-Release-Liste (Cross-Project) - Aktive Sessions - Login-Historie (letzte 30 Logins mit IP + Datum) - Upload-Historie (alle vom PortalUser hochgeladenen Files) - Form-Submissions des PortalUsers - Audit-Log (Anlage, Statuswechsel, Zugang-Änderungen) **Operationen:** - Stammdaten editieren - Project-Access hinzufügen (Project-Auto-Complete + access_level wählen) - Project-Access entfernen / `access_level` ändern - Sessions invalidieren - Pwd-Reset triggern - Mit Contact verknüpfen / Verknüpfung lösen - Status setzen (Deaktivieren / Reaktivieren / Hard-Delete) - Setup-Mail erneut senden - Daten-Export (DSGVO — JSON aller Daten dieses PortalUsers) ### E.4 — Cross-Project-Access-Übersicht (`/{tenant}/admin/portal/access`) **Zu zeigende Daten:** - Matrix-/Listen-Anzeige: PortalUser × Project mit access_level - Filter: Project (oder Pipeline), PortalUser, access_level **Benötigte UI-Elemente:** - Listen- oder Tabellen-Anzeige - Filter-Funktionen - Bulk-Actions: Access entziehen / access_level ändern - Funktion „Access für Project an PortalUser geben" (Modal mit beiden Selektoren) ### E.5 — Auto-Status-Mail-Templates (`/{tenant}/admin/portal/email-templates`) **Zu zeigende Daten pro Template:** - Template-Kind (`setup_invitation | login_magic_link | password_reset | stage_changed | document_released | upload_received`) - Subject (mit Platzhalter-Vorschau) - Body (Markdown mit Platzhalter-Vorschau) - From-Address - Aktiv ja/nein - Letzte Bearbeitung **Operationen:** - Editieren (Subject + Body) mit Platzhalter-Hilfe (`{{customer_name}}`, `{{project_title}}`, `{{stage_name}}`, `{{stage_klartext_label}}`, `{{tenant_name}}`, `{{support_email}}`, `{{magic_link_url}}`, `{{document_name}}`, `{{document_link}}`) - Test-Mail an eigene Adresse senden - Auf Default zurücksetzen - Aktivieren / Deaktivieren ### E.6 — Portal-Audit (`/{tenant}/admin/portal/audit`) **Zu zeigende Daten:** - Chronologische Liste aller Portal-Events - Event-Typen: Login, Logout, Pwd-geändert, Doc-runtergeladen, File-hochgeladen, Project-Access-Änderung, Status-Mail-versendet - Pro Eintrag: PortalUser, Event, IP, User-Agent, Datum, ggf. Project/Doc-Bezug **Benötigte UI-Elemente:** - Filter: PortalUser, Event-Typ, Zeitraum, Project - Such-Funktion - Export-Funktion (CSV, gefilterte Auswahl) --- ## Block F — PortalUser-Lifecycle ### F.1 — Anlage / Einladung **Drei Wege:** **(A) Manuell aus PortalUser-Verwaltung** (`/{tenant}/admin/portal/users`): 1. TenantUser klickt „Neuen PortalUser anlegen" 2. Modal-Eingaben: Email (Pflicht), Vor-/Nachname (Pflicht), Sprache, optional Verknüpfung mit existierendem Contact (Auto-Complete), optional Project-Access-Liste, persönliche Welcome-Message 3. Submit → PortalUser angelegt mit Status `pending_setup`, Setup-Mail mit 7-Tage-Token versendet **(B) Aus Contact-Detail** (M1): 1. TenantUser im Contact-Detail klickt „Portal-Zugang einladen" 2. Modal vorausgefüllt mit Contact-Daten + Auto-Verknüpfung 3. Optional: Project-Access aus Contact-Projekten vorausgewählt **(C) Aus Project-Detail** (M4): 1. TenantUser im Project klickt „Customer-Portal-Zugang einladen" 2. Modal mit Auto-Vorbelegung aus `Project.contact` (falls Contact verknüpft) 3. `CustomerPortalProjectAccess` automatisch mit diesem Project erzeugt **(D) Aus Deal-Detail** (M3, ab Sales-Phase): 1. TenantUser aktiviert „Portal-Zugang ab Sales-Phase" → PortalUser mit Sales-Deal-Access 2. Endkunde sieht Deal-Phase im Portal (gegated über `deals.read_via_portal`-Toggle in PortalConfiguration) **Edge-Cases:** - Email bereits existierender PortalUser im selben Portal: Klartext *„[Name] ist bereits PortalUser. Soll der existierende User Zugang zu diesem Project erhalten? [Bestehenden nutzen] [Abbrechen]"* - Email bereits TenantUser: Erlaubt — getrennte Auth-Klassen, keine Verwechslung möglich (siehe Architektur-Hinweis) - Setup-Token abgelaufen: TenantUser kann „Setup-Mail erneut senden" ### F.2 — Setup-Flow Siehe C.3. ### F.3 — Pwd-Reset - Endkunde-initiiert via `/portal/{tenant}/forgot-password` (siehe C.4) - Tenant-initiiert: TenantUser im PortalUser-Detail klickt „Pwd-Reset-Mail versenden" → Magic-Link mit `purpose=password_reset` ### F.4 — Deaktivierung / Reaktivierung - Tenant-Admin setzt Status `disabled` → alle Sessions invalidiert, Login gesperrt mit Klartext - Reaktivierung: Status zurück auf `active`, kein neuer Setup-Flow nötig ### F.5 — Entfernen / Hard-Delete - Hard-Delete: PortalUser-Status `deleted`, PII-Felder anonymisiert (`[deleted-{userId}]`) - Sessions, Magic-Tokens, Setup-Tokens entfernt - `CustomerPortalProjectAccess` entfernt - Form-Submissions, Uploads bleiben (mit anonymisiertem User-Bezug — Audit-Trail) - Audit-Eintrag mit User-ID + Lösch-Datum - DSGVO-Workflow analog M35 (siehe Block J) ### F.6 — Wenn Portal-Zugang nach Auftrag-Abschluss bleibt - Default: PortalUser bleibt **aktiv** auch wenn alle Projekte abgeschlossen sind - Service/Wartungs-Anfragen weiterhin möglich - Tenant-Admin kann manuell deaktivieren oder Auto-Deaktivierung-Regel definieren („nach 365 Tagen ohne Login deaktivieren" — Phase 2) --- ## Block G — Auto-Status-Mails bei Phasenwechsel ### Auslöse-Logik - Trigger: `project.stage_changed`-Event (M4) - Bedingungen: - `PortalConfiguration.auto_status_mail_enabled` für diese Stage = true - Neue Stage in `visible_pipeline_stages` enthalten - PortalUser hat aktiven `CustomerPortalProjectAccess` mit `access_level != revoked` - PortalUser hat Email-Notification für `stage_changed` aktiv (Default: an) - `Tenant.status != frozen` (in `frozen` keine Outbound-Mails — analog M27) - Mail-Template: `PortalEmailTemplate` mit `kind = stage_changed` - Versand über M9 verbundene Sending-Domain (Default Tenant-Default-Adresse) ### Mail-Inhalte - Subject mit Platzhaltern (z.B. *„Update zu Ihrem Projekt {{project_title}}: {{stage_klartext_label}}"*) - Body mit Klartext-Beschreibung der neuen Phase + Magic-Link zur direkten Project-Detail-Page - Tenant-Branding (Logo + Farbe aus PortalConfiguration / Tenant-Default) - Footer mit Impressum-Link + Notification-Settings-Link ### Edge-Cases - Mehrere PortalUser pro Project: Mail an alle aktiven mit Access - Stage-Wechsel rückwärts (Reverse): Mail nur wenn `stage_klartext_label` sich ändert (sonst stumm — kein Spam) - Schneller Mehrfach-Wechsel innerhalb 5 Min: Debounce, nur letzte Stage gemailt - Mail-Bounce: Eintrag im Portal-Audit + Notification an verantwortlichen TenantUser ### Doc-Released-Mail - Trigger: `CustomerPortalProjectDocument` neu angelegt (manuell oder auto) - Bedingung: PortalUser-Notification für `document_released` aktiv - Template `kind = document_released` - Debounce: bei Bulk-Release (>5 Files in 1 Min) eine Sammel-Mail mit Liste ### Upload-Received-Mail - Trigger: PortalUser hat erfolgreich File hochgeladen - Empfänger: PortalUser (Bestätigung) + verantwortlicher TenantUser (Info) - Template `kind = upload_received` --- ## Block H — Integration mit anderen Modulen ### M1 CRM - `PortalUser.linked_contact_id` verknüpft mit Contact - Im Contact-Detail: Sektion „Portal-Zugang" - Activity-Stream des Contacts erhält Portal-Events (Login, Upload, Form-Submission) als Activity-Typ `portal_event` mit `actor_kind = portal_user` ### M3 Sales-Pipeline (Deals) - Optional Portal-Zugang ab Lead/Deal-Phase (für Pre-Sales-Transparenz) - Tenant-Admin-Toggle „Sales-Phase im Portal sichtbar" - Endkunde sieht Deal-Stage wenn aktiviert ### M4 Auftragspipeline (Projects) - `CustomerPortalProjectAccess` verknüpft PortalUser mit Project - Project-Detail im Tenant-Workspace zeigt Portal-Sektion (verknüpfte PortalUser, Doc-Freigabe-Toggles) - Acceptance-PDF wird (bei Tenant-Konfiguration) automatisch im Portal freigegeben - Project-Stage-Wechsel triggert Auto-Status-Mail (Block G) - `project.stage_changed` mit visibility-Filter ### M5 Form Builder - Forms mit Subtyp `portal_form` sind im Portal aufrufbar - Form-Submission wird mit `portal_user_id` + ggf. `project_id` versehen - Trigger M17: `portal.kunde_replied` ### M9 Email Inbox / Sending - Portal-Auto-Mails versendet über verbundene Sending-Domain (Tenant-Default) - Bounce-Handling über M9-Bounce-Pipeline - Reply-Adresse zeigt zurück auf Tenant-Inbox (Threading mit M9) ### M17 Automation-Engine **Trigger:** - `portal.user_created` - `portal.user_setup_completed` - `portal.user_logged_in` - `portal.kunde_uploaded_file` - `portal.kunde_replied` (Form-Submission) - `portal.access_granted` - `portal.access_revoked` - `portal.document_released` - `portal.document_downloaded` - `portal.status_mail_sent` **Actions:** - `portal.create-user` (PortalUser anlegen) - `portal.send-setup-invitation` - `portal.grant-project-access` - `portal.revoke-project-access` - `portal.release-document` - `portal.send-status-mail` (manuell triggern) - `portal.disable-user` ### M22 Notifications - Auto-Status-Mails an Endkunde (siehe Block G) - Push/In-App-Notification an verantwortlichen TenantUser bei `portal.kunde_uploaded_file` und `portal.kunde_replied` ### M23 Files - `CustomerPortalProjectDocument` referenziert M23-File - File-Aufruf aus Portal: zusätzlicher Permission-Check + Audit-Eintrag - Upload-Pfad: `tenants/{tenantId}/projects/{projectId}/portal-uploads/{fileId}` - Tenant-File-Detail zeigt Quelle = `customer_portal_upload` ### M27 Auth / Multi-Tenancy - **Getrennte User-Klasse**: `PortalUser` ≠ `TenantUser` - Eigene Cookie-Domäne / Cookie-Name - Eigenes Session-Modell - Eigene Login-Routen - **Keine** Permission-Vermischung (PortalUser kann niemals TenantUser-Permissions erlangen) - RLS-Pattern analog: `tenant_id` auf allen Portal-Tabellen mit Policy - Tenant-Status-Wirkung: `frozen` → Portal read-only; `suspended/deleted` → Portal-Login gesperrt mit Klartext ### M35 DSGVO / Account-Lösch-Workflow - PortalUser-Lösch-Flow analog TenantUser-Flow (Multi-Step + 24h-Reverse-Window) --- ## Block I — Permissions-Anwendung ### I.1 — Tenant-seitige Permissions (TenantUser) | Permission | Erlaubt | |---|---| | `portal.read` | Sehen, welche Endkunden Zugang haben (Liste, Details, Access-Übersicht) | | `portal.manage_users` | PortalUser anlegen / einladen / deaktivieren / reaktivieren / Setup erneut senden | | `portal.manage_access` | Project-Access pro PortalUser hinzufügen/entfernen, `access_level` ändern, Doc-Freigabe pro Project schalten | | `portal.delete_user` | Hard-Delete + DSGVO-Lösch-Workflow auslösen | | `portal.admin` | Portal-Konfiguration (Phasen-Sichtbarkeit, Doc-Auto-Freigabe, Branding, Auto-Mail-Templates), Portal-Audit-Sicht, Portal aktivieren/deaktivieren | **Bundle-Mapping (Variante 2):** | Bundle | Atomare Permissions | |---|---| | `portal.none` | (keine) | | `portal.read` | `portal.read` | | `portal.manage_users` | `portal.read` + `portal.manage_users` | | `portal.manage_access` | obigen + `portal.manage_access` | | `portal.admin` | obigen + `portal.delete_user` + `portal.admin` | **SHK-Template-Default-Rollen:** | Rolle | Portal-Permissions | |---|---| | GF | `portal.admin` | | Vertriebsleiter | `portal.manage_access` (kann Sales-Phase-Zugang freischalten) | | Vertriebler | `portal.read` + `portal.manage_users` (kann Endkunden einladen ab Lead) | | Projektleiter / Bauleiter | `portal.manage_access` (verwaltet Doc-Freigabe + Mail-Settings für eigene Projekte) | | Büro / Backoffice | `portal.manage_access` | | Marketing | `portal.read` | | Monteur | `portal.none` | **Anwendung in Tenant-Routes:** - `/{tenant}/admin/portal/` → `portal.admin` - `/{tenant}/admin/portal/users` → `portal.read` (Liste) + `portal.manage_users` (Mutations) - `/{tenant}/admin/portal/users/:id` → `portal.read` - `/{tenant}/admin/portal/access` → `portal.manage_access` - `/{tenant}/admin/portal/email-templates` → `portal.admin` - `/{tenant}/admin/portal/audit` → `portal.admin` - Project-Detail-Portal-Sektion (Doc-Freigabe-Toggles): `portal.manage_access` + `projects.write` (für dieses Project) - Contact-Detail-Portal-Sektion (Einladung): `portal.manage_users` ### I.2 — Portal-seitige Permissions (PortalUser) PortalUser hat **keine** atomaren Permissions im M27-Stil. Stattdessen wirken implizite Resource-Checks: - **Listen-Filter:** automatisch über `CustomerPortalProjectAccess.portal_user_id = self` - **Detail-Access:** Server prüft pro Request `CustomerPortalProjectAccess` (Project), `CustomerPortalProjectDocument` (File) - **Stage-Sichtbarkeit:** Server filtert Stages nach `PortalConfiguration.visible_pipeline_stages` - **Funktion-Sichtbarkeit:** Upload/Form-Funktionen nur bei `access_level = read_full` sichtbar; bei `read_status_only` nicht sichtbar ### I.3 — Klartext-Fehler - TenantUser ohne `portal.manage_users` versucht Einladen: Funktion nicht sichtbar - TenantUser ohne `portal.admin` versucht Konfiguration: Route nicht erreichbar (404) - PortalUser greift auf Project ohne Access: 404 (keine Existenz-Offenlegung) - PortalUser bei `Tenant.status = frozen` versucht Upload: Klartext *„Aktuell sind keine Uploads möglich. Bei Fragen wenden Sie sich an [Support]."* - PortalUser bei `Tenant.status = suspended/deleted` versucht Login: Klartext *„Dieses Portal ist aktuell nicht erreichbar."* (kein technisches Detail) --- ## Block J — DSGVO / Lösch-Workflow ### J.1 — Datenklassifizierung - **Sensible Daten** (Endkunden-PII): Email, Name, Telefon, IP-Logs, hochgeladene Files, Form-Submissions - **Aufbewahrungspflichten:** Acceptance-PDFs + rechtlich aufbewahrungspflichtige Files bleiben (siehe M4); PortalUser-PII wird bei Löschung anonymisiert, nicht gelöscht, soweit verknüpfte Aufbewahrungspflicht besteht ### J.2 — Endkunde-initiiertes Löschen (`/portal/{tenant}/settings/account-delete`) **Multi-Step-Flow (analog M35):** 1. **Erklärung** — Klartext was passiert (Account weg, Login nicht mehr möglich, Daten anonymisiert, aufbewahrungspflichtige Dokumente bleiben Tenant-seitig) 2. **Identität** — Pwd-Eingabe oder Magic-Link 3. **Final-Klick** mit 3-Sek-Countdown 4. **Bestätigungs-Email** mit 24h-Reverse-Window 5. **Nach 24h:** Hard-Delete-Job läuft ### J.3 — Tenant-initiiertes Löschen - TenantUser mit `portal.delete_user` triggert Lösch-Workflow im PortalUser-Detail - Klartext-Warnung: *„Dies löscht den PortalUser-Account. Hochgeladene Files und Form-Submissions bleiben mit anonymisiertem Bezug für Audit-Pflicht."* - 24h-Reverse-Window - Audit-Eintrag ### J.4 — Daten-Export (DSGVO-Auskunft) - Endkunde in `/portal/{tenant}/settings/`: Funktion „Meine Daten exportieren" → JSON-Download mit allen PortalUser-bezogenen Daten (Profil, Sessions-Historie, Project-Access-Liste, Doc-Releases, Uploads, Form-Submissions) - Tenant-seitig: TenantUser mit `portal.read` kann Export für PortalUser anfordern (z.B. Auskunfts-Anfrage) ### J.5 — Tenant-Lifecycle-Wirkung - `Tenant.status = deletion_pending`: Portal-Login bleibt 30 Tage offen mit Banner *„Dieser Anbieter hat sein Konto gekündigt. Daten werden am [Datum] gelöscht."* - `Tenant.status = deleted`: Portal nicht mehr erreichbar; alle PortalUser-Daten via Tenant-Lösch-Job anonymisiert/gelöscht --- ## Block K — Klartext-Hinweise / -Fehler (Sammlung) **Login-Page:** - *„Wir haben Ihnen einen Login-Link an [Email] gesendet. Der Link ist 15 Minuten gültig."* - *„Probleme beim Login? Kontaktieren Sie [Support-Email]."* **Setup-Page:** - *„Willkommen bei [Tenant-Name]. Bitte vervollständigen Sie Ihr Profil, um auf Ihre Projekte zuzugreifen."* - *„Sie können später jederzeit ein Passwort setzen oder per Magic-Link einloggen."* **Project-Detail (leer):** - *„Aktuelle Phase: [Phase]. Es gibt noch keine freigegebenen Dokumente. Sie werden per Email informiert, sobald sich der Status ändert."* **Doc-Download:** - *„Datei wird heruntergeladen. Diese ist nur für Sie und Ihr Projektteam bestimmt."* **Upload-Funktion:** - *„Maximal 10 Dateien gleichzeitig, je max. 50 MB."* - *„Wir benachrichtigen [Tenant-Name] automatisch über Ihren Upload."* **Tenant frozen:** - *„Aktuell sind keine schreibenden Aktionen möglich. Bei Fragen wenden Sie sich an [Support]."* **Permissions-Block (Tenant-Seite):** - *„Hierfür benötigst du erweiterte Portal-Berechtigungen. Tenant-Admin kontaktieren."* **Konfigurations-Hinweise:** - Phasen-Sichtbarkeit leer: *„Aktuell sieht der Endkunde keine Phasen. Aktivieren Sie mind. eine Phase pro Pipeline."* - Auto-Mail-Templates inaktiv: *„Stage-Wechsel-Mails sind aktuell deaktiviert. Endkunden werden nicht automatisch über Phasenwechsel informiert."* --- ## Block L — Phase 2 / spätere Features - **Bidirektionale Kommunikation** (Chat zwischen Kunde und Firma im Portal-Kontext, separat von M13 Team-Chat) - **Blog/CMS im Portal** (Tenant kann redaktionelle Inhalte für Endkunden veröffentlichen — Wartungs-Tipps, News) - **Mehrere Portale pro Tenant** mit unterschiedlichem Branding/Slug (z.B. Privatkunden vs. Bauträger) - **Portal-eigenes Branding** (eigenes Logo + Farben + Custom-Domain `portal.geerkens.de`) - **PortalSubscription** (Wartungs-Abos, Service-Pakete im Portal abschließbar mit Legacy-Provider-Integration) - **Multi-Faktor-Auth für PortalUser** (TOTP-optional) - **In-App-Notifications im Portal** (statt nur Email) - **Bulk-Download** (ZIP) aller freigegebenen Dokumente - **Push-Notifications** an Endkunden (über installierbare PWA) - **Auto-Deaktivierung** von PortalUser nach X Tagen ohne Login (konfigurierbar) - **Direkte Mail-Compose** im Portal (statt nur `mailto:`) - **Endkunden-Empfehlungs-/Referral-Programm** - **Portal-Analytics** für Tenant (welche Endkunden sind aktiv, welche Docs werden geöffnet) --- ## Architektur-Vorschriften (Querschnitt) - **LP-1, AV #2 — User-Klassen-Trennung:** PortalUser strikt getrennt von TenantUser, eigene Auth-Schicht, eigene Cookies, eigene Routes — verhindert Permission-Eskalation - **LP-2 — Mobile-Ready:** Portal-Endkunden-Views (Project-Detail, Upload, Forms) mobile-first; Tenant-Admin-Konfiguration desktop-fokussiert - **LP-3, AV #3 — Branchen-Templates deklarativ:** SHK-Default-PortalConfiguration (Phasen-Sichtbarkeit + Auto-Doc-Freigabe + Mail-Templates) als Seeding - **LP-7 — Konsolidierung:** Customer-Portal löst externe Tools wie Plan-Radar/Trello-Kunden-Boards ab - **LP-9 — Spec-Stil:** UI-Anforderungen als Liste, kein Layout - **LP-10, AV #1 — Klartext-Diagnostik:** alle Endkunden-Texte freundlich, lösungsorientiert, ohne technische Details - **LP-13 — EU-Stack:** Portal-Daten in EU-Storage, Auto-Mails über EU-Sending-Domain - **AV #5 — Permissions-aware-Default:** alle Listen automatisch nach `CustomerPortalProjectAccess` gefiltert - **AV #6 — Audit-Trail-Default:** alle PortalUser-Aktionen (Login, Download, Upload, Doc-Release-Änderung) in Portal-Audit - **AV #20 — Action-Boundary für KI:** KI darf keine Portal-Access-Änderungen direkt vornehmen, nur User-Bestätigt --- ## Detail-Spec-Status: DRAFT Erste vollständige Detail-Spec für Modul 15. **Vor Bau:** Verifizierung mit Noah (zusammen mit Pflichtenheft-Sweep + Geerkens-Launch-Anforderungen). **Offene Detail-Punkte (nicht-blockierend, beim Bau zu klären):** - Konkrete SHK-Default-Phasen-Sichtbarkeit pro Pipeline (welche Stages aus M4-Templates sind kunden-relevant) - Konkrete SHK-Default-Doc-Auto-Freigabe-Liste (Angebot/Rechnung/Acceptance-PDF/Bauplan?) - Konkrete SHK-Default-Auto-Mail-Templates (Subject + Body für `setup_invitation`, `stage_changed`, `document_released`) - Konkrete Upload-Restriktionen (Max-Größe pro File, erlaubte Mime-Types final) - Konkrete Email-Bounce-Handling-Strategie (welcher TenantUser wird informiert) - Konkrete Storage-Pfad-Struktur für Portal-Uploads (Folder-Konvention) - Konkrete Branding-Vererbung Phase 1 (Tenant-Logo + Farbe in welcher Form auf Portal-Seiten) - Subframe-UI-Designs (separat) **Verweise auf abhängige Module:** - M27 (Auth-Pattern + Tenant-Lifecycle-Wirkung) - M4 (Project-Stage-Wechsel-Trigger + Acceptance-PDF-Auto-Freigabe) - M1 (Contact-Verknüpfung + Activity-Stream) - M3 (Sales-Phase-Sichtbarkeit ab Lead/Deal) - M5 (Portal-Forms) - M9 (Sending-Domain für Auto-Mails) - M17 (Automation-Trigger + -Actions) - M22 (Notifications an TenantUser bei Portal-Events) - M23 (Files-Storage + Doc-Freigabe-Architektur) - M35 (DSGVO-Lösch-Workflow)