KI-Assistent

Wozu dient das?#

Der integrierte KI-Assistent unterstützt das Servicepersonal an den Kassen-Terminals sowie Führungskräfte im Backoffice bei der schnellen Bedienung, der Suche nach Systemfunktionen, dem Abrufen von Statusinformationen sowie der vorbereitenden Ausführung von Kassenbefehlen in natürlicher deutscher Sprache.

Rollen#

Servicepersonal (Kellner / Waiter): Nutzt den Assistenten für Fragen zur Bedienung, zur Standortsuche im Backoffice, zur Abfrage freier Tische sowie zur schnellen Bon-Erfassung per Sprache oder Text.
Schichtleiter & Manager (Manager / Admin): Bestätigen verändernde oder finanzwirksame Vorschläge des Assistenten (z. B. Rabatte, Stornierungen, Tischumbuchungen) über interaktive Bestätigungskarten (ConfirmCard). Bediener ohne Managerrechte können solche Aktionen nicht ausführen.

Voraussetzungen#

Einwilligung des Betriebs: Der Assistent ist für jeden echten Betrieb zunächst aus (Demo-Betriebe mit erfundenen Gästen haben ihn an). Solange das Sprachmodell bei DeepSeek läuft, lässt er sich für echte Betriebe nicht einschalten: Die Seite KI-Assistent im Backoffice zeigt dann statt des Schalters einen Hinweis, und der Server lehnt das Einschalten ab (Code KI_ANBIETER_GESPERRT). Bei einem Anbieter ohne diese Sperre schaltet ein Administrator ihn dort ein, nachdem er die Hinweise gelesen und bestätigt hat. Die Eingaben und der Kontext aus der Kasse gehen dann an den Anbieter des Sprachmodells (DeepSeek mit Sitz in der Volksrepublik China oder OpenRouter mit Sitz in den USA, je nach Serverkonfiguration), also in ein Drittland. Der Widerruf ist jederzeit möglich. Jede Entscheidung bleibt mit Person und Zeitpunkt in der Historie stehen. Ohne Einwilligung bekommen auch neu angelegte Artikel nur Suchbegriffe aus ihrem eigenen Namen, nicht vom Sprachmodell.
Aktiviertes Assistenten-Modul in den Systemeinstellungen (ASSISTANT_ENABLED = true).
Konfigurierte und erreichbare KI-Schnittstelle (LLM_BASE_URL und LLM_API_KEY hinterlegt).
Für die Bestätigung von Rabatten oder Stornos: Eine angemeldete Benutzerrolle mit Manager- oder Administratorrechten.

Bildschirm für Bildschirm#

1. Assistenten-Seitenfenster (`AssistantPanel`)#

KI-Assistent als Seitenfenster mit Bestätigungskarte

1 Die Kopfzeile mit dem Titel KI-Assistent, Verlauf löschen und dem Schließen-Kreuz.
2 Ihre Frage oder Ihr Befehl.
3 Ein Werkzeug-Chip zeigt, welche Funktion der Assistent im Hintergrund aufruft (hier Tische prüfen).
4 Die Bestätigungskarte Bestätigung erforderlich mit der Frage, was geschehen soll.
5 Ausführen erteilt die Freigabe, Abbrechen verwirft den Vorschlag.
6 Nachdenken... erscheint, solange der Assistent antwortet; Stoppen bricht die Antwort ab.
7 Die Eingabezeile Fragen Sie den KI-Assistenten...

Das Panel schiebt sich nach dem Tippen auf das Hilfesymbol / KI-Assistent (t("ai_assistant")) auf der rechten Bildschirmseite ein.

Kopfzeile: Enthält das Modulsymbol, den Titel KI-Assistent (t("ai_assistant")), die Schaltfläche Verlauf löschen (t("clear_history")) zum Zurücksetzen der Unterhaltung sowie die Schaltfläche Schließen (t("close")) (X).
Nachrichtenliste (MessageList): Stellt den Dialogverlauf zwischen Bediener und Assistent dar.
- Nachdenken-Anzeige: Während der Assistent an einer Antwort arbeitet, erscheint der Hinweis Nachdenken... (t("thinking")). Über die Schaltfläche Stoppen (t("stop")) kann die Antworterzeugung abgebrochen werden.
- Werkzeug-Chips (ToolCallChip): Zeigen optisch an, wenn der Assistent im Hintergrund Systemfunktionen aufruft (z. B. Tische prüfen (tool.get_tables), Auf dem Bildschirm zeigen (tool.show_on_screen), Handbuch (tool.handbook)). Hinweis: Einzelne Werkzeugnamen werden in der aktuellen Version in englischer Rohform dargestellt.
Bestätigungskarte (ConfirmCard): Erscheint im Chat, wenn der Assistent eine verändernde Aktion vorbereitet hat.
- Überschrift: Bestätigung erforderlich (t("confirmation_required")).
- Hinweistext: Zeigt die konkrete Bestätigungsfrage, z. B. Soll ein Rabatt von {{val}} angewendet werden? (t("confirm.apply_discount")) oder Soll die Aktion {{tool}} ausgeführt werden? (t("confirm.generic_mutation")).
- Schaltflächen: Ausführen (t("mode_execute")) zur Erteilung der Freigabe oder Abbrechen (t("cancel")) zum Verwerfen des Vorschlags.
Eingabezeile (Composer): Eingabefeld mit dem Platzhalter Fragen Sie den KI-Assistenten... (t("ask_assistant_placeholder")).
Visuelle Hervorhebungen (Overlays): Antwortet der Assistent auf Fragen zu Einstellungen, bietet er die Schaltfläche Zeigen (t("mode_explain")) an. Ein Tippen darauf navigiert im Hintergrund direkt zur passenden Stelle im Backoffice und hebt das gesuchte Element optisch hervor.

