Eigene Navigations-Kacheln (CustomNavigationTiles)

Zweck

CustomNavigationTile ergaenzt die SpeamCore-Startseite um eigene Kacheln, die Anwender per Klick zu externen Tools oder erweiterten Workflows fuehren. Pro Kachel werden Icon, Name, Typ (url oder advanced) und — bei url — die Ziel-URL und das Open-Verhalten gepflegt. Über die Sub-Route Assignments wird gesteuert, für welche Mitarbeiter/Rollen/Abteilungen die Kachel sichtbar ist.

Voraussetzungen

- Berechtigung `view:CustomNavigationTile` und `create:CustomNavigationTile`. - Für Assignment-Sub-Liste: `view:CustomNavigationTileAssignment`.

Berechtigungen (CASL)

Action	Subject	Wirkung	Keycloak-Rolle
view	FE_CustomNavigationTile, CustomNavigationTile	Liste/Detail aufrufbar	—
create/update/delete	CustomNavigationTile	Pflegen	APP_SPEAMCORE_CREATE/UPDATE/DELETE_CUSTOM_NAVIGATION_TILE
view	CustomNavigationTileAssignment	Sub-Liste Zuweisungen	APP_SPEAMCORE_VIEW_CUSTOM_NAVIGATION_TILE_ASSIGNMENT

Schritt-für-Schritt-Anleitung

URL-Kachel

