Telegram-Bot: Belegerfassung per Chat mit Datei-Upload und Kontext

[atraining]

Ziel

Ein Telegram-Bot, über den man unterwegs eine Eingangsrechnung abfotografiert oder als PDF hochlädt, der daraus eine Buchung vorschlägt, Rückfragen stellt und nach Bestätigung direkt in Collmex einbucht.

Anwendungsfall: Tankstelle, Restaurant, Hotel. Bon rausnehmen, Foto, Bot fragt "Lieferant Shell, 47,50 EUR, 19% VSt, Konto 4510 (Kfz-Kosten)? Bestätigen mit Ja". Einmal antippen, fertig.

Ausgangsbasis

Im Nachbar-Repo newsroom unter bot/telegram_bot.py läuft bereits ein funktionierender Telegram-Bot (Long-Polling, systemd auf Hetzner-VPS, single-file Python ohne python-telegram-bot). Der dient als Architektur-Blaupause. Zwei Dinge fehlen dort aber, die wir hier brauchen:

1. Datei-Upload (Photo + Document)

Der Wire-Bot verarbeitet nur message.text und ignoriert message.photo und message.document still. Für Collmex brauchen wir:

• Erkennung von photo/document in Telegram-Updates
• Download via Telegram getFile + file_path
• Ablage im GoBD-Belegarchiv (.collmex/belege/<jahr>/<monat>/) mit Hash-basiertem Dateinamen
• Weitergabe an einen LLM-Agent für Belegerkennung (Lieferant, Datum, Netto, USt, Positionen)
• Unterstützung für gängige Formate: JPG, PNG, HEIC, PDF

2. Conversation Context über mehrere Messages

Der Wire-Bot ist stateless. Jede Message öffnet eine frische LLM-Session ohne Erinnerung an vorherige. Für die typische Beleg-Flow brauchen wir das Gegenteil:

User: [sendet Foto]
Bot:  Ich erkenne: Shell, 47,50 EUR brutto, 19% USt.
      Lieferant Shell (70034)? Konto 4510 (Kfz-Kosten)?
      Bestätigen mit "ja", sonst korrigieren.
User: ja, aber Konto 4520
Bot:  Gebucht: 4510 -> 4520, 47,50 EUR brutto auf Kfz-Reparaturen.
      Belegnummer 2026-04-0891.

Dafür brauchen wir pro Chat-ID eine Session:

• Letzte N Messages (User + Bot) als Kontext
• Pending Action: "wartet auf Bestätigung der Buchung X"
• TTL pro Session (z.B. 30 Min Inaktivität, danach Reset)
• Persistenz auf Platte (JSON-Datei oder SQLite), damit Neustarts Sessions nicht verlieren

Technische Skizze

Telegram Update
  |
  +-- Text?
  |     |
  |     +-- Befehl (/status, /hilfe)? -> direkte Antwort
  |     |
  |     +-- Antwort auf pending Action? -> Session laden, weiterverarbeiten
  |     |
  |     +-- Freitext ohne Kontext? -> LLM mit System-Prompt + Collmex-CLI
  |
  +-- Photo/Document?
        |
        +-- Download + Hash + Ablage in .collmex/belege/
        +-- OCR/Extraction via LLM (Anthropic Messages API mit Vision/PDF)
        +-- Vorschlag erzeugen (Lieferant, Konto, USt)
        +-- Session auf "pending_booking" setzen
        +-- Rückfrage an User senden

Datei-Layout (Vorschlag)

collmex/
  bot/
    __init__.py
    telegram.py          # Polling + Dispatcher
    session.py           # Per-chat Session-State (SQLite-backed)
    handlers/
      text.py            # Freitext + Befehle
      photo.py           # Photo-Upload
      document.py        # PDF-Upload
    extraction.py        # LLM-basierte Belegerkennung
    prompts.py           # System-Prompts

Abhängigkeiten

• Issue collmex buchen --dry-run sollte keine Collmex-Credentials brauchen #4 (buchen --dry-run ohne Credentials): der Bot muss den Booking-Vorschlag trocken rechnen können, bevor er echte Credentials an Collmex schickt.
• GoBD-Belegarchiv-Pfad muss existieren (collmex/gobd.py hat das schon).
• Bot braucht eigene Credentials (getrennter .env auf dem VPS), nicht die Dev-Credentials.

Sicherheit

• BOT_ALLOWED_CHATS-Allowlist wie im Wire-Bot (kein offener Chat)
• Jede Buchung braucht explizite Bestätigung — niemals stillschweigend buchen
• Jede Buchung als --dry-run präsentieren, erst auf "ja" echte Buchung
• Session-DB und Beleg-Archiv verschlüsselt am besten via LUKS/ZFS, mindestens Dateiberechtigung 600

Offene Punkte

• Welcher VPS? Eigener oder Piggyback auf Wire-VPS?
• Welches LLM-Modell für Extraction (Vision-fähig, kostengünstig für Massenerfassung)?
• Sprache des Bots: nur Deutsch oder auch Englisch?
• Multi-Mandant-fähig oder ein Bot pro Firma?
• Integration mit den wöchentlichen Routinen aus wissen/routinen.md — kann der Bot den Mahnlauf anstoßen, die OPOS-Liste ausgeben?

MVP-Scope

Für den ersten Wurf reicht:

1. Photo-Upload mit einfacher LLM-Extraktion
2. Vorschlag für Lieferant/Konto/USt im Chat
3. Bestätigung per "ja"
4. Ausführung via collmex buchen
5. Bestätigung zurück an den User

Kontext-Persistenz nur für den aktiven Flow (Pending-Booking), keine Chat-History. Die volle History kommt in Iteration zwei.