Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M15-customer-portal.md
T

21 KiB
Raw Blame History

Boilerplate-Abgleich: M15 — Customer-Portal (Endkunden-Login)

Feld Wert
Modul-ID M15
Name Customer-Portal (Endkunden-Login)
Milestones M141 (Auth), M142 (Projekt-Sicht + Status-Mails), M143 (Datei-Upload + Reklamations-Forms), M144 (Subunternehmer-Zugang), M145 (Skalierung / Service-Inbox), M146 (Lebensdauer + DSGVO + Konfig)
Block Block 6 — Spezial-Module (Pflichtenheft block6.md §15)
Reuse-Level low
Stand Boilerplate read-only verifiziert (/Users/raffaelsheikh/Documents/GitHub/boilerplate)

Verdict in einem Satz

Der namensgleiche Boilerplate-Baustein (prisma/schema/portals.prisma + apps/web/app/modules/portals + apps/web/app/routes/app.$tenant/__portals) ist ein White-Label-SaaS-Marketing-Portal (Subdomain-Hosting, öffentliche Signup-Seiten, Stripe-Connect-Abos, SEO, Analytics) und deckt das HiveGrid-Customer-Portal (Endkunden-Sicht auf eigene Projekte/Dokumente/Status) fachlich nicht ab. Nutzbar ist fast ausschließlich die Querschnitt-Hülle (Auth-Primitiven, Storage, Mail, Notifications, Audit, DSGVO-Export, i18n, Outbox, Cron) — die fachliche Datenebene und alle Endkunden-Views sind neu zu bauen.


WICHTIG: Eignung von portals.prisma (vom Task explizit zu prüfen)

Befund: nicht geeignet für 1:1-Übernahme, allenfalls als Namens-/Struktur-Vorlage.

Verifiziert in /Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/portals.prisma (12 Modelle):

  • Portal ist Subdomain-gehostet (subdomain @unique, optional domain), trägt SEO-Felder (seoTitle/seoDescription/seoImage/seoKeywords...), Analytics-Toggles (Simple/Plausible/Google), eigenen stripeAccountId (Stripe Connect) und White-Label-Branding. Es gibt kein tenantId @unique (P1 verlangt ein Default-Portal pro Tenant), kein enabled/archived_at/is_default/slug=portal.
  • PortalUser hat passwordHash als Pflichtfeld (HiveGrid: nullable für Magic-Link-Only), OAuth-Felder githubId/googleId (gegen EU-Stack AGENTS.md — Apple/Google/Microsoft-Login in P1 verboten), kein status-Enum (pending_setup|active|disabled|deleted), kein linked_contact_id/linked_company_id, kein last_login_at, kein language-Konzept passend zu Auto-Mails.
  • PortalUserRegistration existiert (Token + Email + Name + Company), kommt der HiveGrid-PortalUserRegistration strukturell am nächsten — aber an die SaaS-Signup-Logik (selectedSubscriptionPriceId) gekoppelt.
  • Komplett fehlend in portals.prisma: CustomerPortalAccount, CustomerPortalMagicLinkToken (mit purpose-Enum), CustomerPortalSession (server-side Postgres-Session für PortalUser), CustomerPortalProjectAccess, CustomerPortalProjectDocument, PortalConfiguration (Phasen-Sichtbarkeit/Doc-Auto-Freigabe/Pflicht-Links), PortalEmailTemplate. Es gibt kein Session-Prisma-Modell für PortalUser im gesamten Schema (grep "model Session" prisma/schema/ ist leer).
  • 6 der 12 Modelle sind reines Portal-Abo-Subsystem (PortalSubscriptionProduct/Price/Feature, PortalUserSubscription(Product)(Price), PortalCheckoutSessionStatus) — entspricht direkt dem Anti-Listen-Punkt 15.8.6 (keine Wartungs-Abos/Service-Pakete im Portal in P1) und ist für M15-P1 nicht zu verwenden.

