Premium AI Template (technisch)

Das Premium AI Template ist ein vollständiges Signage-Template für Kiosk und Companion mit einheitlichem Design (Glassmorphism, hell), 3D-Wegfindung, Highlights (kuratierte Inhalte), KI-Suche und Concierge. Dieser Abschnitt beschreibt die technische Struktur für Entwickler und Redaktion.

Template-ID und Slugs

• Template-ID (intern): ai-premium
• Companion-Slug (URL): premium – die NOW! App wird unter /companion/t/premium geladen.
• Registry: Die Signage-App ordnet die Template-ID dem Companion-Slug zu; Handoff-URLs und Redirects nutzen diese Zuordnung.

Wenn du ein neues Center mit diesem Template betreibst, wählst du im Dashboard unter Digital Signage / Kiosk das Template "Premium AI" (oder die entsprechende Bezeichnung). Die Companion ist dann unter dem gleichen Template-Skin erreichbar.

Shells und Screens

Kiosk

• Shell: AIPremiumKioskShell – steuert Navigation, Idle-Timeout, DOOH-Slots, Overlays (Handoff-QR, Gruppen-Session-QR, Barrierefreiheit). Landscape: Das Template ist für Querformat-Kioske optimiert (kompaktere untere Leiste, angepasste Chip-Positionen, mehr Kartenfläche).
• Screens: Home (KioskHome), Shop-Detail (KioskShopDetail), Wayfinding (KioskWayfinding), ggf. Such- und Detailansichten. Die Home-Seite bietet Highlights (mit Info-Icon und Tooltip: von der Redaktion kuratierte Inhalte, exklusiv am Kiosk – wie kuratierte Playlists), Quick-Links (Shops, Gastronomie, Services, News/Angebote) in 4 Spalten, Wegfindung und die Buttons "Auf Handy weitermachen", "Begleitung einladen" (Gruppen-Modus) sowie "In der Nähe". Die Highlights-Zeile kann mit "Mehr Infos" vertikal expandiert werden; die letzte Kachel in der Reihe ("Alle Highlights") öffnet das Slide-up mit der Gesamtübersicht. Shops-, Gastronomie- und Services-Grids sowie "In der Nähe" sind visuell als Karten (4 pro Reihe) umgesetzt.
• Daten: Werden beim Laden der Kiosk-URL aus dem Dashboard (bzw. über die Signage-API) geholt: Shops, Hot Picks (als Highlights angezeigt), Featured News, Services, Center-Config. Die gleichen Datenquellen nutzt die Companion.

Companion (NOW! App)

• Shell: AIPremiumCompanionShell – liest URL-Parameter (centerId, sessionKey, handoffTargetShop, joinCode), initialisiert Session-Tracking und übergibt Daten an die Companion-Home.
• Hauptansicht: CompanionHome – Vollbild-Centerplan (3D oder 2D je nach Konfiguration), Highlights (mit Info-Tooltip zu kuratierten Inhalten), Concierge-Chatbar, Header mit Logo, "NOW!", Parkplatz-Anzeige, "In Gruppe"-Badge, "Session teilen"-Button, Menü.
• Weitere Ansichten: Wayfinding (CompanionWayfinding), Angebote/Events über Menü oder Navigation. "Auf Karte zeigen" und "Route starten" aus dem Concierge minimieren den Chat und heben das Ziel auf dem Plan hervor (kein Wechsel auf eine separate Wayfinding-Seite).
• Handoff vom Kiosk: Beim Scan des "Auf Handy weitermachen"-QR landet der Nutzer bei diesem Template auf der Companion-Startseite (nicht auf einer separaten Centerplan-Unterseite), da der Plan dort bereits sichtbar ist.

Konfiguration und Datenfluss

