From 6418e14be3b6ab43267179d4c25fa96a5e641f26 Mon Sep 17 00:00:00 2001 From: "Simon C. Kessler" Date: Mon, 4 May 2026 10:18:36 +0200 Subject: [PATCH] =?UTF-8?q?Dokumentation=20upgedatet=20f=C3=BCr=20letzte?= =?UTF-8?q?=20code=20changes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- quarkus-automaton/docs/Architecture.md | 14 +++--- .../dateieingang/model/ProcessingStatus.java | 1 + workflow_dateieingang.md | 46 ++++++++++--------- 3 files changed, 33 insertions(+), 28 deletions(-) diff --git a/quarkus-automaton/docs/Architecture.md b/quarkus-automaton/docs/Architecture.md index e04f68b..7cd1b41 100644 --- a/quarkus-automaton/docs/Architecture.md +++ b/quarkus-automaton/docs/Architecture.md @@ -30,16 +30,18 @@ FileProcessingPipeline [ManagedExecutor — Hintergrund-Thread] ├─→ OciUploadService.upload() [OCI SDK] │ └─ Dateien in eingang// + Marker │ - ├─→ SftpService.renameRemote() [SSHJ] - │ └─ .processed (Erfolg) oder .error (Fehler) - │ - ├─→ OrdsNotificationService.notify() [MicroProfile REST Client] - │ └─ POST pck_auto_import.p_process_incoming_ba_data + ├─→ SftpService.deleteRemote() [SSHJ] + │ └─ ZIP gelöscht (Erfolg) oder .error (Fehler) │ └─→ Cleanup: lokale Dateien löschen [immer, im finally] + │ + │ nach allen ZIPs (einmalig): + │ + └─→ OrdsNotificationService.notify() [MicroProfile REST Client] + └─ POST pck_auto_import.p_process_incoming_ba_data │ ▼ - Oracle DB (pck_auto_import verarbeitet eingang//) + Oracle DB (pck_auto_import verarbeitet alle eingang/-Unterordner) ``` ## Pipeline-Steps diff --git a/quarkus-automaton/src/main/java/de/galabau/dateieingang/model/ProcessingStatus.java b/quarkus-automaton/src/main/java/de/galabau/dateieingang/model/ProcessingStatus.java index 60a1950..9dfcea6 100644 --- a/quarkus-automaton/src/main/java/de/galabau/dateieingang/model/ProcessingStatus.java +++ b/quarkus-automaton/src/main/java/de/galabau/dateieingang/model/ProcessingStatus.java @@ -5,6 +5,7 @@ public enum ProcessingStatus { PENDING, PARTIALLY_UPLOADED, MARKER_UPLOADED, + // TODO: ORDS_NOTIFIED wird seit dem Refactoring (ORDS-Aufruf einmalig am Ende der Pipeline, nicht mehr pro ZIP) nicht mehr gesetzt — entfernen ORDS_NOTIFIED, FAILED } diff --git a/workflow_dateieingang.md b/workflow_dateieingang.md index 67bc67c..856c3f6 100644 --- a/workflow_dateieingang.md +++ b/workflow_dateieingang.md @@ -43,14 +43,16 @@ Details zur DB-Verarbeitung: `database/docs/plan_pck_net_storage.md` │ 3c. Alle Dateien in OCI eingang// hochladen │ │ (Unterordner aus der ZIP werden beibehalten) │ │ → Fehler stoppt Verarbeitung dieser ZIP │ -│ 3d. ZIP auf SFTP umbenennen zu .processed │ +│ 3d. ZIP auf SFTP löschen │ │ → bei ungültiger ZIP: .error (manuelle Prüfung nötig) │ -│ → bei Infrastrukturfehlern: keine Umbenennung, Retry │ +│ → bei Infrastrukturfehlern: kein Löschen, Retry │ │ 3e. Marker eingang//_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 │ +│ hochladen — ERST NACH dem SFTP-Delete (siehe unten) │ +│ 3f. Lokale Arbeitsdateien löschen │ +│ │ +│ Nach allen ZIPs (einmalig): │ +│ 3g. ORDS-Endpunkt aufrufen │ +│ (pck_auto_import.p_process_incoming_ba_data) │ └────────────────────────────┬────────────────────────────────────┘ │ ▼ @@ -113,16 +115,16 @@ Daran können die Sachbearbeiter erkennen, dass der Ordner nicht mehr automatisc - 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** +**Service: SFTP-Delete 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 +- OCI: Dateien hochgeladen, noch kein Marker (Marker kommt erst nach dem Delete) +- 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 + - d.h. erst nachdem die ZIP Datei erneut abgearbeitet und komplett in OCI hochgeladen wurde (diesmal mit erfolgreichem Delete 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 +- SFTP: ZIP ist bereits gelöscht — 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 @@ -130,9 +132,9 @@ Daran können die Sachbearbeiter erkennen, dass der Ordner nicht mehr automatisc - **Manueller Fix:** Marker-Datei `eingang//_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 +- SFTP: ZIP ist bereits gelöscht — 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: APEX Automation findet den Marker beim nächsten Stundenlauf und verarbeitet ihn (Schritt 1) — kein Doppelimport, da Quarkus die gelöschte ZIP nicht erneut verarbeitet **DB: Verarbeitung einer einzelnen Datei schlägt fehl** - OCI `eingang/`: Datei bleibt in `eingang//` (Rollback) @@ -150,33 +152,33 @@ Daran können die Sachbearbeiter erkennen, dass der Ordner nicht mehr automatisc --- -## Design-Entscheidung: Marker wird nach dem SFTP-Rename gesetzt +## Design-Entscheidung: Marker wird nach dem SFTP-Delete gesetzt -Der OCI-Marker `_READY_FOR_DB_PROCESSING_` wird bewusst **nach** dem SFTP-Rename zu `.processed` +Der OCI-Marker `_READY_FOR_DB_PROCESSING_` wird bewusst **nach** dem SFTP-Delete hochgeladen — nicht davor. Das erzeugt eine harte Invariante: -> **Marker in OCI vorhanden ↔ ZIP auf SFTP bereits `.processed`** +> **Marker in OCI vorhanden ↔ ZIP auf SFTP bereits gelöscht** ### 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). +(Schritt 1, Fallback), und Quarkus ruft dieselbe Funktion via ORDS auf (Schritt 3g, schneller Pfad). Ohne die Invariante könnte folgender Race entstehen: -1. Quarkus lädt Dateien + Marker hoch, schlägt dann beim SFTP-Rename fehl +1. Quarkus lädt Dateien + Marker hoch, schlägt dann beim SFTP-Delete fehl 2. APEX Schritt 1 findet den Marker → importiert Daten 3. 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 +wenn die ZIP auf dem SFTP bereits gelöscht 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 +Schlägt der Marker-Upload fehl (nach erfolgreichem SFTP-Delete), ist der Zustand eindeutig +erkennbar: ZIP auf SFTP gelöscht, 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. +die gelöschte ZIP nicht erneut verarbeitet und ORDS nicht aufruft. ---