--- module: 32 title: Feature-Flags phase: 1 status: detail-spec-draft last_updated: 2026-05-08 session_source: brainstorming-session-2026-05-07-2206.md related_lps: [LP-9, LP-10] spec_style: requirements-pur --- # Modul 32 — Feature-Flags > **Detail-Spec gemäß LP-9.** Phase 1 minimal — reines Plattform-Admin-Werkzeug, um Features pro Tenant gezielt zu aktivieren/deaktivieren. Kein Tenant-User-UI in Phase 1. Eng verzahnt mit Modul 37 (Plattform-Admin) und Modul 27 Block F.2. ## Themenblöcke ``` A. Datenmodell (FeatureFlag, FeatureFlagFilter, TenantFeatureFlag) B. Routes (admin.hivegrid.de/feature-flags) C. Listen-View und Detail-View D. Filter-Auswertung (zielgruppen-basiertes Aktivieren) E. Code-Convention (tenantHasFlag) F. Flag-Lifecycle (beta → rollout → GA → deprecated) G. Audit-Logging H. Permissions I. Phase 2 Erweiterungen ``` --- ## Block A — Datenmodell ### FeatureFlag Globale Definition eines Flags. Lebt **nicht** im Tenant-Scope, kein RLS — gehört der Plattform. - `id`, `created_at`, `updated_at`, `created_by_admin_user_id` - `key` (technischer Name, snake_case, eindeutig global, z.B. `beta_new_dashboard`) - `label` (kurzer Klartext-Name für Admin-UI) - `description` (Markdown-Freitext: was tut das Flag, welcher Code-Pfad hängt dran, welche Module betroffen) - `default_value` (Boolean — Wert wenn weder globaler Override noch Tenant-Override existiert) - `lifecycle_stage` (Enum: `beta | rollout | ga | deprecated`) - `owner_admin_user_id` (verantwortlicher Plattform-Admin) - `target_module` (optionales Tag: in welchem Modul lebt der Flag, z.B. `crm`, `automation`, `kwp` — frei textuell) - `archived_at` (Soft-Delete für GA-/Deprecated-Cleanup-Phase) **Indizes:** `key` (unique), `lifecycle_stage`, `archived_at`. ### FeatureFlagFilter Pro Flag eine Liste von Filter-Regeln, die Tenants automatisch matchen. Wenn ein Tenant matcht und kein expliziter `TenantFeatureFlag`-Override existiert, gilt der Filter-Wert. - `id`, `feature_flag_id`, `created_at`, `created_by_admin_user_id` - `name` (Klartext: *„Tenants mit > 50 MA"*) - `priority` (Integer — bei mehreren matchenden Filtern gewinnt höchste Priority) - `value` (Boolean — was der Filter setzt) - `criteria` (JSONB — Filter-Bedingung, siehe unten) - `active` (Boolean — Filter ein-/ausschaltbar ohne Löschen) **Filter-Kriterien (JSONB-Schema, kombinierbar mit AND):** - `tenant_size` (Enum-Match: `1-10 | 11-25 | 26-50 | 51-100 | 100+`) - `tenant_industry` (Enum-Match: `shk | ...`) - `tenant_status` (Match auf `trial | active | past_due | frozen | suspended`) - `subscription_product_id` (Match auf bestimmten Plan) - `tenant_created_after` / `tenant_created_before` (Datum) - `tenant_id_in[]` (explizite Liste — quasi „diese 5 Test-Tenants") - `tenant_id_not_in[]` **Hinweis:** Filter-Kriterien sind in Phase 1 bewusst klein gehalten. Erweiterungen in Phase 2 (Region, MRR-Schwelle, Custom-Tags). ### TenantFeatureFlag (Override pro Tenant) Expliziter Override eines Flags für einen Tenant. Hat **immer Vorrang** vor Filter und Default. - `id`, `feature_flag_id`, `tenant_id`, `created_at`, `updated_at` - `value` (Boolean) - `set_by_admin_user_id` - `note` (optionaler Klartext: *„Manuell aktiviert für Geerkens-Pilot"*) - `expires_at` (optional — automatischer Rück-Reset auf Filter/Default) **Constraint:** unique pro `(feature_flag_id, tenant_id)`. **Indizes:** `(tenant_id, feature_flag_id)` für schnelles Lookup, `expires_at` für Cron-basiertes Aufräumen. ### Auswertungs-Reihenfolge (deterministisch) 1. Existiert `TenantFeatureFlag` für diesen Tenant + Flag → dessen `value` gilt 2. Sonst: alle aktiven `FeatureFlagFilter` durchlaufen (sortiert nach `priority` absteigend), erster Match liefert `value` 3. Sonst: `FeatureFlag.default_value` --- ## Block B — Routes **Ausschließlich auf `admin.hivegrid.de`** (Plattform-Admin-Subdomain, siehe Modul 37). **Keine** Routen unter `app.hivegrid.de/{tenant}/...` in Phase 1. ``` admin.hivegrid.de/feature-flags/ → Flag-Liste admin.hivegrid.de/feature-flags/new → Neues Flag anlegen admin.hivegrid.de/feature-flags/:id → Flag-Detail (inkl. Filter, Tenant-Overrides, Audit-History) admin.hivegrid.de/feature-flags/:id/edit → Stammdaten editieren admin.hivegrid.de/feature-flags/:id/filters/new → Neuen Filter anlegen admin.hivegrid.de/feature-flags/:id/filters/:fid → Filter editieren admin.hivegrid.de/tenants/:tenantId/flags → Pro-Tenant-Sicht aller Flag-Auswertungen (siehe Modul 37) ``` **Permissions:** Alle Routen erfordern `admin.feature_flags.*` (Plattform-Admin-Permission, siehe Modul 37). --- ## Block C — Listen-View und Detail-View ### Flag-Liste (`admin.hivegrid.de/feature-flags/`) **Zu zeigende Daten pro Eintrag:** - `key`, `label` - `lifecycle_stage` - `default_value` - Anzahl aktiver Filter - Anzahl Tenant-Overrides - `owner_admin_user_id` - `target_module` - Letzte Änderung (Datum + Admin-User) **Benötigte UI-Elemente:** - Tabellarische Listen-Anzeige - Filter-Funktionen: nach `lifecycle_stage`, `target_module`, Owner - Suche über `key` und `label` - Sortierung pro Spalte - Toggle „Archivierte anzeigen" - Add-Funktion für neues Flag **Operationen:** - Detail öffnen - Lifecycle-Stage-Wechsel (Quick-Action) - Archivieren / Reaktivieren ### Flag-Detail (`admin.hivegrid.de/feature-flags/:id`) **Zu zeigende Daten:** - Stammdaten (alle Felder aus `FeatureFlag`) - Liste der `FeatureFlagFilter` mit Priority, Value, Criteria-Klartext, aktiv/inaktiv - Liste der `TenantFeatureFlag`-Overrides mit Tenant-Name, Value, Note, gesetzt von, Expires-At - Effektive-Auswertung-Statistik (Anzahl Tenants pro Endwert: *X Tenants haben Flag aktiv, Y nicht*) - Audit-History (siehe Block G) **Benötigte UI-Elemente:** - Sektionen für: Stammdaten, Filter, Tenant-Overrides, Audit - Inline-Edit für Stammdaten - Filter-Editor (siehe Block D) - Tenant-Override-Editor: Tenant-Suche (Auto-Complete) + Boolean-Wert + Note + optional Expires-At - Bulk-Override-Funktion: mehrere Tenants gleichzeitig auf gleichen Wert setzen (z.B. *„diese 12 Tenants alle auf true"*) - Lifecycle-Stage-Wechsel mit Bestätigungs-Dialog - Archivieren-Funktion (mit Klartext-Hinweis bei aktiven Tenant-Overrides) **Operationen:** - Stammdaten editieren (`label`, `description`, `default_value`, `lifecycle_stage`, `owner`, `target_module`) - `key` ist nach Anlage **nicht editierbar** (Code-Referenz-Stabilität) - Filter anlegen/editieren/löschen/de-/aktivieren - Tenant-Override anlegen/editieren/löschen - Audit-History betrachten --- ## Block D — Filter-Auswertung ### Filter-Editor **Benötigte UI-Elemente:** - Eingabe für `name`, `priority`, `value` (Toggle) - Criteria-Builder: pro Criteria-Schlüssel ein Eingabe-Element (Dropdown für Enums, Multi-Select wo passend, Datums-Picker für Created-Vor/Nach, Tenant-Auto-Complete für `tenant_id_in[]`) - Live-Vorschau: *„Aktuell würden X Tenants matchen"* mit Klick auf Liste der gematchten Tenants - Aktivieren/Deaktivieren-Toggle **Operationen:** - Criteria sind AND-verknüpft. OR über mehrere Filter-Einträge mit unterschiedlichen Kriterien lösbar. - Live-Vorschau läuft auf Read-Replica gegen aktuelle Tenant-Tabelle. ### Auswertungs-Reihenfolge bei Konflikten - Mehrere Filter matchen einen Tenant → Filter mit höchster `priority` gewinnt - Bei gleicher Priority: chronologisch ältester Filter gewinnt (deterministisch) - Tenant-Override hat **immer** Vorrang vor jedem Filter ### Klartext-Hinweise - Filter ohne Criteria: *„Dieser Filter matcht aktuell alle Tenants — sicher gewollt? [Bestätigen]"* - Filter überschneidet sich mit höher-priorisiertem Filter komplett: *„Dieser Filter ist effektiv wirkungslos, weil Filter ‚X' mit höherer Priority dieselbe Menge matcht."* --- ## Block E — Code-Convention ### Lookup-Funktion ``` await tenantHasFlag(tenantId, 'beta_new_dashboard') ``` **Verhalten:** - Liefert Boolean - Wendet Auswertungs-Reihenfolge aus Block A an - Wirft, wenn `key` im Code referenziert wird, aber kein `FeatureFlag`-Eintrag existiert (Schema-Drift-Schutz) - Ergebnis wird Request-scoped gecacht (kein wiederholtes DB-Roundtrip pro Render) ### Code-Pattern ``` if (await tenantHasFlag(tenantId, 'beta_new_dashboard')) { // neuer Code-Pfad } else { // alter Code-Pfad } ``` **Ausschließlich auf Boolean-Werte** in Phase 1. Keine String-/Numeric-Variants. Phase 2 ggf. Multi-Variant. ### Ohne Tenant-Kontext - Hintergrund-Jobs / Worker, die ohne Tenant laufen, dürfen Flag-Lookup nur mit explizitem Tenant-Argument verwenden - Plattform-globale Flags (ohne Tenant-Bezug) sind in Phase 1 **nicht vorgesehen** — wenn nötig, einfach als `FeatureFlag` ohne Filter und mit `default_value` arbeiten und über separaten globalen Helper aufrufen --- ## Block F — Flag-Lifecycle ### Stages | Stage | Bedeutung | Default-Filter-Empfehlung | |---|---|---| | `beta` | Neu, einzeln aktiviert für Test-Tenants | `default_value=false`, einzelne Tenant-Overrides oder enger Filter | | `rollout` | Breit aktiviert über Filter, Beobachtungs-Phase | `default_value=false`, breite Filter (z.B. *„Tenants > 50 MA"*) | | `ga` | Always-On, Code-Cleanup geplant | `default_value=true`, Filter werden überflüssig | | `deprecated` | Abkündigung, Code wird entfernt | `default_value=false`, Tenants kriegen Klartext-Hinweis im Audit | ### Lifecycle-Wechsel **Workflow:** - Plattform-Admin wählt neuen Stage im Detail-View - Bestätigungs-Dialog mit Klartext-Beschreibung der Konsequenzen - Audit-Eintrag wird geschrieben **Edge-Cases:** - Wechsel auf `ga` mit aktiven Filter-Regeln, die `false` setzen: Klartext-Warnung *„Filter ‚X' setzt das Flag auf false — bei GA wird default_value=true ignoriert, falls Filter höher priorisiert sind."* - Wechsel auf `deprecated`: Klartext-Hinweis an Owner-Admin: *„Bitte Code-Cleanup einplanen — Owner: [Name]"* ### Archivierung - Nur für `ga` und `deprecated` Flags möglich - Aktive Tenant-Overrides werden bei Archivierung **nicht** automatisch gelöscht (Audit-Spur bleibt) - Klartext beim Archivieren mit aktiven Overrides: *„Es gibt noch X Tenant-Overrides — Archivierung verbirgt das Flag aus der Standard-Liste, Overrides bleiben funktional. Sicher fortfahren?"* --- ## Block G — Audit-Logging **Pro Flag-Änderung wird ein Audit-Eintrag geschrieben** (in Modul 21 oder dediziert in `AdminAuditLog`-Tabelle, siehe Modul 37). **Geloggt wird:** - Flag-Erstellung/-Änderung mit Diff (`label`, `description`, `default_value`, `lifecycle_stage`, `target_module`, `owner`) - Filter-Erstellung/-Änderung/-Löschung mit Diff - Tenant-Override-Erstellung/-Änderung/-Löschung mit Diff - Lifecycle-Stage-Wechsel - Archivierung/Reaktivierung **Pro Eintrag:** - Admin-User (Akteur) - Zeitstempel - Vorher/Nachher-Diff - Optionaler Note-Text vom Admin (z.B. *„Geerkens-Pilot-Aktivierung"*) **Sichtbarkeit:** - Im Detail-View des Flags als Audit-History-Sektion - In Modul 37 als Cross-Tenant-Audit-Log durchsuchbar --- ## Block H — Permissions ### Permission-IDs (Plattform-Admin-Scope, siehe Modul 37) | Permission | Erlaubt | |---|---| | `admin.feature_flags.read` | Flag-Liste + Detail einsehen | | `admin.feature_flags.write` | Flags anlegen/editieren, Filter und Tenant-Overrides verwalten | | `admin.feature_flags.lifecycle` | Lifecycle-Stage wechseln, archivieren | ### Bundle-Mapping | Bundle | Atomare Permissions | |---|---| | `admin.feature_flags.none` | (keine) | | `admin.feature_flags.viewer` | `read` | | `admin.feature_flags.operator` | `read` + `write` | | `admin.feature_flags.owner` | `read` + `write` + `lifecycle` | ### Tenant-User-Sicht (Phase 1) - **Keine Tenant-User-Routen** für Feature-Flags in Phase 1 - Tenants sehen aktive Flags nur indirekt: Features sind sichtbar oder nicht - Klartext-Hinweise für nicht-aktivierte Features kommen aus dem jeweiligen Modul (Subscription-Gate-Logik aus Modul 27 Block F.1, nicht aus Feature-Flags) --- ## Block I — Klartext-Hinweise / -Fehler - Lookup auf nicht-existierenden `key` im Code: *„Feature-Flag ‚beta_xy' ist nicht definiert — bitte im Admin-UI anlegen oder Code-Referenz korrigieren."* (wirft im Dev/Staging, loggt nur im Prod) - Tenant-Override anlegen für inaktiven/archivierten Tenant: *„Tenant ist im Status ‚deletion_pending' — Override anlegen?"* mit Bestätigung - Filter-Criteria führt zu 0 matchenden Tenants: dezenter Hinweis *„Aktuell matcht kein Tenant"* (kein Block, ist erlaubt — z.B. Filter für zukünftige Tenants) - Override mit `expires_at` in der Vergangenheit: Klartext beim Anlegen *„Expires-At liegt in der Vergangenheit — Override wird beim nächsten Cron-Lauf entfernt."* --- ## Block J — Phase 2 / spätere Features - **User-spezifische Flags** — Flag pro `(tenant_id, user_id)` statt nur pro Tenant - **Tenant-self-service-Flags** — Tenant-Admin sieht in `/{tenant}/admin/labs/` Toggle *„Beta-Features anzeigen"* und kann ausgewählte Flags selbst aktivieren (Whitelist im `FeatureFlag` Definition: `tenant_self_service_enabled` Boolean) - **Multi-Variant-Flags** — String-/Numeric-Werte (A/B/C-Tests, nicht nur Boolean) - **Rollout-Prozentsatz** — *„aktiviere für 25% der Tenants"* mit deterministischem Hash - **Erweiterte Filter-Kriterien** — Region, MRR-Schwelle, Custom-Tags am Tenant - **Schedule-basierte Aktivierung** — *„aktiviere Flag X automatisch ab 1.6.2026"* - **Telemetrie pro Flag** — wie viele User haben ein Flag-getriggertes Feature genutzt (Verbindung zu Analytics) --- ## Block K — Architektur-Vorschriften (Querschnitt) - **AV #6 — Audit-Trail-Default:** alle Flag-Änderungen geloggt (Block G) - **AV #7 — Feature-Flag-Hülle:** dieses Modul **ist** die Implementierung dieser Architektur-Vorschrift; alle neuen Features in Phase 1 werden mit Flag eingeführt - **LP-10 — Klartext-Diagnostik:** alle Fehler-Cases mit menschenlesbarem Hinweis (Block I) - **LP-9 — Spec-Tiefe:** keine UI-Layouts, nur Anforderungen --- ## Detail-Spec-Status: DRAFT Erste Detail-Spec für Modul 32. Bewusst kompakt gehalten — Modul ist klein, Phase 1 minimal. **Offene Detail-Punkte (nicht-blockierend):** - Konkrete Permission-IDs final mit Modul 37 abstimmen - Caching-Strategie pro Request (in-memory vs. Redis-shared) im Implementierungs-Schritt - Schema-Drift-Check: ob bei Code-Deploy unbekannte Flag-Keys automatisch geseeded werden sollen (Implementierungs-Detail) - Subframe-UI-Designs separat