Schritt für Schritt (inklusive Betriebsverzweigungen)#

Hauptpfad A: Fragen stellen und Einstellungen erklären lassen#

Tippen Sie auf KI-Assistent (t("ai_assistant")).
Geben Sie eine Frage ein, z. B. "Wie richte ich die TSE ein?".
Der Assistent erläutert die Funktion im Chatfenster.
Tippen Sie in der Antwort auf Zeigen (t("mode_explain")).
Das Kassensystem öffnet im Hintergrund automatisch die entsprechende Einstellungsseite und hebt das Bedienfeld optisch hervor.

Auswertungen erfragen (Leitung im Backoffice-Chat): Fragen Sie etwa „Was sind unsere Renner diesen Monat?“ oder „Wann sind unsere Stoßzeiten?“. Die Zahlen und Rangfolgen rechnet der Server, Tagesgrenzen gelten in Ortszeit. Fragen Sie nach Storno-Auffälligkeiten, nennt das Modell Bedienungen nur als „Bedienung A, B, …“; Administrator und Manager sehen in der Antwort die Namen, die erst die Kasse einsetzt. Eine Auffälligkeit ist kein Vorwurf, sondern ein Anlass zum Nachsehen. Der Freitext von Storno-Gründen geht nicht an das Sprachmodell.

Hauptpfad B: Kassenbefehle ausführen (Stufe-0-Schnellmodus)#

Geben Sie an der Kasse einen standardisierten Befehl ein, z. B. "2x Schnitzel auf Tisch 4".
Das System verarbeitet den Befehl direkt ohne Verzögerung (0 KI-Tokens) und bucht die Artikel auf den Tisch.

Hauptpfad C: Finanzielle Aktionen anfragen und bestätigen (Zwei-Schritt-Verfahren)#

Geben Sie einen Befehl ein, der den Rechnungs- oder Finanzstatus verändert, z. B. "Gib 10% Rabatt auf Tisch 2".
Der Assistent berechnet die Daten im Hintergrund, führt die Änderung jedoch nicht direkt aus.
Im Chatfenster erscheint die Gelbe Bestätigungskarte mit der Überschrift Bestätigung erforderlich (t("confirmation_required")) und der Frage Soll ein Rabatt von {{val}} angewendet werden? (t("confirm.apply_discount")).
Verzweigung C1 — Berechtigter Manager bestätigt: Ein angemeldeter Manager tippt auf Ausführen (t("mode_execute")). Das Backend prüft den Bestätigungs-Token und wendet den Rabatt rechtssicher an.
Verzweigung C2 — Bediener bricht ab: Der Bediener tippt auf Abbrechen (t("cancel")). Der Vorschlag wird verworfen und der Bon bleibt unverändert.
Verzweigung C3 — Bon wurde zwischenzeitlich verändert: Wurde der Bon am Terminal verändert (z. B. ein weiterer Artikel hinzugefügt), während der Assistent auf die Bestätigung wartete, schlägt das Ausführen fehl. Das System meldet The order was modified after proposal. Please re-confirm.. Der Bediener muss die Rabatt-Anfrage neu starten.
Verzweigung C4 — Fehlende Managerrechte: Tippt ein Bediener ohne Managerrechte auf Ausführen, weist das System die Aktion mit HTTP 403 Forbidden ab.

Hauptpfad D: Zahlung über den Assistenten kassieren (bar oder Karte)#