1. Eigene Kacheln (/custom-navigation-tiles) → + Neu.
2. name (z. B. „Microsoft Teams").
3. Icon wählen — Klick auf das Icon-Feld öffnet den Icon-Selector (siehe Abschnitt unten). Das Icon wird als Bezeichner aus einer der 31 react-icons-Bibliotheken gespeichert (z. B. TbBrandTeams, FaMicrosoft).
4. type = url.
5. url setzen (z. B. https://teams.microsoft.com).
6. urlOpenMode wählen (new_tab, same_tab, popup).

Advanced-Kachel

type = advanced schaltet die URL-Felder aus und aktiviert die Sub-Route /custom-navigation-tiles/:id/advanced mit individueller Konfiguration (z. B. parametrisierte Aktionen). Advanced-Kacheln können eigenen Plugin-Code ausführen und dabei auf das Advanced-Tile Plugin SDK zugreifen — siehe Abschnitt unten.

Icon-Selector mit Cross-Library-Suche

Der Icon-Selector öffnet sich als zentriertes Modal mit zwei Sichten:

• Library-Auswahl (Default) — listet die 31 verfügbaren Icon-Bibliotheken (Tabler, Font Awesome 5/6, Material Design, Ionicons, Heroicons 1/2, Remix, BoxIcons, Bootstrap, Ant Design, Feather, Lucide, Simple Icons, Phosphor, GitHub Octicons, Grommet, Game Icons, Circum, css.gg, Devicons, Flat Color, IcoMoon, Line Awesome, Radix, Simple Line, Themify, Typicons, VS Code, Weather).
• Library-Browse — nach Klick auf eine Bibliothek werden ihre Icons in einem 10-spaltigen Grid mit Infinite-Scroll geladen.

In das Suchfeld oben kann der User direkt einen Begriff eingeben — die Suche läuft dann parallel über alle Bibliotheken und gruppiert die Treffer nach Library (max. 36 Treffer pro Library, damit das Modal flüssig bleibt). Beim ersten Treffer einer Library wird diese in einen Modul-Cache geladen — Folgesuchen sind dann sofort.

Das gewählte Icon wird als String (Prefix + Name) gespeichert, z. B. TbFlame. Zum Rendern in der App nutzt SpeamCore die Komponente DynamicIcon, die die Bibliothek lazy lädt — alle ~10.000 react-icons sind damit einsetzbar.

Zuweisungen pflegen

Eine Custom-Tile kann an drei Zieltypen zugewiesen werden:

Typ	Wirkung
Mitarbeiter	Kachel nur für diesen Account sichtbar
Abteilung	Kachel für alle Mitarbeiter mit aktiver Rolle in der Abteilung
Rolle	Kachel für alle Mitarbeiter mit dieser Rolle

Die Pflege geht über zwei Wege:

• Tile-Details → Tab Assignments — listet alle bestehenden Zuweisungen (Mitarbeiter, Abteilung, Rolle) mit auflösbaren Namen. Neue Zuweisungen über den Button + Zuweisen und einen Picker mit Mehrfach-Auswahl.
• Rolle-Details → Tab Custom Tiles (neu in Welle 114) — am Rolle-Detail steht ein Tab mit Count-Badge, der die der Rolle zugewiesenen Custom-Tiles auflistet. Über den Tile-Picker (paginiert, bereits zugewiesene sind deaktiviert) lassen sich weitere Tiles zur Rolle hinzufügen.

Beide Wege schreiben in dieselbe Tabelle CustomNavigationTileAssignment mit den Feldern customNavigationTileId, parentType (Employee / Department / Role) und parentId. Die Namens-Auflösung der Zielobjekte passiert im Frontend.

Toolbar (Detail-Seite)

Schlanke Toolbar oben rechts:

Icon	Aktion (aria-label)	CASL	Wirkung
←	Zurückgehen	—	Zurück zur Liste.
🏠	Zur Startseite gehen	—	Springt auf das Dashboard / /.
⏮/◀/▶/⏭	Pagination	—	Navigation durch die gefilterte Liste — Massen-Bearbeitung ohne Liste-Sprung.

Globale Floating-Drawer (links)

Wie auf jeder Detail-Seite verfuegbar — siehe Floating-Quickbar:

• KAL. (Mini-Kalender)
• ZEIT (Persoenliche Wochen-Arbeitszeit)
• ARBEIT (Eigene bevorstehende Aufträge)

Felder und Eingaben

Feldname	Pflicht	Datentyp	Wirkung beim Ausfuellen	Voraussetzung
name	ja	String	Anzeigename auf der Kachel.	—
icon	nein	String	react-icons-Bezeichner aus einer der 31 unterstützten Libraries (z. B. FaMicrosoft, TbExternalLink, LuRocket). Über den Icon-Selector mit Cross-Library-Suche auswählbar.	—
type	ja	ENUM (url, advanced)	Bestimmt Konfigurations-Modus.	—
url	ja bei type = url	String	Ziel-URL.	type = url.
urlOpenMode	ja bei type = url	ENUM (new_tab, same_tab, popup)	Klick-Verhalten.	type = url.

Advanced-Tile Plugin SDK (Juni 2026)

Advanced-Kacheln (type = advanced) führen eigenen Plugin-Code aus. Das Plugin SDK stellt diesem Code geprüfte Plattform-Funktionen bereit — ohne dass die Kachel eigene API-Schlüssel oder Tokens verwalten muss. SpeamCore reicht den Kontext des angemeldeten Nutzers durch (Profil, Berechtigungen, Mandanten-Branding, Sprache), sodass jeder SDK-Aufruf mit dessen Rechten läuft.

SDK-Namespace	Funktionen	Zweck
SDK.ai	complete(), prompt(), extractDocument()	KI-Textvervollständigung und PDF-/Bild-Auswertung (Vision → JSON) über einen serverseitigen Schlüssel
SDK.jobs	run(pfad, body)	generisches Hintergrund-Job-Primitiv (startet einen Job und pollt bis zum Ergebnis)
SDK.print	print(...), print.locked(...)	zentrale PDF-Pipeline → { documentId, fileName }; locked erzeugt einen rechtlich gesperrten Beleg (opt-in)
SDK.documents	download(), getBlob(), createPublicLink()	Dokumente laden / öffentlichen Link erzeugen
SDK.mail	send(), mailboxes(), saveDraft()	E-Mail-Versand und Postfächer (Microsoft Graph)
SDK.user, SDK.can()	aktueller Nutzer + CASL-Berechtigungsprüfung	nur erlaubte Aktionen ausführen
SDK.theme, SDK.format	Mandanten-Branding + sprach-/regionsabhängige Formatierung	konsistente Darstellung

Der KI-Namespace stützt sich auf den werkzeugfreien Completion-Endpoint POST /api/ai-assist/completion (do:AiAssist): Plugins übergeben Nachrichten (Text, Bild oder Dokument) und erhalten Text + Token-Verbrauch zurück; der Server hält den Anbieter-Schlüssel.

Über `SDK.ai` erzeugte Inhalte sind eine **Hilfestellung**. Plugins sollten KI-Ergebnisse vor folgenreichen Schritten (Versand, Beleg-Erzeugung) **bestätigen** lassen. Jeder Aufruf läuft mit den Rechten des angemeldeten Nutzers und verbraucht Tokens, die in der [KI-Nutzung & -Kosten](/ai-usage) sichtbar sind.

Wiederverwendbare Konzepte

• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• Mitarbeiter, Rollen, Abteilungen — Ziel der Assignments.

Häufige Fehler und Lösungen

Fehler	Lösung
Kachel erscheint nicht auf Startseite	Keine Zuweisung (Mitarbeiter, Abteilung oder Rolle) oder fehlende Berechtigung.
Icon wird nicht angezeigt	icon-Bezeichner unbekannt oder leer — über den Icon-Selector neu setzen. Bei Custom-Imports auf das Library-Präfix (z. B. Tb, Fa, Md) achten.
Custom-Tiles-Tab in der Rolle nicht sichtbar	Berechtigung view:CustomNavigationTileAssignment fehlt.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/custom-navigation-tiles	Liste	view CustomNavigationTile
POST	/api/custom-navigation-tiles	Anlegen	create CustomNavigationTile
GET	/api/custom-navigation-tiles/:id	Detail	view CustomNavigationTile
PATCH	/api/custom-navigation-tiles/:id	Ändern	update CustomNavigationTile
DELETE	/api/custom-navigation-tiles/:id	Soft-Delete	delete CustomNavigationTile
GET	/api/custom-navigation-tile-assignments?filter[customNavigationTileId]	Sub-Liste	view CustomNavigationTileAssignment

Versionshinweise

• 2026-06-30: Advanced-Tile Plugin SDK dokumentiert — Namespaces ai (Completion/Vision via POST /ai-assist/completion), jobs, print/print.locked, documents, mail, user/can, theme/format. Verifiziert an advancedTileSDK.ts, aiAssist.router.ts.
• 2026-04-30: Initiale Veröffentlichung.
• 2026-05-12 (Welle 114): Icon-Selector-Modal mit Cross-Library-Suche über 31 react-icons-Bibliotheken (vorher nur ~85 Tabler-Icons hartkodiert). DynamicIcon lädt Icon-Libraries lazy. Neuer Tab Custom Tiles am Rollen-Detail (view:CustomNavigationTileAssignment erforderlich) — Tiles lassen sich jetzt direkt an einer Rolle pflegen.