Session-Lebenszyklus¶

Eine Session ist ein Lieferakt: ein Lieferant, ein Zeitraum, ein Satz Dateien, geführt durch die Verarbeitungs-Pipeline. Sie bindet einen DataContract, die Transformer und Entities ihres Projekts, die hochgeladenen Dateien und jeglichen Session-Kontext.

Der Zustandsautomat¶

CREATED → UPLOADED → PARSED → TRANSFORMED → VALIDATED → CONFIRMED → APPROVED → EXPORTED

Stufe	Was passiert
Parse	Rohdateien werden über Python-native Parser zu Parquet.
Transform	SQLGlot kompiliert Mappings; DuckDB führt sie aus.
Validate	Entity-Regeln laufen als DuckDB-Verletzungsabfragen.
Reconcile	Projekt-Regeln laufen als entity-übergreifende JOINs.
Confirm / Approve	Ein Mensch gibt frei (einfache oder doppelte Freigabe).
Export	Das konfigurierte Formatpaket wird erzeugt.

Massendaten landen nie im Python-Speicher — Python generiert SQL, DuckDB erledigt die Arbeit auf Parquet im Object Storage.

Health vs. Stufe¶

Eine Session hat sowohl eine Stufe (wo in der Pipeline) als auch eine Health (blockiert etwas — z. B. ERROR-Verstöße). Die Sessions-Ansicht verfolgt beides, sodass Sie auf einen Blick sehen, welche Lieferungen Aufmerksamkeit brauchen.

Fehlertypen — Format, Inhalt, System¶

Wenn eine Stufe fehlschlägt, klassifiziert Expecto das Warum, sodass Sie auf einen Blick sehen, wessen Problem es ist und was zu tun ist:

Klasse	Bedeutung	Typische Ursache	Wer behebt es
Format	Die gelieferte Datei verletzt das vereinbarte Dateiformat (das Schema der Source) — Struktur oder Wertsyntax.	Fehlende/überzählige Spalten, falsches Trennzeichen, ein Datum wie `01.12.2025` statt `YYYY-MM-DD`, ein nicht-numerischer Betrag, ein Wert außerhalb der erlaubten Menge.	Der Data Provider — Datei korrigieren und erneut liefern. Bis dahin laufen die inhaltlichen Prüfungen nicht.
Inhaltlich	Das Format stimmt, aber die Daten verletzen eine Validierungs- oder Geschäftsregel.	Soll/Haben geht nicht auf, ein Konto ohne Mapping, eine Mietertrags-Anomalie.	Wird als Inhalt der Lieferung geprüft — die Zahlen/Mappings selbst brauchen Aufmerksamkeit.
System	Expecto konnte einen Schritt nicht ausführen — ein Konfigurations- oder Plattformfehler.	Ein fehlender Referenzkatalog, ein kaputter Mapping-Ausdruck, eine Regel, deren Ausführung fehlschlägt.	Die Organisation bzw. Expecto — der Provider kann nichts tun; dieselbe Datei erneut zu liefern hilft nicht.
Nicht anwendbar	Eine Regel konnte nicht laufen, weil eine optionale Source nicht geliefert wurde.	Eine USt-Regel, wenn die optionale VAT-Datei fehlt.	Niemand — das ist erwartet, kein Fehler. Siehe Optionale Sources.

Jede Session trägt eine aggregierte dominante Fehlerklasse (Priorität: System → Format → Inhalt → nicht anwendbar), dargestellt als Badge im Session-Kopf sowohl in der Admin-Ansicht als auch im Provider-Portal. Der Pipeline-Stepper markiert jede Stufe mit ihrem Ergebnis; Formatfehler blockieren die inhaltlichen Stufen, und ein Systemfehler stoppt die Pipeline (fail-fast), statt spätere Stufen auf Daten laufen zu lassen, die gar nicht erzeugt werden konnten.

Eine Session mit technischem Fehler: das Badge neben dem Titel, der Stepper mit fehlgeschlagener Stufe Verified und die auslösende Regel darunter

Transform-Fehler in Klartext¶

