Abschlussprojekt

Ziel dieses Dokuments ist es, eine vollständige, professionelle Integrationslösung für das beschriebene Multi-Channel-Szenario zu entwerfen. Es enthält die Architektur-Übersicht, detaillierte Workflow-Pläne und die wichtigsten Datenmodelle & Konfigurationen.

1 — Architektur-Übersicht

Kurzbeschreibung der Gesamtarchitektur

  • Zentraler Integrations-Dreh- und Angelpunkt ist Xentral (führendes System).

  • Für jeden funktionalen Bereich existieren entkoppelte, spezialisierte Workflows, um Single Responsibility, Observability und Wiederverwendbarkeit zu gewährleisten.

  • Workflows kommunizieren über den Data Store (persistente Queue / Tables) und Ereignisse (Event-Driven) miteinander, wo möglich in Echtzeit; batch- bzw. scheduler-getriebene Prozesse sind für Nachtläufe oder periodische Exporte vorgesehen.

  • Fehlerhafte Datensätze werden in einer Error-Queue persistiert; ein dedizierter "Error-Repair"-Workflow erlaubt manuelle Korrektur und Retry.

  • Externe Systeme:

    • Shopify (REST Admin API, Webhooks)

    • B2B-Marktplatz (REST + OAuth2, Webhooks)

    • Retailer (SFTP: Bestell-CSV-In, Lieferschein-PDF-Out)

    • Xentral (Xentral-Konnektor, Events für Lieferschein/Rechnung)

Geplante Workflows (Kurzliste)

  • Product & Inventory Sync (Nachtlauf + stündlicher Retailer CSV)

  • Product Upsert Batcher (API rate-limit aware)

  • Shopify Webhook Receiver → Order Import

  • B2B-Marktplatz Webhook Receiver → Order Import (inkl. Customer-Lookup)

  • Retailer SFTP Poller → Order Import (15-minütig)

  • SKU-Normalizer & Mapping (Retailer-Suffix)

  • Order Processing & Validation (inkl. Error-Queue)

  • Shipping Notification Dispatcher (event-driven)

  • Invoice Collector & Daily Exporter

  • Error-Repair UI/Workflow (manueller Retry)

  • Monitoring & Alerting (Admin-Benachrichtigung bei kritischen Fehlern)

Mermaid-Diagramm (komplett, alle Workflows, Trigger und Systeme)

Hinweis: Das Diagramm zeigt die Verantwortlichkeiten: Synchronisation-Batches sind separat von Echtzeit-Webhook-Pfaden; alle asynchronen/fehleranfälligen Übergaben laufen über den Data Store / Queues.

2 — Detaillierte Workflow-Pläne

Jeder Workflow wird schrittweise beschrieben. Wo vorher numerierte lange Schritte auftreten, sind diese als Stepper dargestellt.

1

Product & Inventory Sync (Nightly) — Xentral → Shopify, B2B-Marktplatz

Zweck: Nächtliche Voll- bzw. inkrementelle Synchronisation aller aktiven Artikel inkl. Preis- und Bestandsänderungen.

Ablauf:

  • Trigger: Scheduler (einmal pro Nacht).

  • Schritt 1: Fetch Upfront — Alle aktiven Artikel-Metadaten (SKU, Title, Beschreibung, Preise, Varianten, Lagerlocation) aus Xentral in Seiten (Pagination) lesen und in Memory/Temp-Store vorhalten.

  • Schritt 2: Differenzermittlung — Vergleiche zu letztem Snapshot (im Data Store) um nur geänderte Items zu senden.

  • Schritt 3: Batch-Bildung — Batches nach Kanal-spezifischen Limit-Strategien (z.B. Shopify: Batch-Größe 20, 1s Delay nach N Requests; B2B: Batch-Größe 50).

  • Schritt 4: Product Upsert via Product Upsert Batcher (siehe separater Workflow). UID-Mapping (Xentral product_id ↔ Channel product_id) in Assignment Table persistieren.

  • Schritt 5: Ergebnis-Logging — Erfolge in Audit-Table, Fehler in Error-Queue.

  • Rückfall: Wenn Channel-API Raten-Limit erreicht, wird Exponential Backoff angewandt und Batch erneut in Queue gelegt.

Wesentliche Knoten:

  • Fetcher (Xentral API)

  • Differ Engine ( Snapshot-Vergleich )

  • Batcher (Channel-spezifisch)

  • Retry / Backoff Handler

  • Audit Logger

