12 KiB
Workflow: Automatischer Dateieingang — SFTP → OCI Object Storage → DB
Stand: 2026-04-08
Beteiligte Systeme
| System | Rolle |
|---|---|
| SFTP-Server | Quelle — externer Lieferant legt ZIP-Dateien ab |
| Dateieingang Service | Middleware (Quarkus) — holt ZIP, entpackt, lädt Dateien + Marker in OCI hoch |
| OCI Object Storage | Zwischenspeicher — Eingangsordner, Zielordner nach Verarbeitung |
| Oracle DB / APEX | Verarbeitung — liest Dateien aus OCI, importiert Daten |
Details zum Dateieingang Service: quarkus-automaton/docs/Architecture.md
Details zur DB-Verarbeitung: database/docs/plan_pck_net_storage.md
Ablauf
┌─────────────────────────────────────────────────────────────────┐
│ APEX Automation (stündlich) │
│ → pck_auto_import.p_run_ba_korrespondenz_dateieingang_automation │
│ │
│ 1. p_process_incoming_ba_data aufrufen │
│ → OCI-Batches mit Marker verarbeiten (Fallback: ORDS-Aufruf │
│ im letzten Quarkus-Lauf fehlgeschlagen) │
│ │
│ 2. Dateieingang Service aufrufen (fire & forget) │
│ HTTP POST /api/process-incoming-ba-korrespondenz |
| (Header: X-Api-Key) │
└────────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Dateieingang Service (Quarkus, läuft im Hintergrund) │
│ │
│ 3a. Neue *.zip-Dateien vom SFTP-Server auflisten │
│ 3b. ZIP herunterladen und entpacken │
│ 3c. Alle Dateien in OCI eingang/<zip-name>/ hochladen │
│ (Unterordner aus der ZIP werden beibehalten) │
│ → Fehler stoppt Verarbeitung dieser ZIP │
│ 3d. ZIP auf SFTP umbenennen zu .processed │
│ → bei ungültiger ZIP: .error (manuelle Prüfung nötig) │
│ → bei Infrastrukturfehlern: keine Umbenennung, Retry │
│ 3e. Marker eingang/<zip-name>/_READY_FOR_DB_PROCESSING_ │
│ hochladen — ERST NACH dem SFTP-Rename (siehe unten) │
│ 3f. ORDS-Endpunkt aufrufen |
| (pck_auto_import.p_process_incoming_ba_data) │
│ 3g. Lokale Arbeitsdateien löschen │
└────────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Oracle DB (via ORDS-Endpunkt) │
│ │
│ 4. Unterordner in eingang/ auflisten │
│ 5. Für jeden Unterordner mit Marker: │
│ Für jede Datei (außer Marker) einzeln: │
│ a. Daten importieren (noch kein Commit) │
│ → log_object_ref = eingang/<zip-name>/datei.csv │
│ b. Datei in Zielordner verschieben │
│ c. Commit │
│ d. Fehler → Rollback, ERROR in lg_app_log, nächste Datei │
│ 6. Keine Dateien mehr im Unterordner (außer Marker)? │
│ → Marker löschen (Batch abgeschlossen) │
└─────────────────────────────────────────────────────────────────┘
OCI Ordnerstruktur
bucket/
eingang/
export_2026-04-07/ ← Unterordner = ZIP-Name
datei1.csv
datei2.csv
unterordner/
datei3.csv
_READY_FOR_DB_PROCESSING_ ← Marker: Batch vollständig
<zielordner>/
export_2026-04-07/ ← gleiche Struktur nach Verarbeitung
datei1.csv
...
Der Marker bleibt solange erhalten bis alle Dateien des Unterordners verarbeitet wurden. Fehlgeschlagene Dateien bleiben im Ordner. Wenn ein Import-Lauf alle Dateien im Ordner einmal versucht hat zu importieren, und min. eine Datei übrig geblieben ist, für die der automatische Import also nicht funktioniert hat, dann wird für jede dieser Dateien eine Wiedervorlage für die Sachbearbeiter erstellt und eine Marker Datei für die Sachbearbeiter wird im Ordner abgelegt. Daran können die Sachbearbeiter erkennen, dass der Ordner nicht mehr automatisch importiert wird, sondern sie manuell tätig werden müssen.
Fehlerfall-Verhalten
Service: ZIP ist beschädigt oder ungültig
- SFTP: ZIP →
.error(manuelle Prüfung nötig) - OCI: kein Upload, kein Marker
- DB: wird nicht aufgerufen
Service: SFTP-Download fehlgeschlagen
- SFTP: ZIP bleibt unverändert, wird beim nächsten Stundenlauf erneut versucht
- OCI: kein Upload, kein Marker
- DB: wird nicht aufgerufen
Service: OCI-Upload (Dateien) fehlgeschlagen
- SFTP: ZIP bleibt unverändert, wird beim nächsten Stundenlauf erneut versucht
- OCI: teilweise hochgeladene Dateien bleiben liegen (kein Marker → DB ignoriert den Ordner); beim Retry werden sie überschrieben (OCI PUT ist idempotent)
- DB: wird nicht aufgerufen
Service: SFTP-Rename zu .processed fehlgeschlagen
- SFTP: ZIP bleibt unverändert, wird beim nächsten Stundenlauf erneut versucht
- OCI: Dateien hochgeladen, noch kein Marker (Marker kommt erst nach dem Rename)
- DB: wird nicht aufgerufen
- beim nächsten Stundenlauf werden die Dateien aber nicht importiert, da APEX Automation ohne Marker nichts findet
- d.h. erst nachdem die ZIP Datei erneut abgearbeitet und komplett in OCI hochgeladen wurde (diesmal mit .processed-Umbennung auf SFTP & Marker in OCI) werden die Dateien abgearbeitet
Service: OCI-Marker-Upload fehlgeschlagen
-
SFTP: ZIP ist bereits
.processed— Quarkus greift sie nie wieder auf -
OCI: Dateien vollständig hochgeladen, Marker fehlt → DB-Verarbeitung wird nicht ausgelöst
- DB wird die Dateien wegen dem fehlendem Marker nie automatisiert abarbeiten, aber man sieht das recht einfach über den OCI Dateibrowser in Apex
-
DB: wird nicht aufgerufen
-
Manueller Fix: Marker-Datei
eingang/<zip-name>/_READY_FOR_DB_PROCESSING_in OCI von Hand anlegen (leere Datei) — APEX Automation verarbeitet den Batch dann beim nächsten Stundenlauf
Service: ORDS-Aufruf fehlgeschlagen
- SFTP: ZIP ist bereits
.processed— Quarkus greift sie nie wieder auf - OCI: Dateien + Marker vollständig hochgeladen
- DB: APEX Automation findet den Marker beim nächsten Stundenlauf und verarbeitet ihn (Schritt 1) — kein Doppelimport, da Quarkus die
.processed-Datei nicht erneut verarbeitet
DB: Verarbeitung einer einzelnen Datei schlägt fehl
- OCI
eingang/: Datei bleibt ineingang/<zip-name>/(Rollback) - OCI
zielordner/: keine Änderung - DB: Rollback, ERROR in
lg_app_logmitlog_object_ref = eingang/<zip-name>/datei.csv, nächste Dateien im Batch werden weiterverarbeitet
DB: Batch-Abschluss (nach dem Datei-Loop)
- Alle Dateien erfolgreich:
eingang/<zip-name>/ist leer, Marker wird gelöscht - Noch Dateien übrig: Marker wird gelöscht, SB-Marker (
_BITTE_PRÜFEN_) wird angelegt → Sachbearbeiter müssen manuell eingreifen
DB: p_move_object schlägt nach erfolgreichem Import fehl
- OCI
eingang/: Datei bleibt ineingang/<zip-name>/(Rollback des gesamten Imports) - OCI
zielordner/: keine Änderung - DB: Marker wird am Ende des Loops trotzdem gelöscht; falls noch Dateien übrig → SB-Marker
Design-Entscheidung: Marker wird nach dem SFTP-Rename gesetzt
Der OCI-Marker _READY_FOR_DB_PROCESSING_ wird bewusst nach dem SFTP-Rename zu .processed
hochgeladen — nicht davor. Das erzeugt eine harte Invariante:
Marker in OCI vorhanden ↔ ZIP auf SFTP bereits
.processed
Warum ist das wichtig?
APEX Automation ruft p_process_incoming_ba_data in jedem Stundenlauf einmal direkt auf
(Schritt 1, Fallback), und Quarkus ruft dieselbe Funktion via ORDS auf (Schritt 3f, schneller Pfad).
Ohne die Invariante könnte folgender Race entstehen:
- Quarkus lädt Dateien + Marker hoch, schlägt dann beim SFTP-Rename fehl
- APEX Schritt 1 findet den Marker → importiert Daten
- Quarkus wiederholt den Lauf, ruft ORDS auf → zweiter Import derselben Daten
Mit der Invariante ist dieser Fall ausgeschlossen: APEX Schritt 1 findet nur dann einen Marker,
wenn die ZIP auf dem SFTP bereits .processed ist. Ist sie das, greift Quarkus sie im Retry
nicht mehr an — listZipFiles() gibt nur .zip-Dateien zurück.
Einzig verbleibender manueller Fehlerfall
Schlägt der Marker-Upload fehl (nach erfolgreichem SFTP-Rename), ist der Zustand eindeutig
erkennbar: .processed auf SFTP, Dateien in OCI ohne Marker. Manueller Fix: Marker-Datei
in OCI von Hand anlegen. Dieser Fall erfordert keine DB-seitige Idempotenz, da Quarkus
die Datei nicht erneut verarbeitet und ORDS nicht aufruft.
Warum ruft die APEX Automation p_process_incoming_ba_data auf, obwohl Quarkus das auch tut?
p_process_incoming_ba_data wird in jedem Stundenlauf zweimal aufgerufen:
- Direkt durch
p_run_ba_korrespondenz_dateieingang_automation(Schritt 1) - Indirekt — von Quarkus via ORDS, nachdem der Upload abgeschlossen ist (Schritt 3f)
Der direkte Aufruf in Schritt 1 ist ein Fallback: Wenn der ORDS-Aufruf in einem vorherigen Quarkus-Lauf fehlgeschlagen ist, liegt der Marker bereits in OCI, aber p_process_incoming_ba_data wurde nie aufgerufen. Ohne Schritt 1 würde dieser Batch erst beim nächsten Quarkus-Lauf verarbeitet — und nur dann, wenn Quarkus beim nächsten Mal auch wieder erfolgreich bis zum ORDS-Aufruf kommt. Mit Schritt 1 ist die DB-Verarbeitung unabhängig davon, ob Quarkus den ORDS-Aufruf erfolgreich abgeschlossen hat.
Das heißt: Quarkus ist der schnelle Pfad (Upload + sofortiger DB-Trigger), die APEX Automation ist die Absicherung (findet Marker, die noch nicht verarbeitet wurden).
Warum kein Fehlerordner, keine Status-Tabelle?
Der Zustand steckt im Dateisystem:
- Unterordner mit Marker = Batch bereit oder teilweise verarbeitet
- Unterordner ohne Marker = unvollständiger Upload, wird ignoriert
- Datei im Zielordner = erfolgreich verarbeitet
- Datei noch in
eingang/<zip-name>/= noch ausstehend oder fehlgeschlagen - ZIP auf SFTP mit
.error= persistenter Fehler, manuelle Prüfung nötig
Fehlerdetails stehen in lg_app_log. Über log_object_ref ist jede Datei
eindeutig einer ZIP zugeordnet. Kein Verhalten wird aus dem Log abgeleitet —
es dient ausschließlich dem Audit-Trail.
Zeitplan
APEX Automation läuft 1x pro Stunde. Der Dateieingang Service wird dabei per HTTP POST aufgerufen und läuft zeitlich versetzt nach dem Automation-Start.