Architektur: durchgängige Feature-/Entitlement-Schicht (Ist → Zielbild, Phasen) #68

New Issue

Lars · 2026-04-08T12:43:35+02:00

Lars commented

2026-04-08 12:43:35 +02:00

Kontext

Das Projekt hat ein funktionierendes Kernmodell für Subscriptions: Feature-Registry (DB), Tier-Limits, User-Overrides und check_feature_access (Backend). Parallel existieren verteilte Entscheidungen in UI und Code: Nicht jede sichtbare oder klickbare Fläche nutzt dieselbe Logik, und welche UI-Bausteine faktisch an welchen Features „hängen“, ist oft nicht explizit dokumentiert oder nur implizit in Komponenten/Routern erkennbar.

Bereits konsistenter: Dashboard-Widgets: widget_catalog.py + optional DB-Zuordnung Widgets × Features (AND), widget_id_allowed / apply_entitlements_to_layout_dict.

Ist-Zustand (hybrid)

Backend: Zentrale Berechtigung über check_feature_access; API-Endpunkte teils mit Feature-Enforcement (403), teils ohne.
Frontend: Unterschiedliche Muster: manchmal explizite Checks, manchmal nur Daten/Navigation, teils keine einheitliche FeatureGate-Schicht.
Transparenz: Keine einzige „Surface Map“ (Seite / Nav-Eintrag / Panel → Feature-ID(s)); Zuordnung von Funktionen/visuellen Elementen zu Features überwiegend nicht wie bei Widgets administrierbar.
Definition „Feature“: Namen/Metadaten in der DB, fachliche Verwendung und UI-Anbindung oft weiter Code-nah.

Zielbild (saubere Architektur)

Eine durchgängige Entitlement-Schicht (konzeptionell „Capability“): dieselbe Entscheidungsgrundlage für „darf Nutzer X Feature Y (nutzen/sehen)?“ im Backend und als schmale API fürs Frontend (z. B. gebündelte Übersicht oder gezielte Checks).
Explizite Zuordnung UI → Feature(s): dokumentierte oder registry-basierte Zuordnung (Konvention „Nav/Capture/Seite/Block ↔ feature_id(s)“), damit Transparenz und Reviews möglich sind.
Einheitliche UI-Muster: wenige Hilfsmittel (z. B. Hook + Wrapper), statt pro Komponente neu erfinden; Fehlverhalten (gesperrt vs. leer vs. Upsell) bewusst festlegen.
Kein zweites Parallel-Feature-System: weiterhin Registry + Tiers als Quelle der Wahrheit; feinere Gates über Kombination/AND wie bei Widgets, nicht duplizierte „Modul-Features“ ohne Klärung.

Vorschlag Phasen (erste Überlegung, nicht final)

Phase	Inhalt	Hinweis
P0 Zielbild & Konvention	Kurzspec: Begriffe (Feature vs. Capability vs. Surface), AND/OR-Regeln, Fehlerbilder (403, ausgeblendet, deaktiviert + Tooltip).	Doku + Review, kein Big-Bang.
P1 Pilot vertikal	Eine eng begrenzte Fläche end-to-end umbauen: z. B. Capture-Hub + Hauptnavigation (+ optional eine Liste-Seite): eine zentrale Nutzung von `check_feature_access` / gebündelter Feature-API + `FeatureGate` o. ä.	Lernkurve, Muster für das Team.
P2 Ausbreitung	Weitere Screens/Module nachziehen; Hotspots priorisieren (teure oder sicherheitsrelevante Aktionen).	Iterativ, Altcode ersetzen.
P3 Optional erweitern	Weitere Surfaces administrierbar machen (analog Widget-Zuordnung), nur wenn fachlich nötig.	Vermeidung von Over-Engineering.

Akzeptanz (gesamt, grob)

Neue UI-Stücke, die an ein Feature gebunden sind, folgen dem vereinbarten Muster und sind in der Surface-Zuordnung (oder Registry) nachvollziehbar.
Keine sicherheitsrelevante Aktion nur durch „UI verstecken“ ohne Backend-Check (bestehendes Prinzip beibehalten/verstärken).

Referenzen (Code)

auth.check_feature_access · Feature-Registry / Tier-Limits / User-Restrictions
dashboard_widget_entitlements.py · widget_feature_requirements_db.py · Admin „Widgets × Features“

Issue zur Sicherung des Zielbilds; Umsetzung in Commits/Teil-Issues splitten.