Konzept zur Raten-Limit-Vermeidung:

  • Fetch Upfront um viele kleine GETs zu vermeiden.

  • Channel-spezifische Batching + token-bucket throttling.

  • Parallelität limitiert pro Kanal.

  • Dead-letter Queue für dauerhaft fehlerhafte Items.

2

Product Upsert Batcher (shared)

Zweck: Kanal-spezifischer Sender mit Rate-Limit-Logik und Retry.

Ablauf:

  • Trigger: Accepts batches vom Product & Inventory Sync oder manuellem Trigger.

  • Schritt 1: Für jeden Batch: Annotate mit Channel-Config (rate-limit, max-concurrency).

  • Schritt 2: Sende Requests sequenziert/parallel innerhalb Limits.

  • Schritt 3: On 429 oder transient Fehler: Queue-Item mit exponentially increasing delay.

  • Schritt 4: Auf dauerhafte Fehler: Move to Dead-letter / Error-Queue.

Wesentliche Knoten:

  • Throttler (token-bucket)

  • Sender

  • Response-Mapper (speichert channel-product-id Mapping)

  • Error-Handler

3

Retailer Stock CSV Export (Hourly) — Xentral → Retailer SFTP

Zweck: Retailer erwartet stündlich CSV mit "sku,stock".

Ablauf:

  • Trigger: Scheduler (stündlich).

  • Schritt 1: Query Xentral für SKUs & aktuelle Lagerbestände.

  • Schritt 2: CSV-Generierung (Header: sku,stock). Nur SKUs, keine Produktdaten.

  • Schritt 3: Atomarer Upload auf SFTP (zuerst temporäre Datei, dann atomic rename).

  • Schritt 4: Log/Verifiy (optional: checksum).

  • Fehler: Bei SFTP-Ausfall -> Retry mit Backoff, bei Dauerfehler -> Admin-Benachrichtigung.

Beispiel CSV:

4

Shopify Webhook Receiver → Order Import

Zweck: Echtzeit-Import von Shopify-Bestellungen nach Xentral.

Ablauf:

  • Trigger: HTTP-Webhook von Shopify.

  • Schritt 1: Authentifiziere und validiere Webhook-Signatur.

  • Schritt 2: Normalisiere Bestelldaten (LineItems → sku, qty, price).

  • Schritt 3: Check SKU-Mapping (Data Store: xentral_sku_lookup). Wenn SKU fehlt -> Fehlerfall (siehe Error-Handling).

  • Schritt 4: Anreichern: Customer-Lookup (per Email / externe Referenz). Wenn Kunde unbekannt -> Create-Customer in Xentral (oder in Error-Queue je nach Policy).

  • Schritt 5: Auftrag in Xentral anlegen via Xentral-Konnektor.

  • Schritt 6: Antwort an Shopify (200 OK). Audit-Eintrag.

Wesentliche Knoten:

  • Webhook-Validator

  • Order Normalizer

  • SKU Resolver

  • Customer Resolver

  • Xentral Creator

5

B2B-Marktplatz Webhook Receiver → Order Import (inkl. USt-IdNr. Customer-Lookup)

Zweck: Echtzeit-Import von B2B-Bestellungen und Identifikation/Anlage von Geschäftskunden über USt-IdNr.

Ablauf:

  • Trigger: HTTP-Webhook vom B2B-Marktplatz.

  • Schritt 1: OAuth2-gesicherter Kommunikation (Token-Refresh handled zentral).

  • Schritt 2: Order Normalizer.

  • Schritt 3: Customer-Lookup: Suche nach USt-IdNr. Falls gefunden -> verknüpfen, sonst -> Kunde neu anlegen (Kreditlimit/Tax-Handling beachten).

  • Schritt 4: SKU-Resolving & Menge.

  • Schritt 5: Auftrag an Xentral senden.

  • Fehler: Unbekannte SKU -> Datensatz in Error-Queue (inkl. Raw Payload + Diagnose).

  • Rate-Limits: Webhook-Payloads sind selten; Upstream API Calls (z.B. zur Validierung) werden rate-limited.

Wesentliche Knoten:

  • OAuth2 Token Manager

  • Customer Lookup (USt-IdNr.)

  • Validation & Enrichment

  • Xentral Auftragscreate

6

Retailer SFTP Poller → Order Import (15-minütig)

