Cron-Jobs und Hintergrund-Aufgaben

KI

Status — Code-verifiziert (Welle 82)

SpeamCore hat zwei getrennte Job-Systeme im Backend:

1. Statisch-konfigurierte Cron-Tasks in api.speamcore.com/src/server.ts via node-cron-Library (mit cron.schedule(...)-Aufrufen). Diese sind hardcoded und laufen pro App-Instanz.
2. Dynamische User-Cron-Jobs verwaltet über das CronJob-Modell mit Service cronJob.service.ts. Anwender legen sie im UI an unter /cron-jobs. Dieses System nutzt Anthropic/OpenAI-API für KI-getriebene Cron-Aktionen + Standard-Provider-Definitionen.

Daneben gibt es Worker-basierte Aufgaben (BullMQ + Redis) für asynchrone Verarbeitung — siehe Sync und Jobs.

SpeamCore hat automatisierte Hintergrund-Aufgaben — sie laufen ohne dass jemand klickt, halten das System aktuell und erinnern an Termine.

Drei Job-Systeme im Überblick

Statische Cron-Tasks (server.ts, Stand 2026-05-05)

Diese sind in src/server.ts per cron.schedule(...) hardcoded — Frequenzen können nur durch Code-Deploy geändert werden:

Task	Cron-Expression	Frequenz	Was tut er?
masterStatusTask	*/5 * * * *	alle 5 min	Master-Service-Status-Check
dataTransferPollTask	*/5 * * * *	alle 5 min	Pending DataTransfer-Imports verarbeiten
roleMailboxSyncTask	0 * * * *	stündlich	Rollen-Mailbox-Regeln syncen
unitSyncTask	0 2 * * *	täglich 02:00	Unit + HsCode-Sync
complianceCheckTask	0 2 * * *	täglich 02:00	Tägliche Compliance-Checks erzeugen
chatCleanupTask	15 3 * * *	täglich 03:15	Leere Chats löschen

BullMQ-Worker (asynchrone Verarbeitung, Redis-basiert)

Aus src/workers/:

Worker	Zweck
document-content-extraction-worker	Text aus PDFs / Office-Dokumenten extrahieren
mail-sync-worker	Imap/Graph-Mail-Synchronisation
hs-code-classification-worker	HS-Code-Klassifikation für Produkte
translation-queue-worker	i18n-Übersetzungen verarbeiten
elasticsearch-sync-worker	Search-Index aktualisieren
contact-enrichment-worker	Kontaktdaten anreichern

Erfolg vs Fehler

Jeder Job-Lauf wird im Cron-Logs protokolliert:

• Job-Name
• Start + Ende
• Status (success / error / partial)
• Verarbeitete Datensätze
• Fehler-Meldung (falls error)

Idempotenz — wichtig!

Alle Jobs müssen idempotent sein — mehrfache Ausführung darf nicht zu doppelten Effekten führen.

Beispiele aus dem Code:

• complianceCheckTask läuft 2x am gleichen Tag → findOrCreate in der Engine verhindert doppelte Compliance-Einträge (Default-Datum „gestern" bleibt stabil)
• dataTransferPollTask läuft auf vergangene Imports → bereits-verarbeitete bekommen processedAt-Flag und werden geskippt
• mail-sync-worker läuft auf gleiche Mail-Konten → IMAP-UID-Tracking verhindert doppelten Import

Bei Job-Fehler

Manueller Trigger (User-CronJobs)

Die im UI angelegten User-Cron-Jobs unter /cron-jobs haben drei manuelle Aktionen (verifiziert in cronJob.router.ts):

• POST /api/cron-jobs/:id/execute — Job sofort ausführen
• POST /api/cron-jobs/:id/simulate — Trockenlauf ohne Effekt
• POST /api/cron-jobs/:id/generate-actions — Actions aus Konfiguration neu erzeugen

Statische server.ts-Cron-Tasks haben keinen UI-Trigger — Änderungen erfordern Code-Deploy.

Wann nützlich?

• Vor wichtigen Berichten (BWA, Compliance-Stichtag)
• Nach System-Wartung („alle User-Cron-Jobs neu anstoßen")
• Bei Tests von Job-Konfigurations-Änderungen

Verzögerte Jobs (BullMQ-Queues)

Manche Aufgaben sind nicht zeitgesteuert, sondern werden in eine BullMQ-Queue geschoben (Redis-basiert). Konkrete Queues entsprechen den Workers in src/workers/:

• document-content-extraction — Volltext-Extraktion nach Datei-Upload
• mail-sync — Mail-Sync nach Verbindungs-Anfrage
• hs-code-classification — Klassifikation nach Produkt-Anlage
• translation-queue — i18n-Strings übersetzen
• elasticsearch-sync — Search-Index aktualisieren
• contact-enrichment — Kontaktdaten anreichern

Queue-Worker arbeiten Aufgaben in Reihenfolge ab, mit Retry-Logik bei Fehlern (BullMQ-Standard mit exponentieller Backoff-Strategie).

Performance-Effekt

Schwere Jobs (z.B. Inventur-Stichtag bei 100k Produkten) laufen nachts — geringer User-Impact. Light-Jobs (Notification, Health-Check) laufen häufig, aber kurz.

Wichtige Stunden (System-Last):

• 06:00-18:00 — User-Aktivität, leichte Jobs
• 18:00-06:00 — Heavy Jobs erlaubt

Anti-Pattern

• ❌ Job ohne Idempotenz — bei Re-Run doppelte Effekte
• ❌ Job ohne Logging — bei Fehler nicht nachvollziehbar
• ❌ Job ohne Timeout — kann ewig hängen, Folge-Jobs blockieren
• ❌ Synchroner Versand an alle MAs in einem Job — bei 1000 MAs 30+ min, blockiert Folge-Jobs
• ❌ Audit-Log löschen in einem Job — gesetzeswidrig

KI-Chat-Anwendungen

Welche Cron-Jobs sind in den letzten 7 Tagen mit Fehler gelaufen?
Mit Job-Name, Häufigkeit und letzter Fehler-Meldung.

Welche Jobs haben die längsten durchschnittlichen Laufzeiten?
Mit Trend gegenüber letztem Monat.

Verwandte Doku

• Cron-Jobs überwachen (Admin) — operativ
• Sync und Jobs — technisch
• Notification-System — der häufigste Job-Konsument
• Audit-Trail-Architektur — was Jobs wo loggen