shinkan-jinkendo/docs/working/RBAC_ENFORCEMENT_ROADMAP.md

RBAC, Kontingente & Enforcement — Roadmap

Stand: 2026-06-07 · App 0.8.199 · Schema 20260606083
Bezüge: MEMBERSHIP_RBAC_DECISIONS_2026-06.md, CAPABILITY_CATALOG.v1.md, CLUB_MEMBERSHIP_AND_FEATURES.v1.md

Diese Roadmap bündelt was fertig ist, was als Standard gilt und was noch fehlt — ohne Insellösungen pro Feature.

---

1. Architektur-Standard (verbindlich)

Request-Kette (Ziel)

Auth → Account-State → TenantContext
  → probe_capability (Recht)
  → probe_club_feature_access (Kontingent)
  → Governance (Objekt)
  → Business-Logik
  → consume_club_feature_with_usage + merge_feature_usage_into_response

Frontend-Standard

• GET /api/me/entitlements = einzige Quelle für Rechte + Kontingente in der UI
• request() synchronisiert feature_usage aus API-Responses automatisch (featureUsageSync.js)
• Keine parallelen if (club_admin) für Sicherheit (UX-Fallback nur übergangsweise)

Admin

• Rollen & Rechte (/admin/rights): Matrix mit Klartext zuerst, technische ID darunter
• Umsetzungsstand pro Recht: capability_enforcement_audit.py → Feld enforcement in der Matrix

---

2. Ist-Stand nach Meilenstein

Meilenstein	Inhalt	Status
M1	Feature-Schema, Pläne, Seeds	✅
M2	Feature-Probe + JSON-Log	✅
M3	Capabilities, Account-Lifecycle, Tenant	✅ (Legacy parallel)
M4	/me/entitlements, Badge (KI)	✅ teilweise
M5	Hard-Block + vollständiger Consume	⚠️ nur ai_calls consume; Enforce aus
M6	Admin UI Rollen & Rechte	⚠️ Matrix + Kontingente; kein Plan-/Rollen-CRUD
M7	Vereinsgründung beantragen	✅ Basis + Capabilities
M8	Stripe	❌
Sync	feature_usage + request()	✅

---

3. Roadmap (empfohlene Reihenfolge)

Phase 1 — Durchsetzung sichtbar machen (kurz)

#	Paket	Lieferumfang	Aufwand
1.1	Admin-Matrix UX	Alle Rechte, Haken-Matrix, Umsetzungs-Badge	✅ 2026-06-07
1.2	Doku-Sync	Diese Roadmap, MEMBERSHIP_RBAC §2	✅
1.3	Audit pflegen	Bei jedem probe_capability → capability_enforcement_audit.py	laufend

Phase 2 — Kontingente vollständig (M5)

#	Paket	Lieferumfang
2.1	Consume erweitern	exercises, exercise_media nach Standard-Helfer
2.2	Badges	FeatureUsageBadge an Create/Upload, nicht nur KI
2.3	Dev: Enforce	CLUB_FEATURE_ENFORCE=1 auf Dev, Free ai_calls=0 testen
2.4	Prod-Rollout	Enforce schrittweise; Kommunikation an Vereine

Phase 3 — Capabilities an alle Endpoints (C3–C4)

#	Paket	Lieferumfang
3.1	Endpoint-Audit	ACCESS_LAYER_ENDPOINT_AUDIT.md — jeder Schreib-Pfad
3.2	probe_capability	exercises.update/delete, planning.*, org.*, Medien-Bibliothek, …
3.3	CAPABILITY_ENFORCE=1	Nach Audit auf Dev, dann Prod
3.4	Legacy abbauen	can_plan_in_club nur noch als Fallback, dokumentiert

Phase 4 — Frontend auf Entitlements (Phase E)

#	Paket	Lieferumfang
4.1	Navigation	Menüpunkte aus hasCapability()
4.2	Buttons	KI, Anlegen, Löschen, Planung — aus Entitlements
4.3	Rollen-Labels	Anzeige club_roles statt technischer IDs

Phase 5 — Admin & Produkt (M6 voll)

#	Paket	Lieferumfang
5.1	Pläne-CRUD	Neue Vereinspläne anlegen, nicht nur Seed
5.2	Systemrolle Co-Trainer	Seed + Matrix
5.3	Trainer-Budgets	v2 — club_member_feature_budgets

Phase 6 — Abrechnung (M8)

Stripe / Rechnung — bewusst nach funktionierendem Enforce.

---

4. Superadmin & Vereinsrechte (Entscheidung)

Kurz: Superadmin braucht keine Vereinsrolle club_admin für die meiste Arbeit.

Ebene	Verhalten
Capabilities (neu)	admin und superadmin = platform_admin_bypass für alle Vereins-Capabilities (capabilities.py) — unabhängig von club_member_roles
Legacy-Helfer	can_plan_in_club, can_manage_club_org → True für Plattform-Admin ohne Mitgliedschaft
Mandant	Aktiver Verein über X-Active-Club-Id / active_club_id — keine Mitgliedschaft nötig für Plattform-Admin
Kontingente	Superadmin: Quota-Bypass (Capability-Grant); zählt nicht gegen Vereins-Kontingent
Ausnahmen Legacy	Einzelne Pfade prüfen noch nur has_club_role(…, 'club_admin') ohne Plattform-Bypass — z. B. Löschen von visibility=club-Übungen. → Phase 3 bereinigen

Empfehlung: Superadmin nicht zwingend als club_admin in jeden Verein eintragen. Optional Mitgliedschaft nur für realistische Audit-Tests oder Vereinsorga-Simulation. Produktiv: Mandant per Club-Switcher wählen.

admin (Portal-Admin): gleicher Capability-Bypass für Vereins-Funktionen; Portal-Capabilities nur mit explizitem Grant in der Matrix.

---

5. Vereinsrollen-Matrix — Semantik (Admin-UI)

Zustand	Bedeutung	UI
Keine Grants in DB	Alle aktiven Mitglieder (wenn min_account_state reicht)	Zellen zeigen „alle“
Mindestens ein Grant	Nur angehakte Rollen	Checkboxen
„Alle Mitglieder“	Löscht alle Grants der Zeile	Zurück zum offenen Zustand

Das ersetzt das frühere Formular „Vereinsrollen-Grant hinzufügen“, das nur bereits eingeschränkte Rechte sichtbar machte.

---

6. Offene Lücken (Checkliste)

• CAPABILITY_ENFORCE=1 in Produktion
• CLUB_FEATURE_ENFORCE=1 in Produktion
• Consume für alle Features mit Verbrauch (nicht nur ai_calls)
• probe_capability auf >90 % der Schreib-Endpoints
• Frontend ohne Legacy-Rollen-Guards
• Multipart-Uploads an featureUsageSync anbinden
• Legacy-Löschpfade mit Plattform-Bypass harmonisieren
• HANDOVER.md / PROJECT_STATUS Versionsstand aktualisieren

---

7. Referenzen

Datei	Zweck
backend/capability_enforcement_audit.py	Matrix-Badges „angebunden / Legacy“
backend/club_features.py	Consume-Standard
frontend/src/utils/featureUsageSync.js	Entitlements-Sync
frontend/src/pages/AdminRightsPage.jsx	Konfiguration

Changelog

• 2026-06-07: Initial nach Session Rollen/Kontingente — Standard, Roadmap Phasen 1–6, Superadmin-Klärung, Matrix-Semantik.