shinkan-jinkendo/docs/jinkendo-family/design-principles/RIGHTS_REGISTRY_DESIGN_PRINCIPLES.md

Rights Registry – Designprinzipien (Extraktion)

Status: Analyse / Arbeitspapier
Stand: 2026-07-04
Geltungsbereich: Modul „Rights Registry“ — Capabilities & Features zur Laufzeit registrieren

Serie: Designprinzipien für Produktfamilie · Shinkan Dokument 3 von 15
Mitai-Vergleich: REGISTRY_PLUGIN_DESIGN_PRINCIPLES.md (#4)

Kernkomponenten:

Bereich	Pfade
Registry-Kern	backend/rights_registry.py
Modul-Registrierungen	backend/rights_registrations/ (exercises.py, planning.py, platform.py, club_creation.py)
Startup-Sync	Import in backend/main.py
Tests	backend/tests/test_rights_registry.py

---

Modul

Rights Registry (Registry-first für Capabilities & Features)

Module deklarieren bei Implementierung, welche Rechte und Kontingente sie anbieten. Beim App-Start werden Definitionen in die DB synchronisiert (capabilities, features, Default-Grants).

---

Fachliche Verantwortung

1. Runtime-Registrierung — register_capability(), register_feature() vor DB-Sync.
2. Modul-Ownership — Jedes Feature/Capability trägt module-Feld für Admin-Filter „Rollen & Rechte“.
3. Default Club Grants — Rollen → Capability-Mapping bei Erst-Sync.
4. Kein vollständiger Vorab-Katalog in SQL-Migration — nur was Module wirklich liefern.

---

Designprinzipien

1. Registry-first statt Migrations-Monolith

Prinzip	Neue Rechte erscheinen durch Code-Registrierung + Startup-Upsert — nicht durch manuelle 079-Katalog-Migration pro Feature.
Begründung	Modul und Recht entstehen zusammen; weniger vergessene Katalog-Einträge.
Quelle	rights_registry.py; Docstring; rights_registrations/
Tragfähigkeit	hoch
Einschränkung	Erste Basismigration seedet noch initiale Zeilen.

2. Modul-Datei pro Domäne

Prinzip	rights_registrations/exercises.py registriert nur Übungs-Rechte; Planung/Platform analog.
Begründung	Ownership klar; Merge-Konflikte lokalisiert.
Quelle	rights_registrations/__init__.py
Tragfähigkeit	hoch
Einschränkung	Import-Reihenfolge muss in main.py garantiert sein.

3. Frozen Dataclass-Definitionen

Prinzip	CapabilityRegistration / FeatureRegistration als immutable @dataclass(frozen=True).
Begründung	Keine nachträgliche Mutation nach Registrierung.
Quelle	rights_registry.py
Tragfähigkeit	hoch
Einschränkung	—

4. Validierung an der Registrierungsgrenze

Prinzip	register_* wirft bei fehlendem id oder module.
Begründung	Fehler beim Import/Startup, nicht erst im Admin-UI.
Quelle	rights_registry.py
Tragfähigkeit	hoch
Einschränkung	Keine Schema-Validierung für limit_type/reset_period zur Compile-Zeit.

5. DB als persistierter Katalog, Code als SSoT für neue IDs

Prinzip	Startup sync_rights_registry_to_db() upsertet aus In-Memory-Registry.
Begründung	Admin-UI liest DB; Entwickler erweitern Code-Registry.
Quelle	rights_registry.py; main.py
Tragfähigkeit	hoch
Einschränkung	Deaktivierte Capabilities in DB vs. fehlende im Code — Reconcile-Policy dokumentieren.

6. Default Grants als Code-Daten

Prinzip	default_club_grants: (role_code, capability_id) pro Capability.
Begründung	Neue Module bringen sinnvolle Standard-Rollen mit.
Quelle	rights_registrations/exercises.py
Tragfähigkeit	mittel
Einschränkung	Admin-Overrides in DB können bei Re-Sync überschrieben werden — ON CONFLICT-Verhalten beachten.

---

Nicht übernehmen

1. Capabilities nur in SQL-Migration pflegen — driftet vom implementierten Modul weg.
2. Registrierung ohne Endpoint-Verdrahtung — Spec: „nur Rechte mit echter Endpoint-Verdrahtung“.
3. Zweite Registry-Philosophie für Custom Roles — gleiche Capability-IDs wiederverwenden (Plan Stufe E).

---

Verwandte Dokumentation

• CAPABILITY_ENTITLEMENT_DESIGN_PRINCIPLES.md
• CAPABILITY_CATALOG.v1.md
• DESIGN_PRINCIPLES_INDEX.md