Portal-Assistent: Konzept und Etappenplan

Kurzfassung

Das Kundenportal ist für Studio-Betreiber oft das erste System dieser Art. Es ist umfangreich, und vieles wird übersehen. Wir bauen deshalb in Etappen einen Assistenten ein, der am rechten Bildschirmrand lebt: erst als Hilfe-Spalte mit kurzer Erklärung und ausführlicher Anleitung zu jedem Bereich, dann als Chat, der Fragen aus den Anleitungen beantwortet, dann als Begleiter, der beim Einstieg begrüßt, zeigt, was seit dem letzten Besuch passiert ist, und passende nächste Schritte vorschlägt. Die Figur heißt Simki (Renés Entscheidung 14.09.): der Roboter von unserer Website, weißer Körper, schwarzer Visor, Stirnband, pinke Schweißbänder. Charakterbogen und Referenzpaket: /root/transfer/simki/referenz/SIMKI-CHARAKTER.md. Erste sichtbare Ergebnisse gibt es mit Etappe 1 sofort, jede weitere Etappe baut auf der vorherigen auf und ist einzeln abnehmbar.

Was schon da ist

Zielbild (Renés Beschreibung, geordnet)

1. Rechts eine Spalte im Kundenportal (Desktop), in der der Assistent wohnt. Am Anfang ein Hilfe-Fenster mit Suche und Chat-Eingabe, der Roboter sitzt auf der Oberkante.
2. Zu jedem Bereich die Erklärung parat haben: „Wofür ist das, wie funktioniert das, wie nutze ich das."
3. Beim Bereichswechsel fragen: „Was möchtest du tun?" und passende Wege anbieten.
4. Beim Einstieg begrüßen: „Hallo Vorname, schön, dass du wieder da bist. Hier siehst du, was in den letzten Tagen passiert ist." Später: „Möchtest du mit X weitermachen?", wenn er weiß, was zuletzt gemacht wurde.
5. Handeln können: die Dinge, die ein Kunde im Portal per Knopf tut, auch im Gespräch erledigen.
6. Charme: ein bisschen lustig, ein Schmunzler, später Bewegung (winken, nicken), ohne dass er stört.

Grundsätze (gelten für alle Etappen)

