6.5 KiB
module, title, phase, status, last_updated, session_source, related_lps, spec_style
| module | title | phase | status | last_updated | session_source | related_lps | spec_style | |
|---|---|---|---|---|---|---|---|---|
| 31 | Branding / Theme | 1 | detail-spec-draft | 2026-05-08 | brainstorming-session-2026-05-07-2206.md |
|
requirements-pur |
Modul 31 — Branding / Theme
Detail-Spec gemäß LP-9. Phase 1 minimal: nur Light/Dark-Mode pro User. Voll-Branding (Logo, Farben, White-Label) ist Phase 2. Modul ist in Phase 1 bewusst fast leer.
Themenblöcke
A. Datenmodell (Phase 1)
B. Routes & Settings (Phase 1)
C. Theme-Auflösung (System/Light/Dark)
D. Permissions
E. Phase 2 / spätere Features
Block A — Datenmodell (Phase 1)
A.1 — User.theme_preference
Bestehendes/zu ergänzendes User-Feld:
theme_preference(Enum:system | light | dark, Defaultsystem)
Anwendung:
system→ folgt OS-/Browser-Präferenz (prefers-color-scheme)light→ erzwingt Light-Themedark→ erzwingt Dark-Theme
Persistierung:
- Server-side in
User.theme_preference - Client-side Cache in Cookie/LocalStorage für SSR-Konsistenz (verhindert Flash-of-Wrong-Theme)
A.2 — Keine weiteren Tabellen in Phase 1
In Phase 1 wird kein TenantBranding, kein Logo-Upload, keine Tenant-Farb-Tabelle angelegt. Voll-Datenmodell siehe Phase 2 (Block E).
Block B — Routes & Settings (Phase 1)
B.1 — User-Profile-Settings (/{tenant}/settings/profile/)
Theme-Auswahl:
- Toggle/Picker mit drei Optionen:
System/Hell/Dunkel - Sofortige Anwendung ohne Reload
- Persistierung in
User.theme_preference
Klartext:
- Option
System: „Folgt der Einstellung deines Geräts" - Option
Hell: „Helles Design" - Option
Dunkel: „Dunkles Design"
B.2 — Keine Tenant-Admin-Route in Phase 1
/{tenant}/admin/branding/ existiert in Phase 1 nicht. Erst Phase 2 (siehe Block E).
Block C — Theme-Auflösung
C.1 — Auflösungs-Reihenfolge
Beim Rendern einer User-Session:
- Wenn User eingeloggt +
User.theme_preference = light→ Light - Wenn User eingeloggt +
User.theme_preference = dark→ Dark - Sonst (
systemoder nicht eingeloggt): Browser-Media-Queryprefers-color-scheme - Fallback: Light
C.2 — Live-Reaktivität bei system
- Wenn User
theme_preference = systemund OS-Theme wechselt während der Session, soll Theme live mitwechseln - Listener auf
matchMedia('(prefers-color-scheme: dark)')Change-Event
C.3 — SSR-Konsistenz
- Server rendert mit Theme-Klasse auf
<html>basierend auf Cookie/Header - Verhindert Flash-of-Wrong-Theme beim Hydrate
C.4 — Anwendung in App und Capacitor
- Web: über CSS-Variablen + Theme-Class auf
<html>(Implementierungs-Detail Tailwind-dark:-Variants) - Capacitor (Modul 36): native Status-Bar / Splashscreen müssen Theme respektieren (Native-Hooks setzen)
Block D — Permissions
Permission-IDs
Phase 1 hat keine branding-spezifischen Permissions. User kann eigenes Theme jederzeit setzen.
Phase 2: branding.admin als eigene Permission, gegated über tenant.admin für Tenant-weite Branding-Settings.
Klartext-Fehler
In Phase 1 keine relevanten Fehler-Cases.
Phase 2 / spätere Features
E.1 — Tenant-Branding (Standard, alle Pläne)
Datenmodell — neue Tabelle TenantBranding:
tenant_id(PK, FK)logo_file_id(FK auf File, optional)primary_color(Hex-String, validiert)accent_color_1(Hex-String, optional)accent_color_2(Hex-String, optional)tenant_display_name(überschreibt System-Default in UI, optional)updated_at,updated_by_user_id
Routes:
/{tenant}/admin/branding/— Verwaltungs-Seite
Funktionen:
- Logo-Upload (PNG/SVG, max-Größe definiert)
- Farb-Picker für Primärfarbe + 1-2 Akzentfarben mit Live-Preview
- Tenant-Name-Override für UI-Anzeige
- Branding-Anwendung in: Sidebar/Header-Logo, Email-Header, Customer-Portal, Login-Screen, Capacitor-Splashscreen
- Reset-auf-Default-Funktion
Permission: branding.admin (über tenant.admin)
E.2 — Outbound-Email-Templates mit Branding
- System-Email-Templates erben Tenant-Logo + Primärfarbe
- Header-/Footer-Bereiche im Template-System branding-bewusst
- Marketing-Emails (Modul 10) übernehmen Branding standardmäßig, optional override
E.3 — Custom-Login-Screen
- Tenant-Logo + ggf. Hintergrund-Bild auf
/loginwenn Tenant-Subdomain/-Slug erkannt - Phase 2 für alle Pläne
E.4 — Custom-Splashscreen für Capacitor-App
- Tenant-Logo als Splashscreen in iOS/Android-Builds
- Generierung pro Tenant über Build-Pipeline (Implementierungs-Detail) oder dynamisches Theming beim App-Start
E.5 — White-Label-Modus (Enterprise only)
Funktionen:
- Eigene Domain (
crm.geerkens.deals CNAME zuapp.hivegrid.de/{tenant}) - Eigene Fonts (Upload von Webfonts oder Google-Fonts-Auswahl)
- Vollständig anpassbares Theme (alle Farb-Variablen, nicht nur Primary/Accent)
- Eigenes Email-Template-System (Tenant baut Templates selbst inkl. HTML)
- HiveGrid-Branding entfernt (Footer, Email-Footer, Login-Page)
- Custom-Domain-Workflow inkl. Cert-Management (Caddy-Auto-HTTPS)
Permission: branding.white_label — nur in Enterprise-Plan via Feature-Gate (Modul 27, Block F)
Datenmodell-Erweiterung TenantBranding:
custom_domain(String, validiert)custom_font_file_ids[]theme_variables(JSONB — alle CSS-Variablen)email_templates_custom(Boolean Toggle)hide_hivegrid_branding(Boolean Toggle)
E.6 — Branding-Preview vor Live-Schalten
- Tenant-Admin sieht Vorschau vor Anwendung
- Apply-Button schaltet live für alle User des Tenants
Architektur-Vorschriften (Querschnitt)
- LP-9 — Spec-Tiefe: Phase 1 minimal gehalten, Phase 2 explizit umrissen
- AV #4 — Alle Strings extern: Tenant-Name-Override aus DB, nicht hartkodiert (relevant für Phase 2)
- LP-13 — EU-Stack: Logo-Storage über Scaleway-EU (Modul 23)
Detail-Spec-Status: DRAFT
Modul ist in Phase 1 bewusst minimal. Phase-2-Features sind grob umrissen für Roadmap-Klarheit; Detail-Spec für Phase 2 erfolgt vor Phase-2-Implementierung.
Offene Detail-Punkte (nicht-blockierend):
- Konkrete CSS-Variable-Namen (Implementierungs-Detail Tailwind-Config)
- SSR-Cookie-Name für Theme-Persistierung
- Capacitor-Native-Hook für Status-Bar-Theming (Implementierungs-Detail)
Abhängige Module:
- Modul 27 (Auth) —
User.theme_preference-Feld - Modul 36 (Mobile/Capacitor) — Native-Status-Bar/Splashscreen-Theming
- Phase 2: Modul 23 (Files) — Logo-Upload-Storage
- Phase 2: Modul 27 (Auth, Block F) — Feature-Gate für White-Label-Enterprise