Dokumentation upgedatet für letzte code changes

2026-05-04 10:18:36 +02:00
parent ca7b26509a
commit 6418e14be3
3 changed files with 33 additions and 28 deletions
--- 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/<zip-name>/ + 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/<zip-name>/)
+         Oracle DB (pck_auto_import verarbeitet alle eingang/-Unterordner)
 ```

 ## Pipeline-Steps
--- 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
 }
--- 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/<zip-name>/ 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/<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                              │
+│       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/<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
+- 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/<zip-name>/` (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.

 ---