Zweck: Alle 15 Minuten prüft ein Poller neue CSV-Bestellungen auf dem SFTP-Server; jede Datei enthält genau eine Bestellung.

Ablauf:

  • Trigger: Scheduler (alle 15 Minuten).

  • Schritt 1: Connect to SFTP (Key/Auth) — robustes Error-Handling und Retries.

  • Schritt 2: List new files (z.B. nach Timestamp oder processed-folder pattern).

  • Schritt 3: Für jede Datei: Download, Parse CSV → Order Payload.

  • Schritt 4: SKU Normalizer: Entferne Retailer-Suffix -RTL aus allen SKUs vor Mapping.

    • Beispiel: "PEN-RED-RTL" → "PEN-RED"

  • Schritt 5: SKU Auflösung (Data Store Lookup) → wenn nicht gefunden → Error-Queue.

  • Schritt 6: Auftrag in Xentral anlegen.

  • Schritt 7: Move processed file to archive folder / mark as processed (atomic rename).

  • Fehlerhandling:

    • Parsing-Fehler → Error-Queue mit raw file.

    • SFTP unreachable → Critical Alert (Admin).

Wesentliche Knoten:

  • SFTP Client

  • Parser

  • SKU Normalizer

  • Xentral Auftragscreate

  • Archiver

7

SKU Normalizer & Mapping

Zweck: Einheitliche SKU-Repräsentation, Retailer-Suffix-Handling und Kanal-Mapping.

Ablauf:

  • Eingangsregel für Retailer: entferne Suffix -RTL (RegEx: ^(.*?)(-RTL)?$).

  • Lookup in Assignment Table: xentral_sku ↔ channel_sku (bidirektional).

  • Falls Mapping fehlt:

    • Für Webhooks: Markiere Fehler → Error-Queue.

    • Für Batch-Import: Optionally markiere und versuche Fuzzy-Match (optional, konfigurierbar), ansonsten Error-Queue.

  • Persistenz: Assignment Table im Data Store mit Audit-Fields (created_by, created_at).

Wesentliche Knoten:

  • Normalizer-Funktion

  • Assignment Table Lookup

  • Fuzzy Match (configurable)

8

Order Processing & Validation (Shared)

Zweck: Validierung, Preisprüfung, Fraud-Checks (falls konfiguriert) und finale Auftragserstellung in Xentral.

Ablauf:

  • Input: Normalized Order-Payload (aus Webhooks oder Poller).

  • Validierungen:

    • SKU existiert

    • Kundeninformation vorhanden oder anlegbar

    • Zahlungs- und Versandinformationen valide

  • Falls valid: Erstelle Auftrag via Xentral-Konnektor.

  • Falls invalid: Schreibe vollständigen Payload + Fehler-Metadaten in Error-Queue.

  • Nebenaufgabe: Generiere Audit-Event für downstream Prozesse (Shipping, Billing).

Wesentliche Knoten:

  • Validator

  • Xentral-AuftragsClient

  • Error-Queue-Schreiber

9

Shipping Notification Dispatcher (Event-Driven)

Zweck: Versandevents (Lieferscheine) in Xentral an Kanäle zurückmelden; Lieferschein PDF für Retailer erzeugen und auf SFTP ablegen.

Ablauf:

  • Trigger: Xentral Event "Lieferschein erstellt".

  • Schritt 1: Event-Consumer validiert Event (Auftrag ID, Kanal).

  • Schritt 2: Fetch Tracking-Info aus Xentral (Tracking-Nummer, Carrier).

  • Schritt 3: Kanal-spezifische Update-Aufrufe:

    • Shopify: Fulfillment/Tracking-Update via REST

    • B2B-Marktplatz: Status-Update API

    • Retailer: PDF-Lieferschein erzeugen (PDF Generator) und auf SFTP ablegen (atomic put)

  • Schritt 4: Persistiere Versand-Event in Audit-Log.

  • Fehler: On SFTP write-fail -> Retry + Admin-Alert bei Dauerfehlern.

Wesentliche Knoten:

  • Event-Consumer

  • Channel-Adapter (Shopify / B2B / Retailer)

  • PDF-Generator

  • SFTP-Uploader

10

Invoice Collector & Daily Exporter

Zweck: Rechnungen für B2B-Marktplatz und Retailer zwischenspeichern und täglich gesammelt an Buchhaltungssysteme übertragen (hier: simuliert durch Log-Eintrag).

