85 lines
5.5 KiB
Markdown
85 lines
5.5 KiB
Markdown
<!-- status: canonical -->
|
|
<!-- lastReviewed: 2026-04-05 -->
|
|
<!-- verifiedAgainst: gateway (codebase audit 2026-03-29) -->
|
|
|
|
# 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.<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` — 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>`, `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/concepts/Navigation-API-Konzept.md`.
|