# Navigation API ## Überblick Die Navigation-API ist die **Single Source of Truth** für die Navigationsstruktur: Das **Gateway** entscheidet, welche Einträge ein Benutzer sieht; das **UI** rendert nur die gelieferte Struktur — **keine** parallele Berechtigungslogik im Frontend für die Navigation. Die API liefert **keine** Darstellungsassets (Icons, CSS); stattdessen **UI-Komponenten-Codes** (`uiComponent`), die im Client (z. B. `PAGE_REGISTRY`) auf Komponenten gemappt werden. Einträge ohne Berechtigung erscheinen **nicht** im Baum (kein `hasAccess: false`). Unbekannte `uiComponent`-Codes sollen im UI **sichtbar als Fehler** gemeldet werden, damit Gateway/UI-Drift auffällt. **Ziel-Endpoint (Konzept):** `GET /api/navigation` mit Antwort u. a. `language`, `blocks[]`. **Ist-Stand (Audit):** Statische Navigation u. a. über `GET /api/system/navigation` mit `sections` — Migration auf kombinierten Endpoint und `blocks`-Schema ist im Konzept dokumentiert. **Personalisierung:** Sortierung über numerisches `order`; User-Overrides in Settings (`navOrder`), Merge im Gateway: `EffektiveOrder = User-Override ?? Default ?? 50`. Update-Konzept: `PUT /api/user/settings/navOrder`. Aktuelle UI-Bezüge im Kontext: `MandateNavigation`, Hook `useNavigation` (`frontend_nyla`). ## Block-Struktur Die Antwort besteht aus einer geordneten Liste von **Blocks**: - **`type`:** `static` oder `dynamic` - **`id`:** z. B. `system`, `workflows`, `basedata`, `admin`, `features` - **`title`:** Anzeige-Gruppentitel - **`order`:** Reihenfolge der Blöcke **Static Block:** enthält `items[]` mit Navigationsknoten auf System-/Admin-/Basisdaten-Seiten. **Dynamic Block:** enthält `mandates[]` → je Mandat `features[]` → `instances[]` → `views[]`. Der dynamische Block fehlt, wenn der User keine zugängliche Feature-Instanz hat. **Item-Felder (Static / Views):** | Feld | Bedeutung | |------|-----------| | `uiComponent` | Eindeutiger Code für das UI-Mapping | | `uiLabel` | Text in der gewählten Sprache | | `uiPath` | URL-Pfad | | `order` | Sortierung innerhalb der Ebene | | `objectKey` | Vollqualifizierter RBAC-Bezug (UI-Kontext), z. B. `ui.system.home` | ## Static Blocks (System, Basedata, Admin) Typische **static** Blöcke im Konzept: - **`system`:** mandatsübergreifende Systemseiten (z. B. Home, Einstellungen) — `page.system.*`, ObjectKeys `ui.system.*`. - **`workflows`:** Workflow-bezogene Systemseiten (z. B. Playground, Chat-Liste) — ebenfalls `page.system.*` / `ui.system.*` im Beispiel. - **`basedata`:** Stammdaten (z. B. Prompts, Dateien) — weiterhin `page.system.*` mit Pfaden unter `/basedata/...`. - **`admin`:** Administration — `page.admin.*`, ObjectKeys `ui.admin.*` (Benutzer, Mandanten, …). Die exakte Liste und Default-`order` stammen aus der Gateway-Konfiguration (`NAVIGATION_SECTIONS` in `mainSystem.py` laut Analyse — Felder teilweise noch `label`/`path`/`icon`; Zielmapping: `uiLabel`/`uiPath`, ohne `icon` in der API). ## Dynamic Block (Features) - **`id`:** typischerweise `features` - Hierarchie: **Mandat** → **Feature-Typ** (`uiComponent` z. B. `feature.trustee`) → **Instanz** → **Views** (`page.feature..`) - Pfade enthalten Mandats- und Instanz-IDs (siehe Konzeptbeispiele) - Sortierung auf allen Ebenen über jeweiliges `order` (Mandat, Feature, Instanz, View) ## RBAC-Integration - **`objectKey`** in Navigationsitems entspricht dem **`item`**-String im **UI-Kontext** der Access Rules (vollqualifiziert), z. B. `ui.feature.trustee.dashboard`. - Navigation-Endpoint wendet **Permission-Filter** an, bevor die Response gebaut wird — nur erlaubte Knoten sind enthalten. - Konventionen (Kontext UI): `ui.system.`, `ui.admin.`, `ui.feature..`. Für DATA/RESOURCE siehe übergreifendes RBAC-Dokument (`data.*`, `resource.*`). - **Inkonsistenz-Hinweis (Audit):** Template-Rollen dürfen keine Kurz-`item`-Namen (`dashboard`) nutzen, wenn `objectKey` vollqualifiziert ist — `item` und Navigation müssen übereinstimmen. ## Schlüssel-Dateien | Schicht | Pfad / Artefakt | |---------|------------------| | Statische Sektionen (Gateway) | `mainSystem.py` — `NAVIGATION_SECTIONS` | | Navigation-Route | `routeSystem.py` — Endpoint-Evolution `/api/system/navigation` → `/api/navigation` | | Feature-Views / Template-Rollen | z. B. `mainTrustee.py`, `mainRealEstate.py` — `UI_OBJECTS`, `TEMPLATE_ROLES` | | Admin-Feature-Permission (Ist teils feature-spezifisch) | `routeAdminFeatures.py` — z. B. `_deriveViewPermissions` | | Frontend: Navigation | `MandateNavigation.tsx`, `useNavigation` | | Frontend: Registry (Ziel) | `frontend_nyla/src/config/pageRegistry.ts` — `PAGE_REGISTRY`, `FEATURE_REGISTRY` | | Legacy-Duplikate (Audit) | `mandate.ts` — `FEATURE_REGISTRY` / View-Definitionen parallel zum Backend | ## Regeln / Invarianten - **Backend autoritativ:** Keine eigenständige Zusammenstellung der Navigationsstruktur im UI aus mehreren Quellen ohne Gateway-Abgleich (Zielzustand: ein Endpoint, ein Baum). - **Nur sichtbare Knoten:** Keine negativen Sichtbarkeitsflags in der Response. - **Sortierung:** ausschließlich vom Gateway; das UI sortiert empfangene Listen nicht erneut. - **`uiComponent`-Konventionen:** `page.system.`, `page.admin.`, `page.feature..`, Feature-Gruppe `feature.`. - **Drift sichtbar machen:** Unbekannte Codes im UI als Fehler anzeigen, nicht still ignorieren. - Vollständiges API-Konzept und Migrationsphasen: `wiki/concepts/Navigation-API-Konzept.md`.