345 lines
14 KiB
Markdown
345 lines
14 KiB
Markdown
---
|
||
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
|