Ablauf:

  • Trigger: Xentral Event "Rechnung erstellt" → Invoice Collector schreibt Rechnung (PDF/Meta) in Data Store per Kanal.

  • Täglich: Invoice Daily Exporter sammelt alle neuen Rechnungen und überträgt sie an die jeweiligen Buchhaltungssysteme (hier: Log-Eintrag).

  • Nach erfolgreichem Export: Markiere as exported.

Wesentliche Knoten:

  • Invoice Collector

  • Export Scheduler

  • Export Logger (Simulierte Übertragung)

  • Reconciliation-Table

11

Error-Handling Allgemein & Error-Repair Workflow

Zweck: Einheitliches Fehlermanagement, Persistenz defekter Datensätze und manuelle Wiederherstellung.

Ablauf (Error-Queue):

  • Fehlerhafte Datensätze (z.B. unbekannte SKU, Parsing-Fehler) werden mit folgendem Payload gespeichert:

    • raw_payload

    • error_code

    • error_message

    • source_workflow

    • created_at, retry_count

  • Fehler werden nicht sofort verworfen; sie sind für Review zugänglich.

Error-Repair Workflow (für Sachbearbeiter):

  • Trigger: Manuell per UI / Admin-Trigger.

  • Schritt 1: Lade Eintrag aus Error-Queue.

  • Schritt 2: Sachbearbeiter korrigiert Daten im Data Store (z.B. SKU mapping ergänzen, CSV korrigieren).

  • Schritt 3: Trigger "Retry Single Record" — speichert korrigiertes Payload in Verarbeitung-Queue mit Ursprungshandling (idempotenz beachtet).

  • Schritt 4: Workflow behandelt den Datensatz erneut; bei Erfolg: Error-Queue-Eintrag markiert resolved.

Kritische Fehler:

  • Beispiel: SFTP nicht erreichbar → Mail an Admin-Verteiler + Monitoring-Eintrag.

  • Bei kritischen recurring failures: Auto-Escalation nach konfigurierbaren Thresholds.

(Die Error-Repair Logik ist interaktiv; hier ist nur das Design dokumentiert.)

3 — Datenmodelle & Konfiguration

Wichtige Data Structures und Assignment Tables. Diese Tabellen sind persistente Entities im Data Store.

  1. SKU Assignment Table

  • Zweck: Bidirektionales Mapping zwischen Xentral-SKU und Kanal-SKU.

  • Struktur:

Field
Type
Beschreibung

id

string

Primärschlüssel

xentral_sku

string

SKU in Xentral

channel

string

z.B. shopify, b2b, retailer

channel_sku

string

SKU im Kanal

created_by

string

wer erstellt hat

created_at

datetime

updated_at

datetime

  1. Channel Configuration Table

  • Zweck: Storing API endpoints, auth, rate-limits, batch-sizes.

Field
Type
Beschreibung

id

string

channel

string

shopify / b2b / retailer

base_url

string

vollständige URL (mit Query params wenn nötig)

auth

json

credentials / OAuth config

rate_limit

json

e.g. { "max_requests": 100, "per_seconds": 60 }

batch_size

int

empfohlene Batch-Größe

created_at

datetime

  1. Error-Queue Table

  • Zweck: Persistente Speicherung fehlerhafter Datensätze.

Field
Type
Beschreibung

id

string

source_workflow

string

z.B. retailer-sftp-poller

raw_payload

json/text

Originaldaten

error_code

string

z.B. SKU_NOT_FOUND

error_message

text

Debug-Info

retry_count

int

created_at

datetime

resolved

boolean

  1. Invoice Store

  • Zweck: Speicherung der Rechnungs-PDFs / Metadaten zur täglichen Aggregation.

Field
Type
Beschreibung

invoice_id

string

Xentral Invoice ID

channel

string

b2b / retailer

pdf_blob

binary/ref

Link oder Blob im Data Store

metadata

json

amount, date, order_ref

exported

boolean

default false

created_at

datetime

  1. Audit Log (Events)

  • Zweck: Nachvollziehbarkeit aller Aktionen (sync/calls/errors).

Field
Type
Beschreibung

id

string

event_type

string

e.g. product_update, order_import

source

string

workflow name

payload_ref

ref

pointer auf relevant data

status

string

success/failure

created_at

datetime

Konfigurationsempfehlungen

  • Secrets & Keys: zentral verwaltet (Secret Store), nicht in plain config.

  • OAuth2: Token-Refresh-Service zentral implementieren (B2B).

  • SFTP: Key-Pair Auth, IP-Failover Config.

  • Throttling: Channel-spezifische Token-Buckets konfigurierbar.