Geben Sie z. B. "Tisch 4 zahlt 38,50 mit Karte" ein. Auch eine Zahlung ist eine finanzwirksame Aktion: Es erscheint zuerst die Bestätigungskarte (siehe Hauptpfad C).
Karte: Nach dem Ausführen startet der Assistent die Zahlung am Kartenterminal, genau wie der Knopf im Zahlungsfenster (siehe 35. Kartenzahlung am Terminal). Der Gast hält die Karte an das Terminal. Trinkgeld nimmt der Assistent nicht auf; dafür das Zahlungsfenster benutzen.
Erst bezahlt, wenn das Geld da ist: Der Assistent meldet eine Zahlung nur dann als erfasst, wenn das Terminal sie genehmigt hat. Bei einer Teilgenehmigung zählt nur der genehmigte Betrag; der Rest bleibt offen und der Assistent nennt ihn.
Verzweigung D1 — Kein Terminal eingerichtet: Der Assistent antwortet „Karte bitte am Terminal kassieren.“ und bucht nichts. Kassieren Sie über das Zahlungsfenster.
Verzweigung D2 — Karte abgelehnt: Der Assistent meldet die Ablehnung mit Grund, z. B. „… wurde am Terminal abgelehnt (…). Die Zahlung ist nicht vereinnahmt — die Bestellung bleibt offen.“
Verzweigung D3 — Zeitüberschreitung am Terminal: Der Ausgang ist unbekannt; der Assistent meldet „Zeitüberschreitung am Terminal (Ausgang unbekannt)“, die Bestellung bleibt offen. Klären Sie den Status am Terminal bzw. in der Kartenabstimmung (35a), bevor Sie erneut kassieren.
Ist der offene Betrag vollständig vereinnahmt, schließt der Assistent Bestellung und Tisch.

Offene Grenzen, Datenrelevanz & Fiskalische Unverbindlichkeit#

Offenlegung der sichtbaren Daten#

Der KI-Assistent sieht ausschließlich den vom Kassen-Client übermittelten Kontext (UiState):

Die ID des aktuellen Bildschirms (z. B. pos.tables oder pos.settings.fiscal),
die aktive Tischnummer und Bereichs-ID,
sowie Produktnamen aus dem Artikelstamm.
Der Assistent sieht NIEMALS: Passwörter, Bediener-PINs, Kreditkartendaten, ungehashte Token oder unverschlüsselte Kundendaten.

Grenzen der KI-Ververlässlichkeit#

Keine eigene Finanzmathematik: Der Assistent führt keine eigenen mathematischen Berechnungen von Rechnungsbeträgen, Zwischensummen oder Steuern durch. Sämtliche Beträge werden ausschließlich vom Backend des Kassensystems berechnet.
Fehlermöglichkeiten: Bei mehrdeutigen Formulierungen kann der Assistent die Absicht des Bedieners missverstehen. Nutzen Sie in Zweifelsfällen die manuelle Bedieneroberfläche.
Kein dauerhaftes Gedächtnis: Der Gesprächsverlauf wird nicht in der Datenbank gespeichert. Ein Neuladen des Kassenfensters löscht den Dialogverlauf.

Keine Ersetzung des Steuer- und Prüfprotokolls (Fiskalische Unverbindlichkeit)#

WICHTIGER RECHTSHINWEIS: Die Antworten und Auskünfte des KI-Assistenten sind rein informativ und stellen keine steuerlich oder rechtlich verbindlichen Dokumente im Sinne der GoBD, KassenSichV oder DSFinV-K dar.

Der Assistent kann keine fiskalischen Belege ausstellen oder TSE-Signaturen erzeugen; er delegiert alle Aktionen strikt an die Fachdienste des Kassensystems (OrderService, PaymentService).
Revisionssicher und prüfungsrelevant sind ausschließlich die im unveränderlichen Audit-Protokoll (audit_entries) und in der TSE gespeicherten Transaktionen. Das System zeichnet bei jeder KI-unterstützten Aktion sowohl den KI-Akteur (actor="assistant") als auch den bestätigenden Benutzer unveränderlich auf (→ Kapitel 23).

Was passiert im Hintergrund#

Drei-Stufen-Verarbeitung (Tiered Inference Pipeline):
- Stufe 0 (Strikter Parser / parser.py): Formelhafte deutsche Kassenbefehle (wie "2x Cola auf Tisch 2", "Tisch 12 öffnen") werden direkt von einem lokalen Regelwerk ausgewertet. Dies erfolgt in Millisekunden, verbraucht 0 KI-Tokens und sendet keine Daten an externe KI-Dienste.
- Stufe 1 & 2 (LLM-Modell): Komplexere Fragen werden an das Sprachmodell (Qwen) weitergeleitet.
Einmalige Bestätigungs-Tokens mit SHA256-Fingerabdruck (ADR 0031):
- Bei verändernden Aktionen erzeugt das Backend einen einmaligen Bestätigungs-Token (PendingConfirmation). Dieser ist an einen order_fingerprint (SHA256-Hash aus Bon-Summe, Status, Artikelanzahl und Zeitstempel) gebunden.
- Der Token wird auf Datenbankebene atomar in einer einzelnen Transaktion eingelöst (UPDATE pending_confirmations SET is_used = true WHERE token = :t AND is_used = false).
- Wird ein Token ein zweites Mal gesendet, schlägt die Aktualisierung fehl und der Server bricht mit einer Fehlermeldung ab.
Audit-Protokollierung: Jeder Zug erzeugt das Ereignis assistant.turn, welches im revisionssicheren Audit-Log mit der Benutzer-ID des Freigebenden verankert wird.

