Sync- und Hintergrund-Jobs
Zweck
Viele Workflows in SpeamCore laufen asynchron im Backend — sei es periodischer Sync mit externen Systemen, eingehende Webhooks oder rechenintensive Operationen. Die Plattform verwendet BullMQ mit Redis als Job-Queue. Diese Konzept-Seite gibt eine Übersicht über die Job-Familien, ihre Trigger und Fehler-Behandlung — damit du in Modul-Doku nicht jedes Mal das Pattern erklaeren musst.
Job-Familien
1. Cron-Jobs (zeitgesteuert)
Pflege über /cron-jobs. Beispiele:
- Wiederkehrende Erzeugung von Buchungen aus Ausgaben (
recurring/contract/credit). - Periodische Notification-Events (z. B. Wartungs-Erinnerung).
- Daten-Health-Checks (z. B. abgelaufene
expiresAt-Felder bei Course-Enrollments).
Lock-Mechanismus: lockedBy + lockedAt verhindert Doppellauf bei Multi-Worker-Setups.
2. Externer Sync
| Provider | Was wird synchronisiert | FE-Steuerung |
|---|---|---|
| finAPI | Bank-Konten und Bank-Transaktionen | TransactionAccounts → finAPI-Modal |
| Pleo | Kreditkarten-Konten und -Transaktionen | TransactionAccounts → Pleo-Modal |
| Microsoft Graph | Mails, Mailboxes, Calendar-Events | Mail-Konten |
| Shopify | Produkte, Bestellungen, Kunden | Shopify-Stores |
| Speambox / MQTT | Sensor-Daten, Geraete-Status | Speamboxes, Speambox-System-Types |
Sync-Lauf wird typischerweise:
- per Cron-Job (z. B. alle 15 Min) angestossen,
- bei Bedarf manuell über UI-Button (z. B. „Sync ausführen" in Categories oder einer Mailbox).
3. Webhook-getriggerte Jobs
Für eingehende Events (z. B. neue Mail von Microsoft Graph, finAPI-Notification, Shopify-Webhook). Ein Webhook-Endpoint legt einen Job in BullMQ; der Worker verarbeitet asynchron.
4. Asynchrone Operationen
- Datentransfer-Exporte und -Importe.
- Import-Jobs mit Chunk-weisem Verarbeiten.
- Trash-Hard-Delete grosser Datenmengen.
- Match-Engine bei manuellem Matching-Lauf.
5. Notification-Versand
Siehe Notification-System — Events erzeugen Logs und werden über Channels (Mail, Push, MS Teams) verschickt; Versand laeuft in BullMQ.
Status und Fehler-Behandlung
Jeder Job hat:
| Status | Bedeutung |
|---|---|
pending | Wartet in der Queue |
running | Wird gerade ausgeführt |
completed | Erfolgreich beendet |
failed | Fehler — Stack-Trace gespeichert |
delayed / paused | BullMQ-spezifische Zustaende |
Retry-Logik: BullMQ wiederholt fehlgeschlagene Jobs typischerweise mit Exponential-Backoff. Nach N Fehlversuchen bleibt der Job failed.
Job-Ereignis-Audit: Jobs koennen optional Events in JobActivity oder modul-spezifische Aktivität-Logs schreiben — z. B. DocumentActivity bei Document-Transformationen.
Lock-Mechanismus (Cron-Spezial)
Bei CronJob schreibt der Worker beim Beginn:
lockedBy = <workerId>lockedAt = now
Andere Worker, die den Job in ihrer Queue sehen, ueberspringen ihn, solange lockedBy != null. Der Lock wird beim Beenden gelöscht. Bei Worker-Crash bleibt der Lock haengen — manuelle Korrektur über /cron-jobs/:id notwendig.
Berechtigungen
| Action | Subject | Wirkung | Keycloak-Rolle |
|---|---|---|---|
view | CronJob | Cron-Liste | APP_SPEAMCORE_VIEW_CRON_JOB |
do | RunCronJob | Manuell ausloesen | APP_SPEAMCORE_DO_RUN_CRON_JOB |
view | JobActivity | Job-Audit-Log einsehen | APP_SPEAMCORE_VIEW_JOB_ACTIVITY |
view | FinapiConfig, PleoConfig, ShopifyConfig | Externe-Sync-Konfiguration | APP_SPEAMCORE_VIEW_FINAPI_CONFIG, PLEO_CONFIG, SHOPIFY_CONFIG |
Wiederverwendbare Konzepte
- Notification-System — Spezialfall eines Job-Konsumenten.
- Auto-Allocation — laeuft als Job.
- Berechtigungen verstehen (CASL)
Verknuepfungen zu Modulen
- Cron-Jobs — zeitgesteuerte Jobs verwalten.
- Notification-Logs — Versand-Historie.
- Mail-Konten, TransactionAccounts, Shopify-Stores, Speamboxes — Sync-Verbraucher.
- Datentransfer, Import — asynchrone Operationen.
Versionshinweise
- 2026-04-30: Initiale Veroeffentlichung als Querschnitts-Konzept.