## Kontext Das Projekt hat ein funktionierendes **Kernmodell** für Subscriptions: Feature-Registry (DB), Tier-Limits, User-Overrides und `check_feature_access` (Backend). Parallel existieren **verteilte Entscheidungen** in UI und Code: Nicht jede sichtbare oder klickbare Fläche nutzt dieselbe Logik, und welche UI-Bausteine faktisch an welchen Features „hängen“, ist oft **nicht explizit** dokumentiert oder nur implizit in Komponenten/Routern erkennbar. **Bereits konsistenter:** Dashboard-Widgets: `widget_catalog.py` + optional DB-Zuordnung **Widgets × Features** (AND), `widget_id_allowed` / `apply_entitlements_to_layout_dict`. --- ## Ist-Zustand (hybrid) - **Backend:** Zentrale Berechtigung über `check_feature_access`; API-Endpunkte teils mit Feature-Enforcement (403), teils ohne. - **Frontend:** Unterschiedliche Muster: manchmal explizite Checks, manchmal nur Daten/Navigation, teils keine einheitliche `FeatureGate`-Schicht. - **Transparenz:** Keine einzige „Surface Map“ (Seite / Nav-Eintrag / Panel → Feature-ID(s)); Zuordnung von **Funktionen/visuellen Elementen** zu Features überwiegend **nicht** wie bei Widgets administrierbar. - **Definition „Feature“:** Namen/Metadaten in der DB, fachliche Verwendung und UI-Anbindung oft weiter **Code-nah**. --- ## Zielbild (saubere Architektur) 1. **Eine durchgängige Entitlement-Schicht** (konzeptionell „Capability“): dieselbe Entscheidungsgrundlage für „darf Nutzer X Feature Y (nutzen/sehen)?“ im Backend und als schmale API fürs Frontend (z. B. gebündelte Übersicht oder gezielte Checks). 2. **Explizite Zuordnung UI → Feature(s):** dokumentierte oder registry-basierte Zuordnung (Konvention „Nav/Capture/Seite/Block ↔ feature_id(s)“), damit **Transparenz** und Reviews möglich sind. 3. **Einheitliche UI-Muster:** wenige Hilfsmittel (z. B. Hook + Wrapper), statt pro Komponente neu erfinden; Fehlverhalten (gesperrt vs. leer vs. Upsell) bewusst festlegen. 4. **Kein zweites Parallel-Feature-System:** weiterhin Registry + Tiers als Quelle der Wahrheit; feinere Gates über Kombination/AND wie bei Widgets, nicht duplizierte „Modul-Features“ ohne Klärung. --- ## Vorschlag Phasen (erste Überlegung, nicht final) | Phase | Inhalt | Hinweis | |-------|--------|---------| | **P0 Zielbild & Konvention** | Kurzspec: Begriffe (Feature vs. Capability vs. Surface), AND/OR-Regeln, Fehlerbilder (403, ausgeblendet, deaktiviert + Tooltip). | Doku + Review, kein Big-Bang. | | **P1 Pilot vertikal** | Eine eng begrenzte Fläche end-to-end umbauen: z. B. **Capture-Hub** + **Hauptnavigation** (+ optional eine Liste-Seite): eine zentrale Nutzung von `check_feature_access` / gebündelter Feature-API + `FeatureGate` o. ä. | Lernkurve, Muster für das Team. | | **P2 Ausbreitung** | Weitere Screens/Module nachziehen; Hotspots priorisieren (teure oder sicherheitsrelevante Aktionen). | Iterativ, Altcode ersetzen. | | **P3 Optional erweitern** | Weitere Surfaces administrierbar machen (analog Widget-Zuordnung), nur wenn fachlich nötig. | Vermeidung von Over-Engineering. | --- ## Akzeptanz (gesamt, grob) - Neue UI-Stücke, die an ein Feature gebunden sind, folgen dem **vereinbarten Muster** und sind in der **Surface-Zuordnung** (oder Registry) nachvollziehbar. - Keine sicherheitsrelevante Aktion nur durch „UI verstecken“ ohne Backend-Check (bestehendes Prinzip beibehalten/verstärken). --- ## Referenzen (Code) - `auth.check_feature_access` · Feature-Registry / Tier-Limits / User-Restrictions - `dashboard_widget_entitlements.py` · `widget_feature_requirements_db.py` · Admin „Widgets × Features“ --- *Issue zur Sicherung des Zielbilds; Umsetzung in Commits/Teil-Issues splitten.*

Sign in to join this conversation.