1046 lines
46 KiB
Markdown
1046 lines
46 KiB
Markdown
---
|
||
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 Stripe-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)
|