wiki/b-reference/platform/navigation.md

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.

Endpoint: GET /api/navigation mit Antwort u. a. language, blocks[] (implementiert in routeSystem.py, gemountet als navigationRouter).

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 (ui-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.*.
• billing: Billing-Seiten — page.system.*, ObjectKeys ui.system.*.
• basedata: Stammdaten (z. B. Prompts, Dateien) — 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); Response-Felder sind uiLabel/uiPath (kein icon in der API). Static Blocks können Subgruppen (verschachtelte items[]) enthalten, nicht nur flache Listen.

Dynamic Block (Features)

• id: typischerweise features
• Hierarchie: Mandat → Feature-Typ (uiComponent z. B. feature.trustee) → Instanz → Views (page.feature.<code>.<view>)
• 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.<name>, ui.admin.<name>, ui.feature.<code>.<view>. 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 — GET /api/navigation (navigationRouter)
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	ui-nyla/src/config/pageRegistry.tsx — 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>, page.admin.<page>, page.feature.<feature>.<view>, Feature-Gruppe feature.<code>.
• Drift sichtbar machen: Unbekannte Codes im UI als Fehler anzeigen, nicht still ignorieren.
• Vollständiges API-Konzept und Migrationsphasen: wiki/z-archive/concepts/Navigation-API-Konzept.md.