• Nur eigene Daten. Der Assistent läuft in der Portal-Sitzung des Kunden. Er sieht ausschließlich, was diese Person auch auf den Seiten sieht (Scoping über portalUserOf(), wie jede Portal-Route). Kein Admin-Token, kein Zugriff auf andere Kunden, keine Zentrale-Werkzeuge.
• Ehrlich. Antworten zu Systemdaten kommen aus dem System, Antworten zur Bedienung aus den Anleitungen. Weiß er etwas nicht, sagt er das und bietet den Weg zum SIM-Team (Postfach) an. Nichts erfinden.
• Handeln nur mit Bestätigung. Jede Aktion zeigt vorher eine Karte („Ich setze Lead Sabine M. auf ‚Termin vereinbart'. Passt?") und läuft danach über genau den Portal-Endpunkt, den auch der Knopf nutzt.
• Nicht nerven. Höchstens ein proaktiver Hinweis je Seitenaufruf, jeder Hinweis wegklickbar, Spalte einklappbar, Zustand wird gemerkt. Sprüche sparsam.
• Kosten im Griff. Modell wie beim KI-Berater (Gemini Flash über OpenRouter), Tageslimit je Kunde, Zähler im Kosten-Tracking. Etappen 1 und 2 kosten nichts pro Aufruf, weil dort kein Modell läuft.
• Du-Form, Ton wie die Anleitungen: klar, freundlich, ohne Fachjargon, keine Gedankenstriche.
• Desktop zuerst. Die Spalte erscheint ab 1440 px Breite. Darunter wird sie zum Knopf unten rechts, der dasselbe Fenster als Sheet öffnet.

Etappen

Etappe 0: Sichtbarkeit (heute erledigt)

Haupt-Reiter und Kopf-Aktionen im Portal sind jetzt überall echte Buttons in der Buttonfarbe, links unter der Einleitung (Cockpit, Postfach, News, Kursplan, Verträge, Kundenstimmen, Partner). Live als Hub v0.297.5.

Etappe 1: Kurz erklärt und Anleitung auf jeder Seite

Inhalt. Für alle 13 Bereiche plus Startseite entsteht eine Kunden-Anleitung mit fester Struktur: Wofür ist das? Wie funktioniert es? So nutzt du es, Schritt für Schritt. Häufige Fragen. Wenn etwas nicht klappt. Jede Anleitung trägt eine kurz:-Zeile mit zwei, drei Sätzen. Der Seitenrahmen zeigt daraus unten auf jeder Seite die Karte „Kurz erklärt" mit dem Knopf „Ausführliche Anleitung". Der Menüpunkt „Hilfe & Anleitungen" bekommt eine Einstiegsseite mit allen Themen (bisher lief er ins Leere).

Stand. LIVE als Hub v0.297.6 (14.09. früh): Rahmen (Parser, Karte, Test), 13 Anleitungen von drei Opus-Agenten aus dem Quellcode geschrieben und gegen die gemeldeten Unsicherheiten korrigiert, alle 15 Hilfe-Schlüssel und die Karte auf 13 Seiten live geprüft. René liest die Texte einmal quer.

Ergebnis für den Kunden. Auf jeder Seite steht in drei Sätzen, wofür sie da ist, und ein Klick weiter die ganze Anleitung. „Hilfe & Anleitungen" führt zu allem.

Aufwand. Rahmen 0,5 AT (erledigt), Texte 1 AT Agenten plus 0,5 AT Prüfung, Renés Lesezeit etwa 1 Stunde.

Etappe 1b: Hilfe-Leiste von rechts (live, 14.09.)

Renés Befund nach dem Durchklicken: „Die Anleitungen sind gut, aber wenn ich nicht gleichzeitig darauf gucken kann, ist das total schwierig." Deshalb ist das schwebende Hilfe-Fenster durch eine Leiste ersetzt, die sich vom rechten Rand einschiebt (Hub v0.297.7): ab 1200 px Breite rückt der Seiteninhalt nach links, sodass Anleitung und Seite nebeneinander stehen; darunter liegt die Leiste über dem Inhalt, am Handy als Sheet von unten. Sie bleibt über Seitenwechsel offen und zeigt auf jeder Bereichsseite deren Anleitung. Zugeschoben wird mit ✕ oder Esc, zurück holt sie ein Griff am rechten Rand mit Simkis Kopf. Links innerhalb der Anleitungen und „Alle Anleitungen" bleiben in der Leiste. Damit steht der Platz, in den in Etappe 2 Simki, Schnellwege und Suche einziehen.

Etappe 2: Die Hilfe-Spalte rechts

Inhalt. Neue rechte Spalte (etwa 320 px, ab 1440 px Breite, einklappbar, Zustand im Browser gemerkt). Oben sitzt der Roboter auf der Kante der Spalte (stehendes Bild, freigestellt). Darunter, je nach Seite:

• eine Sprechblase mit dem kurz:-Text des aktuellen Bereichs,
• der Knopf „Ausführliche Anleitung",
• zwei bis vier Schnellwege je Bereich („Neuen Lead anlegen", „Kursausfall eintragen", „Feiertag hinzufügen"), die den passenden Knopf auf der Seite auslösen oder dorthin scrollen,
• das Suchfeld („Was möchtest du tun?"), zunächst identisch mit der Suche oben: findet Bereiche, Anleitungen, Leads, Kurse.

Am Handy und auf kleinen Bildschirmen: runder Knopf mit dem Roboterkopf unten rechts, öffnet dasselbe als Sheet. Der bisherige schwebende Hilfe-Dialog geht in der Spalte auf.

Datenmodell. Eine kleine Datei je Bereich (hub/hilfe/profile/<bereich>.json oder ein Block in der .kunde.md) mit den Schnellwegen: Beschriftung, Ziel (Knopf-Kennung oder Anker). Keine Datenbank nötig.

Ergebnis. Der Kunde hat auf jeder Seite einen festen Ort, an dem Erklärung, Anleitung, Schnellwege und Suche liegen. Die Figur ist da.

Aufwand. 1,5 AT.

Etappe 3: Fragen stellen (Chat aus den Anleitungen)

Inhalt. Das Suchfeld wird zum Chat. Fragen wie „Wie trage ich einen Feiertag ein?" oder „Warum wird meine News nicht angezeigt?" beantwortet das Modell aus den Anleitungen (alle .kunde.md zusammen sind klein genug, um sie vollständig mitzugeben, kein eigener Suchindex nötig) plus Kontext: aktueller Bereich, Studioname, Vorname, Studio-Software. Jede Antwort endet mit einem Sprungziel („Das machst du unter Öffnungszeiten, Reiter Feiertage") und, wo es passt, mit dem Angebot, ans SIM-Team zu schreiben.

Lesende Werkzeuge (nur eigene Daten, über die vorhandenen Portal-Routen mit der Sitzung des Kunden): Leads-Liste und Zähler, nächste Probetrainings, Postfach offen, Cockpit-Stand, Kursplan-Zahlen, Öffnungszeiten heute, Webstatistik-Übersicht. Damit sind Fragen wie „Wie viele Anfragen hatte ich diese Woche?" möglich.

Bauart. Neues Hub-Modul portalAssistent.ts (Routen unter /portal/api/assistent/*, Verlauf in Tabelle portal_assistent_dialoge, Modellaufruf wie chatbotCore.ts über OpenRouter), Streaming in die Spalte. Rate-Limit je Sitzung, Tageslimit je Kunde, Kosten ins Kosten-Tracking. Der Verlauf ist für das SIM-Team in der Kundenakte einsehbar (Karte „Portal-Assistent": Fragen, die Kunden stellen, sind die beste Quelle für fehlende Anleitungen).

Ergebnis. Der Kunde fragt in seinen Worten und bekommt eine Antwort mit Weg.

Aufwand. 2 AT.

Etappe 4: Begrüßen und vorschlagen (proaktiv)

Inhalt.

• Beim Einstieg: „Hallo Vorname, schön, dass du wieder da bist. Seit deinem letzten Besuch: 3 neue Anfragen, 2 unbeantwortete Nachrichten im Postfach, dein Kursplan wurde am Dienstag veröffentlicht." Die Zahlen kommen aus den Portal-Ereignissen seit last_login_at, keine Modellkosten.
• Beim Bereichswechsel: ein Satz zum Bereich plus ein Vorschlag aus dem Ist-Zustand („2 Leads warten seit 3 Tagen ohne Termin. Soll ich sie dir zeigen?").
• Weitermachen: „Zuletzt hast du am Kursplan gearbeitet. Weitermachen?" aus portal_audit (letzte Aktion je Konto).
• Regeln: höchstens ein Hinweis je Seitenaufruf, Hinweise mit Kennung und „nicht mehr zeigen", nichts wiederholen, was schon weggeklickt wurde.

Ergebnis. Das Portal fühlt sich an, als würde jemand mitdenken.

Aufwand. 2 AT (Ereignis-Zusammenfassung 1 AT, Vorschlagsregeln je Bereich 1 AT).

Etappe 5: Handeln mit Bestätigung

Inhalt. Aktionen im Gespräch, jede mit Bestätigungskarte, jede über den bestehenden Portal-Endpunkt: Lead-Status setzen und Notiz ergänzen, Termin bestätigen, Nachricht im Postfach als erledigt markieren, Kursausfall eintragen, Feiertag anlegen, News-Entwurf anlegen, Kundenstimme freigeben, Cockpit-Regel an- oder ausschalten. Bauart wie in der Zentrale (Vorschau-Karte, dann run() gegen exakt den Knopf-Endpunkt), aber mit der Kunden-Sitzung statt Admin-Token. Renés Grundsatz aus der Zentrale gilt auch hier: Was ein Knopf kann, kann der Assistent auch, sonst ist es ein Baufehler.

Ergebnis. „Setz den Lead von Sabine auf Termin vereinbart" reicht.

Aufwand. 3 AT, in Paketen je Bereich lieferbar (zuerst Leads und Postfach, dann Kursplan und Zeiten).

Etappe 6: Die Figur lebt

Inhalt. Aus den vorhandenen Roboter-Motiven wird ein fester Charakter: ein Charakterbogen (Vorderseite, Halbprofil, Kopf) in einheitlichem Look, daraus vier Haltungen als freigestellte Bilder (steht, winkt, zeigt nach links auf die Seite, denkt). Erste Bewegung als kurze WebM-Sequenzen mit Alphakanal oder als Bildfolge (Winken beim Einstieg, Nicken nach einer Aktion, Blinzeln als Leerlauf). Sprechblase mit kleinen Sprüchen, sparsam und passend zur Branche („Montag ist Beintag. Und Lead-Tag."). Später, wenn es sich lohnt, ein echtes 3D-Modell (glTF) mit drei Animationen, damit er wirklich steht und sich bewegt.

Ergebnis. Der Schmunzler.

Aufwand. Charakterbogen und Haltungen 1 AT plus Bildgenerierung, Bewegung 1 AT; 3D später separat.

Später (nicht in diesem Plan)

Der gleiche Assistent in der Zentrale für das SIM-Team (dort gibt es schon den SIM Assistenten, eine Zusammenführung ist eine eigene Entscheidung). Sprache statt Tippen. Erinnerungen („Erinnere mich Freitag an den Kursplan").

Renés Zielbild für später und meine Vorschläge dazu

Renés Bild (14.09.): Wenn Simki voll da ist, schwebt er über dem Inhalt, lässt sich hin- und herschieben, unten rechts sitzt eine Blase wie bei einem Chatbot; man ruft ihn und schickt ihn wieder weg, dann verschwindet er in seiner Ecke.

Mein Vorschlag, wie beides zusammenpasst:

1. Zwei Zustände statt einem. Die Leiste (Etappe 1b) bleibt der Arbeitsmodus für alles, was man nebenher liest oder länger tippt: Anleitung, Chatverlauf, Schnellwege. Die Blase unten rechts ist der Rufmodus: Simki klein, mit einer Sprechblase für einen Satz („3 neue Anfragen" oder die Begrüßung). Ein Klick auf die Blase öffnet die Leiste, ✕ schickt ihn zurück in die Ecke. So verdeckt nichts den Inhalt, und man muss ihn nie wegschieben, um zu arbeiten.
2. Schweben und Schieben nur für Simki selbst, nicht für Text. Die Figur darf frei über dem Inhalt stehen und lässt sich mit der Maus versetzen (Position wird gemerkt). Text gehört in die Leiste oder in eine kurze Sprechblase an der Figur. Lange Texte in frei schwebenden Fenstern waren genau das Problem, das wir heute gelöst haben.
3. Zeigen statt erklären. Wenn Simki auf etwas hinweist („den Knopf Kurs-Pool findest du hier"), hebt er das Element auf der Seite mit einem weichen Rahmen hervor und stellt sich daneben. Das ist mit den Schnellwegen aus Etappe 2 fast geschenkt und wirkt stärker als jede Beschreibung.
4. Ruhig sein können. Ein Schalter „Simki nur auf Zuruf" in den Einstellungen, für Kunden, die keine Begrüßung und keine Vorschläge wollen. Die Figur bleibt dann in der Ecke und meldet sich nicht von selbst.
5. Ein Gedächtnis je Person, nicht je Browser. Zuletzt besuchter Bereich, weggeklickte Hinweise und die Position der Figur liegen am Portal-Konto, damit es am Laptop und am Handy dasselbe Verhalten gibt.
6. Simki spricht, wie er aussieht. Kurze Sätze, Fitnessbezug als Augenzwinkern, nie belehrend. Beispiele stehen im Charakterbogen. Die Mundlinie auf dem Visor leuchtet, während er „spricht" (Text erscheint), das ist sein Erkennungszeichen aus dem Website-Video.

Vorbereitung der Figur: Referenzpaket mit zehn Bildern (Ganzkörper freigestellt, Studio, Yoga, Gadgets, Video-Standbilder winken und sprechen, Kopf freigestellt) und Charakterbogen mit englischer Prompt-Fassung liegt unter /root/transfer/simki/referenz/. Das Higgsfield-Element „simki" wird in einer Sitzung mit Higgsfield-Anbindung (claude.ai, Cowork) aus den Bildern 01 bis 04 angelegt; die Anbindung hängt nicht am Server. Danach lassen sich Haltungen und kurze Videos jederzeit nachgenerieren.

Architektur in einem Absatz

Alles bleibt im Hub, keine neue Datenbank, kein neuer Container. Wissensquelle sind die Hilfe-Dateien im Repo, Bereichsprofile mit Schnellwegen liegen daneben. Die Spalte ist Teil der Portal-Shell (portal.ts, portal-ui.js, portal.css) und bekommt je Seite ihren Kontext über opts.nav. Der Chat läuft über ein neues Modul portalAssistent.ts mit eigener Tabelle für Dialoge, Modellaufruf über OpenRouter wie beim KI-Berater, Kosten im Kosten-Tracking. Lesende und handelnde Werkzeuge rufen ausschließlich die bestehenden /portal/api/*-Routen mit der Sitzung des Kunden auf. Figur-Assets liegen unter hub/public/portal/assistent/.

Fragen an René

1. ~~Name der Figur~~ entschieden: Simki.
2. Welches Motiv. Die schlanke Hantel-Figur (ki_roboter_fitness_frei.png) oder die mit Telefon, Kamera und Aktenordnern (simki_assistent.png)? Für die Spalte passt die schlanke besser, die Gadget-Variante ist als Bild fürs Handeln (Etappe 5) schön.
3. Modell und Budget. Gemini Flash über OpenRouter wie beim KI-Berater, mit Tageslimit je Kunde (Vorschlag: 60 Fragen). Einverstanden?
4. Pilotkunden. SimGym zum Bauen, danach zwei echte Kunden für Etappe 3 (Vorschlag: Impuls und Life X, sobald live).
5. Sichtbarkeit in der Zentrale. Soll das SIM-Team die Kundenfragen und -dialoge in der Kundenakte sehen (Vorschlag: ja, das zeigt, welche Anleitungen fehlen)?
6. Ton der Sprüche. Wie viel Humor darf es sein: gelegentlich ein Augenzwinkern (Vorschlag) oder ein richtiger Spaßvogel?

Vorschlag für die Reihenfolge