Service-Layer apps/web/app/modules/portals/services/ enthält ausschließlich Portal.server.ts, PortalPricing.server.ts, PortalStripe.server.ts, PortalSubscription.server.ts, StripeConnect.server.ts — keinen PortalUser-Login-/Magic-Link-/Session-Flow. Die Routen apps/web/app/routes/app.$tenant/__portals/** sind Tenant-Admin-CRUD über das Portal (Pages, Pricing, Domains, Users-Verwaltung), kein Endkunden-Frontend mit eigener Auth.

Empfehlung: portals.prisma und das portals-Web-Modul NICHT erweitern. HiveGrid-Portal-Modelle neu in prisma/schema/app.prisma (vorgesehener Platzhalter) als CustomerPortal*-Familie anlegen, um Namenskollision mit dem bestehenden Portal/PortalUser zu vermeiden. Das bestehende Schema bleibt als Struktur-/Feld-Vorlage für PortalConfiguration (Branding/Auth-Flags) und PortalUserRegistration (Token-Einladung) nutzbar.


Übernehmbar aus Boilerplate

Boilerplate-Pfad Was Wie nutzbar
prisma/schema/portals.prisma (Modelle Portal, PortalUser, PortalUserRegistration) Feld-/Struktur-Vorlage für CustomerPortalConfiguration (Branding/Auth-Flags) + Registration-Token-Muster als-vorlage (NICHT 1:1 — siehe Abschnitt oben)
prisma/schema/accounts.prisma → MagicLinkToken (Z.98) Magic-Link-Token-Pattern (tokenHash @unique, expiresAt, consumedAt, Index (userId, expiresAt) + (expiresAt, consumedAt)) als-vorlage — neue CustomerPortalMagicLinkToken braucht zusätzlich purpose-Enum (login/setup/password_reset/email_verification) + FK auf PortalUser statt User
apps/web/app/routes/auth.magic-link.tsx (+ .test.tsx), login.tsx/login.server.ts, forgot-password.tsx, reset.tsx, verify.$id.tsx Bestehende TenantUser-Auth-Flows (Magic-Link, Login, Pwd-Reset, Email-Verify) als Referenz-Implementierung als-vorlage — analog für PortalUser nachbauen mit getrenntem Cookie (hg_portal_session) und getrennter Middleware (requirePortalUser); KEIN Code-Reuse 1:1 (andere User-Klasse, andere Routes)
apps/web/app/utils/auth/passwordHasher.server.ts Passwort-Hashing (für optionales PortalUser-Pwd, ≥12 Zeichen, C.2) 1:1 (Hasher) — HIBP-Check ist zusätzlich zu verdrahten
apps/api/src/auth/login-rate-limit.ts, apps/api/src/auth/cookie/session-cookie.ts, packages/config/src/session-cookie.ts (resolveSessionCookiePolicy) Login-Rate-Limit + sichere Cookie-Policy (HTTP-only/Secure/SameSite=Lax) 1:1 für Policy-Helper; Rate-Limit-Pattern anpassen für Portal-Email/IP-Limits (C.1: 3/15min pro Email, 10/h pro IP)
packages/shared-store (createSlidingWindowRateLimiter, createFixedWindowRateLimiter, createSessionStore, createIdempotencyStore) Redis-KV für Rate-Limit (Magic-Link-Anfragen), Session-Cache, Idempotenz 1:1 als Infrastruktur
packages/storage/src (signed/, access/, scan/ mit ClamAV + magic-bytes-adapter + allow-list, s3-quarantine) Datei-Upload-Pipeline für D.5: signierte URLs, Mime-Type-Allowlist, Virus-Scan, Quarantäne 1:1 als Infrastruktur — Upload-Pfad tenants/{tenantId}/projects/{projectId}/portal-uploads/... + erlaubte Mime-Types (Bilder/PDF/Office/Audio) konfigurieren
prisma/schema/core.prisma → FileObject/FileUploadProgress/FileChunk Storage-Metadaten-Modelle anpassen — HiveGrid M23-Files (M052-M055) liefert die eigentliche File-Entität; CustomerPortalProjectDocument referenziert diese, nicht direkt FileObject
packages/mail/src (mailersend.ts, queue.ts, templates-react, types.ts) Transaktionaler Mail-Versand (Setup-/Login-/Status-/Doc-Released-/Upload-Received-Mails, Block G) 1:1 als Versand-Layer; Sending-Domain kommt aus HiveGrid M9 (Tenant-Default)
packages/foundation/src/notifications.ts (notify, notifyMany, bundleNotifications, isNotificationEnabled) + prisma/schema/notifications.prisma (NotificationDelivery, UserNotificationPreference, DeviceToken) Notification-Querschnitt für Push/Email-Digest an PL bei Upload/Form (M22) + Anti-Spam-Bündelung (M145 / 15.13.2.5) 1:1 — bundleNotifications deckt die 30-Min-Bündelung (15.13.2.5) direkt ab
packages/foundation/src/audit.ts (auditEvent, withAuditMiddleware) + prisma/schema/core.prisma → AuditEvent (Hash-Kette) Portal-Audit (Logins, Downloads, Uploads, Access-Änderungen, Status-Mails — Block A E.6, AV #6) 1:1 — S3-Upload/Download manuell auditieren (INTEGRATION-CONTRACTS §6 Ausnahme)
packages/foundation/src/permissions.ts (withTenantScope, withPermission, requirePermission, withOwnerCheck) Tenant-seitige Portal-Permissions (portal.read/manage_users/manage_access/delete_user/admin, Block I.1) + 404-statt-403-Pattern (I.3) 1:1 als Pattern; Permission-Keys neu in packages/entitlements/src/permissions.ts definieren
packages/foundation/src/errors.ts (CatalogError, foundationErrors.notFound 404) Klartext-Fehler + Existenz-Versteckung (404 bei fehlendem Project-Access, I.3 / D.3) 1:1
packages/foundation/src/flags.ts / packages/feature-flags + prisma/schema/featureFlags.prisma Feature-Flag „Modul ohne Deploy abschaltbar" (DoD), Portal aktivieren/deaktivieren 1:1
packages/view-models/src/index.ts (VMState, ActionCallbacks, RegistryGate, PortalRegistryItem, ShellRegistries) View-Model-Vertrag + Portal-Navigations-Registry-Typ (passt zu INTEGRATION-CONTRACTS §14 portal-shell.config.ts) 1:1 als Vertrag
packages/i18n (defaultLocale="de", supportedLocales=["de","en"], ICU, formatDate/Currency) i18n für alle Portal-Texte (DE/EN je PortalUser.language) + Klartext-Diagnostik (Block K) 1:1 — neuer Namespace customerPortal o.ä.
packages/db/src/dsgvo/user-fk-map.ts + packages/db/src/dsgvo/pseudonymize.ts + Worker apps/worker/src/jobs/dsgvo-export.ts, dsgvo-deletion.ts, dsgvo-grace-cron.ts (24h) DSGVO-Lösch-Workflow (24h-Reverse-Window, Anonymisierung) + JSON-Daten-Export (Block J / 15.11) anpassen — DSGVO-Infra ist auf User-FK ausgelegt; PortalUser-FKs müssen in user-fk-map.ts (bzw. analogem Portal-FK-Map) ergänzt werden; Export-Job-Muster (@toolctrl/exports JSON) wiederverwenden
packages/exports (./json, ./s3-multipart) DSGVO-JSON-Export-Bundle für PortalUser (J.4) 1:1 als Serializer + S3-Sink
prisma/schema/outbox.prisma (OutboxEvent) + packages/db/src/outbox.ts (publishOutboxEvent) + Worker apps/worker/src/outbox/event-router.ts Transaktionale Side-Effects (Status-Mail-Trigger bei project.stage_changed, M17-Trigger portal.*, Mail-Debounce) 1:1 als Event-Backbone; neue portal.* Event-Prefixe im DEFAULT_OUTBOX_ROUTING ergänzen
apps/worker/src (Cron-Scheduler-Muster, group-runtime.ts, handlers.ts, single-instance Cron wie dsgvo-grace-cron) Lifecycle-Cron-Jobs (M146): Auto-Deaktivierung nach 24 Monaten Inaktivität, Pro-Projekt-Auto-Schließung nach 12 Monaten, Status-Mail-Debounce (5-Min-Window) als-vorlage — neue Portal-Lifecycle-Jobs nach demselben Muster
apps/api/src/route-access-inventory.ts (Auth-Klassen, u.a. public-*) + apps/api/src/middleware/error-envelope.ts Öffentlich erreichbare Portal-Routen (Login/Setup/Reset sind ohne Session erreichbar) als Auth-Klassen-Muster als-vorlage
apps/web App-Shell (AppLayout, ShadcnSidebarLayout, components/ui/* shadcn/Radix: Tabellen/Forms/Modale/Empty/Loading) + Theme (Tenant.themeConfig, parseThemeConfig) Branding-Vererbung P1 (Tenant-Logo + Farbe, 15.8.10) + UI-Primitiven für Tenant-Admin-Konfig-Seiten (E.1–E.6) anpassen — Tenant-Admin-Seiten reuse die App-Shell; Endkunden-Portal-Shell ist eine eigene, minimale Shell (INTEGRATION-CONTRACTS §1: „Customer-Portal hat eigene minimale Navigation"), mobile-first (LP-2)
packages/marketing-outbound (Bündelungs-/Routing-Adapter-Muster) + Lead-Routing-Pattern (M048-Referenz) Routing-Regeln für Endkunden-Aktivitäten (M145 / 15.13.2.4, „analog Lead-Routing") als-vorlage für die Service-Inbox-Routing-Logik
CI-Gates: verify:phase-c-boundaries, verify:i18n, verify:tenant-isolation-report, verify:sidebar-routes, test:hot-swap, verify:ui-visual, Storybook + lost-pixel Erfüllung der DoD-Checkliste (Layer-Trennung, i18n, Visual-Regression, Hot-Swap-Drill) 1:1 erben/erweitern

Vorhandene Daten-Modelle (Boilerplate, konkrete Prisma-Pfade)

Modell Pfad Relevanz für M15
Portal, PortalUser, PortalUserRegistration, PortalPage prisma/schema/portals.prisma Nur als Struktur-Vorlage — fachlich SaaS-White-Label-Portal, nicht Endkunden-Projekt-Portal (siehe Eignungs-Abschnitt)
PortalSubscription* (6 Modelle) prisma/schema/portals.prisma Nicht verwenden in P1 (Anti-Liste 15.8.6)
MagicLinkToken (FK auf User) prisma/schema/accounts.prisma:98 Token-Pattern-Vorlage; neuer CustomerPortalMagicLinkToken mit purpose-Enum + FK auf PortalUser
User, Tenant, TenantUser, Registration, TenantUserInvitation prisma/schema/accounts.prisma TenantUser-Seite (strikt getrennt von PortalUser, LP-1 AV#2); Tenant.status/Tenant.themeConfig für Tenant-Lifecycle-Wirkung + Branding
AuditEvent (Hash-Kette), IdempotencyKey, FileObject/FileUploadProgress/FileChunk prisma/schema/core.prisma Audit, Idempotenz, Storage-Metadaten — Querschnitt
Role, Permission, RolePermission, UserRole, Group prisma/schema/permissions.prisma RBAC-Fundament für Tenant-seitige portal.*-Permissions (Block I.1)
NotificationDelivery, UserNotificationPreference, DeviceToken prisma/schema/notifications.prisma Notifications/Push an PL (M22) + Anti-Spam-Bündelung
OutboxEvent prisma/schema/outbox.prisma Event-Backbone (Status-Mail-Trigger, M17-Trigger)
FeatureFlag, FeatureFlagFilter, FeatureFlagAudit prisma/schema/featureFlags.prisma Feature-Flag-Abschaltbarkeit (DoD)
ExportJob, ImportJob prisma/schema/queue.prisma, imports.prisma DSGVO-Export-Job-Tracking
app.prisma (leerer Platzhalter // custom database models) prisma/schema/app.prisma Ziel-Ort für alle neuen CustomerPortal*-Modelle

NICHT vorhanden (HiveGrid-Domäne, von vorgelagerten Modulen geliefert, nicht von der Boilerplate): Project/Auftrag, Contact, Company, Deal, Pipeline, Stage, HiveGrid-File — grep "model (Project|Contact|Company|Deal|Pipeline|Stage)" in prisma/schema/ ist leer. Diese kommen aus M042-M046 (CRM), M059-M064 (Sales), M065-M070 (Auftrag), M052-M055 (Dateien) und sind harte Vorbedingungen (M142-Abhängigkeiten: M066, M052-M055, M092).


Lücken / komplett neu zu bauen

Daten-Layer (neu in app.prisma, alle als CustomerPortal*-Familie)

  • CustomerPortal (ein Default-Portal pro Tenant: tenantId @unique, slug=portal, is_default, enabled, archived_at)
  • PortalUser als eigene Endkunden-User-Klasse mit status-Enum (pending_setup|active|disabled|deleted), linked_contact_id/linked_company_id, language, last_login_at, optionalem Subunternehmer-Discriminator (M144 / 15.13.2.2)
  • CustomerPortalAccount (nullable password_hash, terms_accepted_at, marketing_opt_in, failed_login_attempts/locked_until)
  • CustomerPortalMagicLinkToken (purpose-Enum, Lebenszeiten login=15min/setup=7d/reset=1h/verify=24h, requested_ip/user_agent)
  • CustomerPortalSession (server-side Postgres-Session für PortalUser — existiert für keine User-Klasse in der Boilerplate; eigener Cookie hg_portal_session, 30-Tage-Sliding-Window, 7-Tage-Inaktivität)
  • PortalUserRegistration (Setup-Token + welcome_message)
  • CustomerPortalProjectAccess (access_level-Enum read_status_only|read_full, granted_by, Soft-Revoke; Indizes (tenant_id, portal_user_id), (tenant_id, project_id))
  • CustomerPortalProjectDocument (FK auf HiveGrid-File, release_kind-Enum, customer_visible_filename)
  • PortalConfiguration (visible_pipeline_stages JSON, stage_display_labels JSON, auto_release_doc_types, auto_status_mail_enabled, Pflicht-Links imprint_url/privacy_url, support_email/phone, welcome_message_default)
  • PortalEmailTemplate (template_kind-Enum, subject/body mit Platzhaltern, from_email_address_id → M9)
  • Subunternehmer-Strukturen (M144): Projekt-Subunternehmer-Liste (Firma/Rolle/Zeitraum), per-Projekt-Sichtbarkeits-JSON
  • Service-Inbox / Aktivitäts-Aggregation + Routing-Regeln (M145)

Auth-Layer (M141) — größte Einzel-Lücke

  • Komplette PortalUser-Auth-Schicht parallel zu M27: requirePortalUser-Middleware, getrennte Cookie-Domäne, Magic-Link-Flow (Anfrage → Token → Validierung → Session), Setup-Flow, Pwd-Reset, Email-Verification — in der Boilerplate existiert NUR die TenantUser-Auth (als Referenz, nicht 1:1 nutzbar). Cross-Permission-Test (Endkunde auf Tenant-Route → 404) ist Erfolgskriterium.
  • HIBP-Check für PortalUser-Passwörter (Boilerplate hat Hasher, aber HIBP separat zu verdrahten — vgl. M020)
  • hCaptcha ab 3. Magic-Link-Anfrage (C.1)

UI / Views — komplett neu

  • Endkunden-Portal-Shell (eigene minimale, mobile-first Navigation; NICHT die Tenant-App-Shell) + packages/ui-hivegrid/src/customer-portal/portal-shell.config.ts (INTEGRATION-CONTRACTS §14)
  • Alle Endkunden-Views: Dashboard (D.1), Projekte-Liste (D.2), Project-Detail mit Phasen-Fortschritt (D.3), Dokumente-Cross-View (D.4), Upload (D.5), Forms (D.6 — über HiveGrid M5, NICHT @toolctrl/form-widget, das nur text/email/number/select kann — kein File/Foto/Signatur), Settings (D.7)
  • Alle Tenant-Admin-Konfig-Seiten (E.1–E.6: Portal-Konfig, PortalUser-Verwaltung/-Detail, Access-Matrix, Email-Templates, Portal-Audit) — reuse App-Shell + shadcn-Primitiven, Inhalte neu
  • Querschnitt-Erweiterungen in bestehenden HiveGrid-Modulen: Project-Detail-Portal-Sektion (M4), Contact-Detail-Portal-Zugang (M1), Deal-Detail-Sales-Phase-Toggle (M3) — abhängig von M042-M070

Domänen-Logik / Integration

  • Auto-Status-Mail-Engine bei project.stage_changed mit Debounce (5-Min-Window), Mehrfach-Empfänger, Reverse-Stage-Stumm-Logik (Block G) — Outbox + Mail vorhanden, Logik neu
  • Doc-Auto-Freigabe-Regeln pro Doc-Typ + manuelle Freigabe/Sperre (15.5)
  • M17-Automation-Trigger/-Actions (portal.* — Block H), M22-Notifications-Wiring
  • Service-Inbox + Routing-Regeln + Stille-Modi + Service-Team-Rolle (M145)
  • Pro-Kunden- vs. Pro-Projekt-Lebensdauer-Logik + Lifecycle-Cron (M146)
  • DSGVO-Lösch-Workflow für PortalUser inkl. Portal-FK-Map (Export-/Deletion-Infra vorhanden, PortalUser-Verdrahtung neu)

Empfohlenes Vorgehen (Reihenfolge)

  1. Querschnitt zuerst sicherstellen (1:1 aus Boilerplate): foundation (auditEvent, withTenantScope/withPermission, notify, CatalogError, flags), packages/mail, packages/storage (signed/scan/access), packages/shared-store (Rate-Limit/Session/Idempotenz), Outbox + Worker-Cron-Muster, i18n, view-models. Diese sind nutzbar wie sie sind.
  2. Daten-Layer neu in prisma/schema/app.prisma als CustomerPortal*-Familie — portals.prisma als Feld-Vorlage heranziehen, aber NICHT erweitern (Namenskollision + falsche Fachlichkeit). MagicLinkToken (accounts.prisma:98) als Token-Pattern, ergänzt um purpose-Enum. Forward-Only-Migration mit Inverse-SQL (DoD).
  3. M141 Auth-Schicht neu bauen (kritischster Block) — TenantUser-Auth-Routen (auth.magic-link.tsx, login.server.ts, forgot-password.tsx, reset.tsx, verify.$id.tsx) als Referenz, aber als eigene PortalUser-Klasse mit getrenntem Cookie/Middleware. passwordHasher 1:1, HIBP + hCaptcha + Rate-Limits ergänzen. Cross-Permission-404-Test als Gate.
  4. M142 Projekt-Sicht auf bereits gebauten HiveGrid-Modulen (M042-M070, M052-M055, M092 sind Vorbedingungen) — Endkunden-Views + Permission-aware Filter (CustomerPortalProjectAccess) + Status-Mail-Engine (Outbox + Mail 1:1, Debounce-Logik neu).
  5. M143 Upload + Forms — packages/storage-Pipeline 1:1 (signed/scan/mime-allowlist/quarantine), Upload-Pfad-Konvention, Notification an PL via notify 1:1; Portal-Forms über HiveGrid M5 (M121-M125), nicht über @toolctrl/form-widget.
  6. M144 Subunternehmer — als Discriminator/Untergruppe der PortalUser-Klasse + per-Projekt-Sichtbarkeits-JSON; Datenleck-Schutz (Subunternehmer sehen Endkunden nicht).
  7. M145 Skalierung — Service-Inbox + Routing (Lead-Routing-Muster M048 als Vorlage) + bundleNotifications 1:1 für 30-Min-Bündelung.
  8. M146 Lebensdauer + DSGVO + Konfig — Lifecycle-Cron nach dsgvo-grace-cron-Muster; DSGVO-Export/Deletion-Infra (@toolctrl/exports JSON + dsgvo-*-Jobs) wiederverwenden, PortalUser-FK-Map ergänzen; Tenant-Admin-Konfig-Seiten mit App-Shell + shadcn.
  9. Reachability/DoD verdrahten: portal-shell.config.ts (§14, Default unsichtbar), Permission-Keys in entitlements/src/permissions.ts, i18n-Namespace, Smoke-/Hot-Swap-/Visual-Tests, Feature-Flag. CI-Gates erben.

Anti-Listen-Wächter (nicht bauen in P1): Portal-eigenes Branding (15.8.10), Chat/bidirektionale Kommunikation (15.8.1/15.8.4), In-App-Notifications im Portal (15.8.3), Wartungs-Abos/PortalSubscription* (15.8.6 — das gesamte Abo-Subsystem aus portals.prisma bewusst ignorieren), Bulk-ZIP-Download (15.8.9), 2FA-Pflicht (15.8.8), Blog/CMS (15.8.7), eigene Domain (15.14.2), Mehrfach-Portale (15.14.3).