• Center: centerId bestimmt, welches Center geladen wird (Subdomain oder Parameter).
• Vorab geladen: Hot Picks (UI: Highlights), Shops, News/Events, Services, Center-Infos (Name, Logo, Akzentfarbe), Wayfinding-Daten (Floors, SVG/3D).
• Concierge: Nutzt die Dashboard-API (Visitor-Chatbot); die Signage-App leitet Anfragen per Proxy weiter, damit kein CORS vom Dashboard nötig ist. Kontext (Shops, Angebote, Parken, Trending, Rückgaberichtlinien usw.) wird serverseitig aus der AI-Context-Bibliothek geladen.
• Handoff: Session wird über POST /api/qr-sessions (Signage) angelegt; die Handoff-URL enthält sessionKey, centerId und optional shop/screen. Der QR führt auf /companion/t/premium?…. Beim Premium-AI-Template wird screen=companion-home gesetzt, damit der Nutzer auf der Startseite (mit Karte) landet.
• Gruppen-Modus ("Begleitung einladen"): Gruppe wird über POST /api/group-session (Signage-Proxy zum Dashboard) erzeugt. Das Overlay erklärt in drei Schritten den Ablauf (Du bist hier → Begleitung scannt → Fertig) und hebt den QR-Code sowie die Code-Alternative deutlich hervor.
• DOOH / Idle: Nach Ablauf der Inaktivität wird der Kiosk-Bereich weich verkleinert und der DOOH-Slot mit Playlist eingeblendet. Die Playlist läuft im Loop. Ein deutlicher Hinweis ("Tippen – Kiosk wieder aktivieren" / "Vollbild-Karte, Shops & Routen erscheinen wieder") macht klar, dass ein Tippen die volle Kiosk-UI wiederherstellt.
• Local Hero (DOOH): Über dem Werbe-Slot kann ein Local-Hero-Strip angezeigt werden: Shops, News, Events und Angebote, die die Redaktion im Dashboard unter Digital Experience → DOOH Video → „Local Hero – DOOH“ hinzufügt. Der Strip zeigt „Bei uns im Center“ und rotiert die Einträge (z. B. alle 8 Sekunden) mit Logo/Bild und Namen. So können lokale Partner und Aktionen im Idle-Modus sichtbar bleiben, ohne die Werbe-Playlist zu ersetzen.

Neu ergänzt: Modulare Kiosk-Features (Dashboard)

Im Bereich Digital Experience → Kiosk → Premium AI Optionen wurden zusätzliche Feature-Toggles ergänzt. Damit kann jedes Center das Template ohne Code-Anpassung schlanker oder umfangreicher ausrollen.

Feature-Toggles (pro Center)

• Premium-Module: enableOffers, enableFood, enableServices, enableHighlights, enableNearby, enableGroupSession, enableA11y, enableHandoffQr, enableDoohIdle
• Neue Basis-Module (standardmäßig deaktiviert): enableTraffic, enableSocialFeed, enableTransitMonitor
• Alternative Labels für Quicklinks: offersLabel, shopsLabel, foodLabel, servicesLabel, trafficLabel, socialFeedLabel, transitMonitorLabel

Basis-Module (neu)

• Verkehr: Google-Maps-Embed (Verkehrslage) via trafficMapEmbedUrl
• Social Feed: Elfsight/iframe-Quelle via socialFeedEmbedCode (src wird extrahiert)
• ÖPNV-Monitor: Abfahrtsmonitor/Embed via transitMonitorEmbedUrl

Alle drei Module erscheinen als zusätzliche Icons in den Quicklinks und öffnen ein einheitliches Slide-up (KioskEmbedSlideUp).

Shared Wayfinding-Package

Die 3D-Karte, SVG-Routen und zugehörige Logik kommen aus dem Shared Package @mall-os/wayfinding (Monorepo: packages/wayfinding). Dieses Package ist für alle Apps und Templates die zentrale Quelle:

• Digital-Signage (dieses Template, Kiosk/Companion) nutzt es für die 3D-Ansicht, Routen-Parsing und optional die find-route-API (Typen FindRouteRequest/FindRouteResponse).
• Center-Website nutzt es für die Wayfinding-Seite und Centerplan-Embeds (z. B. Goldbeck, HBB).
• Neue Kiosk-/Companion- oder Website-Templates sollten ausschließlich dieses Package einbinden; keine Duplikate in den Apps. Siehe packages/wayfinding/README.md für Anbindung und Exporte.

Routen im Dashboard und in der 3D-Ansicht

