115 lines
4.5 KiB
Markdown
115 lines
4.5 KiB
Markdown
|
# 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](file:///c:/Dev/mitai-jinkendo/.claude/docs/technical/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_ENTITLEMENT_DESIGN_PRINCIPLES.md)
|
|||
|
|
- [CAPABILITY_CATALOG.v1.md](../../../.claude/docs/technical/CAPABILITY_CATALOG.v1.md)
|
|||
|
|
- [DESIGN_PRINCIPLES_INDEX.md](./DESIGN_PRINCIPLES_INDEX.md)
|