Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,122 @@
# Boilerplate-Abgleich — M31 Branding / Theme
| Feld | Wert |
|------|------|
| **Modul-ID** | M31 |
| **Name** | Branding / Theme |
| **Milestones** | M030 (Hell/Dunkel-Modus + Capacitor-Status-Bar) — Phase 1. (Spec-Quelle `_bmad-output/specs/M31-branding.md`; LP-9. Phase-2-Features E.1-E.6 ohne eigenes Milestone in `docs/milestones/`.) |
| **Block** | Block 1, Abschnitt 31.1 (`_bmad-output/pflichtenheft/blocks/block1.md`) |
| **Reuse-Level Phase 1** | **medium** — solide Light/Dark-Basis vorhanden, aber binär statt drei-modig; "system"-Modus + Live-Reaktivität fehlen |
| **Reuse-Level Phase 2** | **medium-high** — Tenant-Theme-Engine (Farben/CSS-Vars), System-Branding-Felder (Logo/Favicon) und Mail-Brand-Tokens existieren als starke Vorlage |
> **WICHTIG zur Milestone-Benennung:** Das Milestone-Verzeichnis `docs/milestones/M031-feature-flag-schalter-lifecycle/` gehört NICHT zu diesem Modul (das ist Feature-Flags). Das fachlich passende Milestone für M31 Branding/Theme Phase 1 ist **`docs/milestones/M030-hell-dunkel-modus/`**.
> **Hinweis zur PLAN.md-Annahme:** `M030/PLAN.md` nennt „`next-themes` bereits in Boilerplate-Deps". Das ist **falsch verifiziert** — `next-themes` taucht in der Boilerplate nur in `apps/web/app/utils/build/buildWarningTriage.ts` (Build-Warnungs-Triage) auf, NICHT als aktive Theme-Lib. Die reale Boilerplate nutzt ein **eigenes Session/Cookie-basiertes Dark-Mode-System** (siehe unten). Slice-Planung muss das korrigieren.
---
## Was das Modul fachlich braucht (aus Spec)
**Phase 1 (M030 / minimal):**
- A: `User.theme_preference` Enum `system | light | dark`, Default `system`
- B: User-Settings-Route `/{tenant}/settings/profile/` mit 3-Optionen-Picker, sofortige Anwendung ohne Reload
- C: Theme-Auflösung (User-Pref → `prefers-color-scheme` → Light-Fallback), Live-Reaktivität bei `system` (matchMedia-Listener), SSR-No-Flash via Cookie/Header, Anwendung in Web (`dark:`-Class) + Capacitor (Status-Bar/Splash)
- D: keine Permissions in Phase 1
**Phase 2 (E.1-E.6, später):** TenantBranding-Tabelle (Logo, primary/accent-color, display-name), `/{tenant}/admin/branding/`, Logo-Upload, Farb-Picker mit Live-Preview, Branding in Email/Portal/Login/Splash, White-Label (custom_domain, custom fonts, theme_variables JSONB), Permissions `branding.admin` + `branding.white_label` (Enterprise-Gate via M27).
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `prisma/schema/accounts.prisma:17` | `User.lightOrDarkMode String?` — Per-User Hell/Dunkel-Präferenz | **anpassen** — Feld existiert, ist aber binär (`light`/`dark`, nullable). Muss zu 3-Wert-Enum `system\|light\|dark` mit Default `system` erweitert/migriert werden |
| `apps/web/app/root.tsx:97-100` | SSR-Anwendung der `dark`-Klasse auf `<html>` aus `userSession.lightOrDarkMode` (gated über `DARK_MODE_IN_APP`) | **als-vorlage** — No-Flash-Mechanik via Session vorhanden; muss um `system`-Auflösung (`prefers-color-scheme`) + Cookie-Header-Lesung erweitert werden |
| `apps/web/app/root.tsx:184-213` | Action `toggleLightOrDarkMode` (+ `setTheme`, `setLocale`): persistiert in User-DB + Session, feuert `EventsService.create` Audit-Event `user.preferences.updated` | **als-vorlage** — Persist-Pfad + Audit-Wiring vorhanden; Toggle→3-Wert-Set umbauen |
| `apps/web/app/routes/preferences.tsx` | Dedizierte `/preferences`-Action-Route, an die Toggle/Selector posten | **anpassen** — Endpoint-Pattern wiederverwenden; Action für 3-Wert-Preference ergänzen |
| `apps/web/app/utils/theme/userThemePreference.server.ts` | `LIGHT_OR_DARK_MODES`, `normalizeLightOrDarkMode`, `nextLightOrDarkMode`, `persistUserLightOrDarkMode(userId, …)` | **anpassen** — Normalisierung/Persist als Basis; Enum um `system` erweitern, Auflösungs-Helfer (`resolveEffectiveTheme`) neu ergänzen |
| `apps/web/app/components/ui/toggles/DarkModeToggle.tsx` (`DarkModeToggle`, `DarkModeSvgs`) | Binär-Toggle-Button mit i18n-Label + Analytics-Event | **als-vorlage** — für 2-Wert; für Phase-1-Spec (3 Optionen) eher Picker (s. nächste Zeile) |
| `apps/web/app/components/ui/selectors/ThemeSelector.tsx` | Dropdown/Select-Picker, postet `setTheme` an `/preferences` mit Analytics | **als-vorlage** — Picker-Pattern (Dropdown + fetcher.submit) direkt für System/Hell/Dunkel-Auswahl übernehmbar; Optionen-Quelle austauschen |
| `apps/web/app/components/layouts/sidebars/shadcn/nav-user.tsx:152-157` | Theme-Toggle bereits in User-Menü der App-Shell verdrahtet (`onThemeToggle`, gated über `DARK_MODE_IN_APP`) | **als-vorlage** — Einbau-Ort in Shell vorhanden; auf Picker/3-Wert anpassen |
| `apps/web/app/application/Constants.ts:10` | `DARK_MODE_IN_APP = true` — Schalter ob App-Bereich Dark-Mode bekommt | **1:1** als Feature-Gate-Vorbild (Spec D verlangt Feature-Flag-Fähigkeit) |
| `apps/web/app/application/enums/shared/Theme.ts` | `enum Theme { LIGHT, DARK }` | **anpassen** — um `SYSTEM` erweitern |
| `apps/web/app/locale/.../translations.json` (`components.themeToggle.modeLabel.light/dark`, `settings.theme.*`, `shared.theme`) | Vorhandene i18n-Keys de+en für Theme-Labels | **anpassen** — `system`-Label ergänzen; Klartext aus Spec B.1 einsetzen |
| `apps/mobile/package.json:25` (`@capacitor/status-bar` 7.0.1), `@capacitor/splash-screen` 7.0.1 | Capacitor Status-Bar- + Splash-Plugins als Dependency installiert | **als-vorlage** — Plugins vorhanden, aber **keine theme-aware Nutzung** (kein `StatusBar.setStyle`-Aufruf in `apps/mobile/src`) → Spec C.4 muss neu gebaut werden |
### Phase-2-relevante Vorlagen (Tenant-Branding / White-Label)
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `prisma/schema/accounts.prisma:187-188` | `Tenant.theme String?` + `Tenant.themeConfig String?` (serialisierter JSON-String mit Farben inkl. `darkColors`, `sidebar*`) | **als-vorlage** für Phase-2-`TenantBranding` (Farb-Override pro Tenant) |
| `apps/web/app/utils/theme/ThemeConfig.ts` (`parseThemeConfig`, `ThemeConfig`) | Parst Tenant-`themeConfig` → CSS-Variablen (alle Farb-Slots inkl. dark, sidebar, radius, fontFamily) | **als-vorlage** für Phase-2-Live-Theming / `theme_variables` JSONB (E.5) |
| `apps/web/app/utils/theme/defaultThemes.ts` (`themeConfigurations`, `defaultThemes`, `defaultTheme="blue"`) | ~20 vordefinierte Farbschemata (light+dark) als CSS-Var-Sets | **als-vorlage** für Farb-Picker-Presets (E.1) |
| `apps/web/app/themes.css` (~86 KB) | `.theme-{name}` + `.dark.theme-{name}` Klassen | **als-vorlage** für Phase-2-CSS-Var-Theming |
| `apps/web/app/routes/app.$tenant/settings/theme.tsx` + `apps/web/app/components/core/tenants/forms/UpdateTenantFormTheme.tsx` | Tenant-Theme-Verwaltungs-Route (`update-theme`-Action, Permission-gated `app.settings.account.view/update`, Live-Preview via `themePreviewStore`) | **als-vorlage** für `/{tenant}/admin/branding/` (E.1) — Route-/Form-/Permission-Pattern direkt adaptierbar |
| `apps/web/app/stores/themePreviewStore.ts` (`useThemePreviewStore`) | Client-Store für Live-Preview-Override im Shell-Layout | **als-vorlage** für „Preview vor Live-Schalten" (E.6) |
| `apps/web/app/components/layouts/sidebars/shadcn/ShadcnSidebarLayout.tsx` | Liest Tenant-`themeConfig` + Dark-Mode → injiziert `--sidebar*` CSS-Variablen in Shell | **als-vorlage** für Anwendung von Tenant-Branding in Sidebar/Header (E.1) |
| `prisma/schema/core.prisma:6,23-27` (`AppConfiguration.theme`, `brandingLogo`, `brandingLogoDarkMode`, `brandingIcon`, `brandingIconDarkMode`, `brandingFavicon`) | **System-weite** (nicht tenant-bezogene) Branding-Felder | **als-vorlage** für Feld-Shape der Phase-2-`TenantBranding`-Tabelle (Logo + Dark-Logo + Icon + Favicon) |
| `apps/web/app/utils/db/appConfiguration.db.server.ts:90,196,251-292` | Load/Persist + Mapping `branding.logo/logoDarkMode/icon/iconDarkMode/favicon` | **als-vorlage** für DB-Service-Layer Phase 2 |
| `apps/web/app/root.tsx:127-135` | Favicon/Branding-Logo aus `appConfiguration.branding` ins `<head>` injiziert | **als-vorlage** für Tenant-Branding-Anwendung (E.1) |
| `packages/brand/src/index.ts` (`@toolctrl/brand`) | Brand-Tokens (productName, legal/support-Links, assets, **mail.colors**), `createBrandTokens`, `resolveTransactionalBrandTokens`, `brandCssVariables` | **als-vorlage** für E.2 (Email-Branding mit Logo+Primärfarbe) — Mail-Color-Token-Resolution + CSS-Var-Export bereits fertig |
| `prisma/schema/portals.prisma:14-15` (`themeColor`, `themeScheme`) + `apps/web/app/modules/portals/db/portals.db.server.ts:176-209` | Per-Portal `themeColor`/`themeScheme` (separates Customer-Portal-Theming) | **als-vorlage** für E.3 Custom-Login/Portal-Branding (eigenständiges Konzept, nicht 1:1) |
---
## Vorhandene Daten-Modelle
| Modell / Feld | Pfad | Deckung |
|---|---|---|
| `User.lightOrDarkMode String?` | `prisma/schema/accounts.prisma:17` | Phase 1 A.1 — **teilweise** (binär statt 3-Wert-Enum, nullable statt Default `system`) |
| `Tenant.theme String?` | `prisma/schema/accounts.prisma:187` | Phase 2 E.1 — Tenant-Farbschema-Auswahl |
| `Tenant.themeConfig String?` | `prisma/schema/accounts.prisma:188` | Phase 2 E.1/E.5 — serialisierte Tenant-Theme-Vars (Whitelabel-Vorlage) |
| `AppConfiguration.theme / brandingLogo / brandingLogoDarkMode / brandingIcon / brandingIconDarkMode / brandingFavicon` | `prisma/schema/core.prisma:6,23-27` | Phase 2 E.1 — **System-Level** Branding-Feld-Shape (Vorlage für TenantBranding) |
| `Portal.themeColor / themeScheme` | `prisma/schema/portals.prisma:14-15` | Phase 2 E.3 — Customer-Portal-Theming (separat) |
**Existiert NICHT (muss in Phase 2 neu angelegt werden):**
- Keine `TenantBranding`-Tabelle (kein `model TenantBranding/Branding/TenantTheme` in `prisma/schema/*.prisma`).
- Keine `logoFileId`/`primaryColor`/`accentColor`/`custom_domain`/`theme_variables`-Felder als eigene Tenant-Branding-Entität.
- Branding ist heute **system-weit** (`AppConfiguration`), NICHT tenant-scoped.
---
## Lücken / komplett neu zu bauen
### Phase 1 (M030)
1. **3-Wert-Theme-Preference statt binär** — `User.lightOrDarkMode` ist `light`/`dark`. Spec verlangt Enum `system | light | dark` mit Default `system`. → Feld erweitern/migrieren (Forward-Only-Migration), `Theme`-Enum + Normalisierungs-Helfer um `system` ergänzen.
2. **`system`-Auflösung über `prefers-color-scheme`** — existiert NICHT (`grep prefers-color-scheme` = 0 Treffer in apps/packages). Spec C.1 Schritt 3 + Live-Listener C.2 (`matchMedia('(prefers-color-scheme: dark)')`) komplett neu.
3. **Live-Reaktivität bei `system`** — kein Client-Listener für OS-Theme-Wechsel während offener Session (C.2) vorhanden.
4. **SSR-Cookie für No-Flash bei `system`** — heute kommt der Modus aus der **Server-Session** (nur eingeloggt). Für `system`/nicht-eingeloggt + No-Flash braucht es Cookie/Header-Lesung von `prefers-color-scheme` server-seitig (C.3). Neu.
5. **3-Optionen-Picker an `/{tenant}/settings/profile/`** — Picker-Komponente existiert als Vorlage (`ThemeSelector`/`DarkModeToggle`), aber für 3 Optionen mit Spec-Klartext (B.1) neu zusammenzubauen; Einbau in `settings/profile` (nicht nur User-Menü).
6. **Capacitor Status-Bar / Splash theme-aware** — Plugins (`@capacitor/status-bar`, `@capacitor/splash-screen`) sind installiert, aber **kein** `StatusBar.setStyle(...)`-Aufruf in `apps/mobile/src` (C.4). Native-Hook komplett neu.
7. **i18n-Key `system`** — `components.themeToggle.modeLabel` hat nur `light`/`dark`; `system` + Spec-Klartexte fehlen.
### Phase 2 (E.1-E.6) — alles als Vorlage vorhanden, aber neu zu bauen
- `TenantBranding`-Tabelle (Felder per `AppConfiguration`-Shape) — neu.
- `/{tenant}/admin/branding/`-Route — `settings/theme.tsx`-Pattern adaptieren.
- Logo-Upload (PNG/SVG) via Files-Modul (M23/Scaleway) — neu verdrahten.
- Permissions `branding.admin` (über `tenant.admin`) + `branding.white_label` (Enterprise-Gate via M27) — neu.
- White-Label: custom_domain (Caddy-Cert), custom fonts, `theme_variables` JSONB, hide-hivegrid-branding — neu (ThemeConfig-Parser als Vars-Vorlage).
- Email-Branding (E.2): `@toolctrl/brand` mail-tokens als Basis, tenant-scoped erweitern.
---
## Empfohlenes Vorgehen (Phase 1 zuerst)
1. **Daten-Layer:** `User.lightOrDarkMode` → 3-Wert-Preference erweitern. Forward-Only-Migration mit Inverse-SQL-Kommentar; Default `system`; bestehende `null`-Werte → `system`. (`accounts.prisma:17`)
2. **Auflösungs-Helfer neu:** `resolveEffectiveTheme(pref, prefersColorSchemeHeader/Cookie)` aufbauend auf `userThemePreference.server.ts`-Normalisierung. Reihenfolge nach Spec C.1.
3. **SSR-No-Flash erweitern:** `root.tsx:97-100` umbauen — `dark`-Klasse zusätzlich aus aufgelöstem `system`-Wert (Cookie/Header) setzen, nicht nur aus Session. Cookie-Name (offener Spec-Punkt) festlegen.
4. **Client-Reaktivität:** `matchMedia`-Listener für `system`-Modus (neu) — bei OS-Wechsel `dark`-Klasse live toggeln (C.2), Cookie aktualisieren.
5. **UI-Picker:** `ThemeSelector.tsx`/`DarkModeToggle.tsx` als Vorlage → 3-Optionen-Picker mit Spec-Klartext; posten an `/preferences` (vorhandene Action erweitern). Einbau in `settings/profile` + optional User-Menü (`nav-user.tsx`).
6. **Audit/Events:** vorhandenes `user.preferences.updated`-Event (`root.tsx:197`) für neuen 3-Wert weiterverwenden.
7. **i18n:** `system`-Label + Klartexte (de zuerst, AV #4 — alle Strings extern).
8. **Capacitor (C.4):** Native-Hook neu — `@capacitor/status-bar` `StatusBar.setStyle(Style.Dark/Light)` + Splash an aufgelösten Modus koppeln (`apps/mobile/src`). Soft-dependency auf M168.
9. **Feature-Flag:** Modul über Flag abschaltbar machen (DoD); `DARK_MODE_IN_APP`-Konstante als Vorbild.
10. **Phase 2** erst nach eigener Detail-Spec; dann `settings/theme.tsx` + `AppConfiguration`-Branding-Shape + `@toolctrl/brand` als Startpunkte.
---
## Notiz zu Layer-Disziplin (AGENTS.md / INTEGRATION-CONTRACTS)
- Die Boilerplate-Vorlagen liegen in `apps/web` (RR7-Routen, Loader+Action+Component gemischt). HiveGrid-DoD verlangt: Loader baut View-Model, UI-Component (`packages/ui-hivegrid/**`) nur VM+Actions, keine Prisma-/Server-Imports im UI-Paket, Subframe via Adapter. → Vorlagen als Referenz für Logik, **UI-Komponente neu** in `packages/ui-hivegrid` (Subframe-Design pflicht, Memory `feedback_subframe_mandatory`).
- Sidebar/Settings-Wiring: `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` ist Single-Source (INTEGRATION-CONTRACTS §1); Mandant-Settings unter `app.hivegrid.de/settings/<modul>/...` (§ Route-Tabelle). Phase 1 ist eine Profil-Settings-Sektion, kein eigener Sidebar-Top-Eintrag — explizit dokumentieren (DoD-Ausnahme).