• Dashboard (Centerpläne → Etage → Tab „Routen“): Mit dem Modus „Route einzeichnen“ (R) klickst du Waypoints nacheinander an (z. B. Eingang → Shop). Jeder Klick erzeugt eine Verbindung (WaypointConnection) in der Datenbank. Diese Verbindungen erscheinen als Linien im 2D-Overlay des Route-Editors. Nach dem Erstellen einer Verbindung werden die Daten neu geladen, damit die Linien zuverlässig angezeigt werden.
• Auto-Snap für Redakteure: Beim Setzen von Waypoints kann der Editor Punkte automatisch auf das SVG-Routennetz (#routes/#Routes) ziehen. Das reduziert „kreuz und quer“-Verbindungen und macht die Pflege ohne externe Tools deutlich einfacher.
• Barrierefrei-QA-Layer: Im Routen-Editor kann ein Filter nur barrierefreie Verbindungen hervorheben (ohne Treppe/Rolltreppe, ohne wheelchairAccess=false) für schnelle Qualitätskontrolle.
• Wayfinding-Routenquelle (Option): Unter Kiosk-Optionen → Wegeführung kann die Routenquelle gewählt werden: Auto (Standard: Dashboard-Route, wenn ein Kiosk-Standort zugeordnet ist, sonst SVG), Nur SVG-Routen (#routes/#Routes-Ebene in der SVG) oder Nur Routen-Editor (nur Wegpunkte aus dem Dashboard). So lässt sich gezielt vermeiden, dass SVG-Routen und Dashboard-Routen gleichzeitig oder widersprüchlich genutzt werden.
• 3D-Ansicht (Kiosk/Companion): Die eingezeichnete Route wird in der 3D-Karte genutzt, sobald die Routenquelle „Dashboard“ oder „Auto“ ist und der Kiosk einer Display-Location zugeordnet ist (Digital Experience → Hardware → „Standort (Display)“). Dann wird die Route vom Datenbank-Graphen (WaypointConnection) über die find-route-API berechnet. Bei Nur SVG-Routen wird ausschließlich die SVG-Gruppe „#routes“ (bzw. „#Routes“) genutzt.
• Barrierefreies Routing im Kiosk: Die Routing-API berücksichtigt modusabhängig avoidStairs, preferElevator und accessibilityRequirements (z. B. Rollstuhl-/Kinderwagenmodus), damit die Route im Kiosk korrekt angepasst wird.

Neu ergänzt: Slide-ups und Detailansichten (UI/UX)

Die Kiosk-Slideups für Shops, Gastronomie, Services, News, Angebote, Highlights, In der Nähe wurden überarbeitet:

• harmonisierte Spacing-/Padding-Logik für Header, Filter, Content und Detailbereiche
• moderne Grid-Darstellung mit bis zu 5 Karten pro Zeile (insbesondere Landscape/XL)
• zusätzliche Filter (Suche, Etage, Kategorie) inkl. Trefferanzeige und Reset
• verbesserte Detailansichten mit vorhandenen Dashboard-Daten (z. B. Öffnungszeiten, Telefon, Website, Beschreibung)
• bessere Portrait-/Landscape-Balance für Touch-Bedienung im Kioskbetrieb

Design und Theme

• Theme: Hell (kein Dark Mode); Glassmorphism und dezente Skeuomorphie, einheitlich für Kiosk und Companion.
• Design-Tokens: Zentrale Werte (Farben, Abstände, Schatten) liegen in einer Theme-Datei (z.B. ai-premium-theme.ts); Header, Karten und Chatbar nutzen dieselben Styles.
• Safe Area: Header und untere Bereiche berücksichtigen env(safe-area-inset-*) für Notch und Gestenleiste.

AR-Navigation und Shopfront-Erkennung (Beta)

Die Companion bietet neben der klassischen 2D/3D-Kartenansicht einen AR-Modus (Beta), der die Kamera des Smartphones nutzt:

AR-Navigation (Dead Reckoning + Image Tracking)

• Plan/AR-Toggle: In der Wayfinding-Ansicht (CompanionWayfinding) kann der Nutzer zwischen Plan (3D-Karte) und AR (Kamera-Livebild mit Richtungspfeil) wechseln.
• Dead Reckoning: Gyroskop (Heading) + Accelerometer (Schrittzähler) schätzen Position und Richtung. Die Schätzung wird per Map Matching auf den bekannten Korridor-Graphen projiziert, um Sensordrift zu kompensieren.
• Positions-Kalibrierung: Anfangsposition kommt vom QR-Scan am Kiosk. Zusätzlich können Shopfront-Bilder als Image Marker dienen (siehe unten), um die Position unterwegs automatisch zu kalibrieren.
• Drift-Warnung: Nach einer gewissen Schrittzahl warnt das System und bietet einen Re-Scan an (QR oder Shopfront).

Shopfront-Erkennung (MindAR.js Image Tracking)

• Technologie: MindAR.js – browser-basiertes Image Tracking mit WebGL und TensorFlow.js. Keine native App nötig.
• Workflow:
  1. Dashboard: Für jeden Waypoint (Shop/Location) kann ein Shopfront-Bild (Foto der Ladenfront) als arMarkerImageUrl hinterlegt werden – im bestehenden position-JSON-Feld, kein Schema-Change.
  2. Dashboard: Button „AR-Marker" im Routen-Editor kompiliert alle Shopfront-Bilder einer Etage client-seitig zu einer .mind-Datei (MindAR-Format).
  3. Companion: Beim Öffnen des AR-Modus lädt die App die .mind-Datei und die Image Targets über /api/ar/image-targets.
  4. Live: Nutzer richtet die Kamera auf eine Ladenfront → MindAR erkennt das Bild → AR-Overlay zeigt Shop-Name, Angebote, News und Events. Gleichzeitig wird die Position für die Navigation kalibriert.
• Fallback: Wenn kein Image Tracking verfügbar ist (keine .mind-Datei konfiguriert), bleibt die QR-basierte Kalibrierung aktiv.

AR-Felder im Dashboard (Waypoint-Editor)

Im Tab Centerpläne → Etage → Routen gibt es unter jedem Waypoint ein aufklappbares Panel „AR-Navigation (Beta)" mit:

Feld	Beschreibung
Blickrichtung °	Wohin schaut der Nutzer an diesem Standort (Dropdown: N, NO, O, SO, S, SW, W, NW)
Gang-Richtung °	Korridor-Richtung zum nächsten Wegpunkt (Gradzahl)
Distanz (m)	Entfernung zum nächsten Wegpunkt in Metern
Landmarks	Sichtbare Orientierungspunkte (kommagetrennt, z. B. „Brunnen, H&M links")
Shopfront-Bild	URL zum Foto der Ladenfront (für MindAR Image Tracking)

Alle Felder sind optional und werden als zusätzliche JSON-Eigenschaften im bestehenden Waypoint.position-Feld gespeichert – kein Datenverlust, kein Schema-Change.

Konfiguration

• .mind-Datei-URL: Wird in den Center-Optionen unter signageTemplateOptions.arMindFileUrl gespeichert und über AIPremiumCompanionShell an CompanionWayfinding übergeben.
• Image Targets: Die API /api/ar/image-targets?centerId=... liefert alle Waypoints mit arMarkerImageUrl für ein Center.

Datenintegrität (ohne Datenverlust)

Die neuen Optionen wurden additiv eingeführt:

• neue Template-Optionen sind optional und haben Defaults
• bestehende Datenstrukturen bleiben gültig
• AR- und Zusatzfelder werden in bestehenden JSON-Feldern ergänzt (kein destruktiver Schema-Umbau)

Wichtige Dateien (Orientierung im Codebase)

• Kiosk-Shell: z.B. AIPremiumKioskShell.tsx
• Companion-Shell: z.B. AIPremiumCompanionShell.tsx
• Companion-Home: z.B. CompanionHome.tsx
• Handoff (plattformweit): HandoffQROverlay, buildHandoffUrl, getHandoffCompanionPath
• Gruppen-Session: GroupSessionQROverlay, Signage-API /api/group-session
• Concierge-UI: CompanionChatbar; Backend: Dashboard Visitor-Chatbot + AI-Context
• AR-Navigation: ARNavigationView.tsx, useARNavigation (Dead Reckoning), useImageTracking (MindAR)
• AR-Overlay: ARShopOverlay.tsx (Shop-Info bei erkanntem Shopfront)
• AR-Utilities: ar-utils.ts (Position-JSON-Parsing mit AR-Feldern)
• MindAR-Compiler: mind-ar-compiler.ts (Client-seitige .mind-Kompilierung im Dashboard)
• Image Targets API: /api/ar/image-targets (liefert AR-Marker für ein Center)

Wenn du ein neues Template anlegst und die Companion anbinden willst, brauchst du: Eintrag in der Signage-Companion-Registry (Template-ID → Companion-Slug), eine Companion-Shell die sessionKey/handoff/joinCode verarbeitet, und die Nutzung der gemeinsamen Handoff- und Gruppen-Overlays. Das Premium AI Template dient dabei als Referenz.