4 — Fehlerbehandlung & Monitoring (Detail)

  • Fehlerklassifizierung:

    • Transiente Fehler: 429, Netzwerkprobleme → Retry mit Backoff.

    • Datenfehler: Missing SKU, invalid payload → persist in Error-Queue.

    • Kritische Infrastrukturfehler: SFTP unreachable, Xentral auth broken → Admin-Alert + Incident-Ticket.

  • Retry-Strategien:

    • Transient: Exponential Backoff, max_retries configurable (z.B. 5).

    • Dauerhafte Failure → Dead-letter / Error-Queue.

  • Observability:

    • Metrics: queue_depth, success_rate, avg_processing_time, failed_jobs.

    • Dashboards für jede Pipeline (Sync, Orders, SFTP).

    • Alerts: Thresholds (z.B. Error-Queue > N, SFTP down > 5min).

  • Admin-Benachrichtigung:

    • E-Mail / PagerDuty Integration bei kritischen Fehlern.

    • Beispiel-Trigger: SFTP unreachable after 3 retries, repeated authentication failures.

Expandable: Error-Repair Flow (für Sachbearbeiter)

Error-Repair Workflow — Ablauf für Sachbearbeiter

  1. Sachbearbeiter öffnet Error-Queue UI und filtert nach Source/Fehlercode.

  2. Einsicht in raw_payload und vorgeschlagene Diagnose (Automatische Hinweistexte).

  3. Korrektur: z.B. SKU Mapping ergänzen (-> SKU Assignment Table update), CSV korrigieren oder Kundendaten ergänzen.

  4. Klick auf "Retry" — der Datensatz wird markiert und in die Verarbeitung-Queue zurückgeführt (idempotent, mit correlation_id).

  5. Nach erfolgreichem Retry wird Error-Queue-Eintrag als resolved markiert und ein Audit-Eintrag geschrieben.

5 — Security & Idempotency

  • Idempotency Keys: Bei allen Aufrufen zu Xentral und Channel-APIs Idempotency-Header verwenden, falls unterstützt.

  • Authentication:

    • Shopify: HMAC-Webhook Verification + API Key

    • B2B: OAuth2 (Client Credentials oder Authorization Code mit Refresh)

    • SFTP: Key Based Auth

  • Least Privilege: API-Credentials mit minimalen Rechten für die jeweiligen Aktionen.

  • Sensitive Data: Keine sensiblen Daten in Logs; Maskierung von Payment-Daten.

6 — Operational Notes & Deliverables

Was in der Preset Instance enthalten sein sollte

  • Struktur der Workflows (als Xentral Connect Workflows), z. B.:

    • product-sync (Scheduler)

    • product-upsert-batcher

    • shopify-webhook-receiver

    • b2b-webhook-receiver

    • retailer-sftp-poller

    • sku-normalizer

    • order-processor

    • shipping-dispatcher

    • invoice-collector

    • invoice-daily-exporter

    • error-repair-workflow

  • Data Store Schemas (tables): SKU Assignment, Channel Config, Error-Queue, Invoice Store, Audit Log.

  • Beispiel-Configs für Channel Credentials (als Placeholder, nicht echte Keys).

  • Beispiel-Mappings (einige SKU-Zuordnungen).

  • Scheduler-Konfigurationen (15min poller, hourly CSV, nightly sync, daily invoice export).

Hinweis zur Einreichung (wie gefordert)

  • Lösungsdokument (dieses Markdown).

  • Export der "Preset Instance" als ZIP, die die oben genannten Workflow-Strukturen, Data Store-Schemas und Beispiel-Konfigurationen enthält.

Wenn du möchtest, kann ich als nächsten Schritt:

  • Eine konkrete JSON-Schema-Definition für die wichtigsten Data Structures erstellen (z.B. Error-Queue, SKU Assignment).

  • Beispiel-Implementierungen der wichtigsten Workflow-Knoten in Pseudocode oder als detaillierte Node-By-Node Beschreibung ausarbeiten.

  • Eine Checkliste für die Preset-Instance-Erstellung liefern (welche Dateien/Flows exakt exportiert werden sollen).

Was möchtest du als Nächstes?

PreviousKursübersicht und LernzieleNextÜberblick & Setup

Was this helpful?