Ein Transform schlägt am häufigsten fehl, wenn ein Wert nicht in seinen Zieltyp passt — z. B. eine nicht-numerische Zeichenkette in einer Betragsspalte. Statt eines abgeschnittenen Datenbankfehlers nennt die Transform-Stufe die exakte Spalte, den Wert, den Zieltyp und die Quellzeile(n) (zum Beispiel Column "amount": value "abc" is not a valid number) und hebt die betreffende Zelle hervor. Das rohe technische Detail bleibt hinter einer Aufklappung verfügbar, für alle, die es brauchen.

Dasselbe gilt für Fehler bei Validierung und Geschäftsregeln: Eine Regel, die nicht ausgeführt werden kann — unbekannte Spalte oder Tabelle, fehlgeschlagene Konvertierung, zu wenig Speicher — zeigt eine verständliche Meldung (zum Beispiel The rule references an unknown table "vat_options") mit dem rohen Engine-Fehler einen Klick entfernt, statt die Datenbank-Ausnahme durchzureichen.

Ein inhaltlicher Fehler: das Content-Badge, die markierte Stufe und die hervorgehobene Zelle im Datengitter neben ihrer Verletzung

Verfolgung je Datei und je Transformer¶

Innerhalb einer Session haben jede Source-Datei und jeder Transformer einen eigenen Status und ein eigenes Parquet-Ergebnis, sodass Sie Parse-Ergebnisse je Datei und Transform-/Validate-Ergebnisse je Transformer inspizieren können.

Optionale Sources¶

Eine DataContract-Source kann optional sein. Wird eine optionale Source nicht geliefert, bricht die Pipeline nicht mit einem Fehler ab:

Transform — ein Transformer, dessen sämtliche Eingaberollen eine nicht gelieferte optionale Source sind, wird als SKIPPED erfasst (nicht ERROR). Die Session zählt einen übersprungenen Transformer als erledigt, sodass er den Fortschritt nicht blockiert.
Validate — der übersprungene Transformer geht als checked mit dem Grund missing_optional_source durch, statt als Fehler „keine transformierten Daten".
Export — das Paket lässt die fehlende optionale Source aus und vermerkt sie unter omissions in datapackage.json (gespiegelt im export_report der Session); jeder Eintrag nennt die role und den Grund optional_not_delivered.

Eine fehlende erforderliche Source bleibt auf jeder Stufe ein harter Fehler. Geschäftsregeln, die von einer nicht gelieferten Source abhängen, werden als nicht anwendbar statt fehlgeschlagen gemeldet — siehe Geschäftsregeln.

Pipeline-Zeitmessung¶

Workspaces können erfassen, wie lange jeder Pipeline-Lauf dauert. Ein Owner oder Admin aktiviert dies unter Einstellungen → Pipeline → Stufenzeiten messen; standardmäßig ist es deaktiviert, und solange es aus ist, wird nichts gemessen oder gespeichert.

Wenn aktiviert, erfasst jeder Lauf für jede automatische Stufe (Parse, Transform, Check, Export) deren Dauer sowie die seit Pipeline-Start verstrichene Zeit bis zum Abschluss der Stufe. Unter jedem Stufen-Badge im Status-Stepper steht dessen Dauer, daneben die kumulierte Zeit ab Start für die durchgehende Kette Parse → Check. Der ausgeklappte Bereich Vollständige Details ergänzt eine Lauf-Zusammenfassung: wann der Lauf begann, wann die automatischen Stufen endeten und die gesamte Maschinenzeit.

Manuelle Stufen (Uploaded, Confirmed, Approved) sind menschliche Aktionen und werden daher als Gates ohne Maschinendauer angezeigt. Solange die Messung aus ist, zeigt der Stepper keine Zeit-Beschriftungen — genau wie bisher.

Audit-Trail¶

Session-Aktivität wird als append-only Kommentare festgehalten — Typen COMMENT, INTERNAL_NOTE und STATUS_CHANGE — und ergibt eine dauerhafte Historie, wer was wann getan hat.

Wer Sessions erstellen darf¶

Je nach Session-Erstellungsmodus des Projekts können Sessions von Ihrer Organisation, vom Data Provider oder von beiden erstellt werden.