Häufige Probleme#

0. `KI_NICHT_FREIGEGEBEN`#

Ursache: Der Betrieb hat dem KI-Assistenten nicht zugestimmt, oder die Einwilligung wurde widerrufen.
Lösung: Ein Administrator schaltet den Assistenten im Backoffice unter KI-Assistent ein. Andere Rollen sehen den Assistenten-Knopf erst danach.

0a. `KI_ANBIETER_GESPERRT`#

Ursache: Der konfigurierte Anbieter des Sprachmodells ist für echte Betriebe gesperrt, weil für die Datenübermittlung dorthin keine Grundlage vorliegt.
Lösung: Der Betrieb kann das nicht selbst beheben; der Assistent steht wieder zur Verfügung, wenn der Betreiber des Servers auf einen freigegebenen Anbieter wechselt. Auch eine frühere Einwilligung gilt so lange nicht.

1. `Assistant service is disabled`#

Ursache: Das Assistenten-Modul ist in der Kassenkonfiguration ausgeschaltet (ASSISTANT_ENABLED = false).
Lösung: Aktivieren Sie den Assistenten in den Systemeinstellungen des Kassensystems.

2. `LLM service is not configured (missing LLM_BASE_URL or LLM_API_KEY)`#

Ursache: Die Zugangsdaten zum Sprachmodell-Dienst fehlen in den Server-Einstellungen.
Lösung: Tragen Sie LLM_BASE_URL und LLM_API_KEY in der Systemkonfiguration ein.

3. `The order was modified after proposal. Please re-confirm.`#

Ursache: Die Bestellung am Tisch wurde von einem anderen Bediener verändert, während der Assistent auf die Bestätigung wartete (der SHA256-Fingerabdruck passt nicht mehr).
Lösung: Starten Sie die Anfrage an den Assistenten erneut, um einen aktuellen Vorschlag mit neuem Fingerabdruck zu erzeugen.

4. `Confirmation token has already been used.`#

Ursache: Der Bestätigungs-Token dieser Karte wurde bereits eingelöst (z. B. durch Mehrfachklicken auf Ausführen).
Lösung: Eine Mehrfacheinlösung wird vom System verhindert. Prüfen Sie, ob die Aktion bereits ausgeführt wurde.

5. `Invalid confirmation token.`#

Ursache: Der übermittelte Bestätigungs-Token ist ungültig, gefälscht oder abgelaufen.
Lösung: Erstellen Sie über den Assistenten eine neue Anfrage.

6. `Too many requests. Please try again later.`#

Ursache: Der angemeldete Benutzer hat die Ratenbegrenzung von 20 Anfragen pro Minute an den KI-Assistenten überschritten.
Lösung: Warten Sie eine Minute, bevor Sie erneut Fragen an den Assistenten stellen.

7. `Invalid, inactive, or unresolvable location_id for tenant`#

Ursache: Die im Kassen-Kontext übermittelte Standort-ID gehört nicht zum aktuellen Mandanten oder ist im System deaktiviert.
Lösung: Prüfen Sie die Standorteinstellungen an der Kasse und melden Sie sich neu an.

8. `Confirmation token is for {tool}`#

Ursache: Es wurde versucht, einen Bestätigungs-Token für ein anderes Werkzeug einzulösen als dasjenige, für das der Token ausgestellt wurde.
Lösung: Starten Sie die gewünschte Aktion neu über den Assistenten.

9. `Invalid location_id format. Must be a valid UUID.`#

Ursache: Die vom Kassen-Client gesendete Standort-ID entspricht nicht dem geforderten UUID-Format.
Lösung: Laden Sie die Kassenoberfläche neu, um den Standort-Kontext zu aktualisieren.

Grenzen#

Im Offline-Betrieb des Kassenterminals stehen nur einfache Stufe-0-Befehle eingeschränkt zur Verfügung; freie KI-Fragen erfordern eine aktive Serververbindung.
Der Gesprächsverlauf beschränkt sich im Kassenfenster auf maximal die letzten 10 Nachrichten innerhalb der aktuellen Sitzung.

Dieses Kapitel gehört zum Merkuron-Handbuch für Inhaber und Servicepersonal.