Error handling verbessert und OCI Verbindungsaufbau Problem behoben

workflow_dateieingang.md

@@ -43,10 +43,11 @@ 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. Marker eingang/<zip-name>/_READY_FOR_DB_PROCESSING_        │
-│       hochladen                                                 │
-│  3e. ZIP auf SFTP umbenennen (.processed oder .error)           │
-│       → erst NACH erfolgreichem Marker-Upload                   │
+│  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                              │
@@ -97,30 +98,85 @@ Daran können die Sachbearbeiter erkennen, dass der Ordner nicht mehr automatisc
 
 ## Fehlerfall-Verhalten
 
-**Service: Upload einer Datei schlägt fehl**
-- Verarbeitung dieser ZIP stoppt sofort
-- Kein Marker wird geschrieben, ZIP auf SFTP wird zu `.error` umbenannt
-- ORDS wird nicht aufgerufen
-- Bereits hochgeladene Dateien werden beim nächsten Trigger überschrieben (OCI PUT idempotent)
+**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: ORDS-Aufruf schlägt fehl**
-- Marker liegt in `eingang/<zip-name>/`, Dateien sind vollständig hochgeladen
-- Beim nächsten Stundenlauf findet APEX Automation den Marker und verarbeitet
+**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**
-- Rollback — Datei bleibt in `eingang/<zip-name>/`
-- ERROR in `lg_app_log` mit `log_object_ref = eingang/<zip-name>/datei.csv`
-- Nächste Dateien im Batch werden weiterverarbeitet
+- OCI `eingang/`: Datei bleibt in `eingang/<zip-name>/` (Rollback)
+- OCI `zielordner/`: keine Änderung
+- DB: Rollback, ERROR in `lg_app_log` mit `log_object_ref = eingang/<zip-name>/datei.csv`, nächste Dateien im Batch werden weiterverarbeitet
 
 **DB: Batch-Abschluss (nach dem Datei-Loop)**
-- DB-Marker (`_READY_FOR_DB_PROCESSING_`) wird **immer gelöscht** — kein automatischer Retry
-- Liegen noch Dateien im Unterordner: SB-Marker (`_BITTE_PRÜFEN_`) wird angelegt → Sachbearbeiter müssen manuell eingreifen
-- Alle Dateien erfolgreich: INFO in `lg_app_log`, Unterordner ist leer
+- 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**
-- Rollback des Imports → sauberer Ausgangszustand
-- Datei bleibt in `eingang/<zip-name>/`
-- DB-Marker wird trotzdem am Ende des Loops gelöscht; falls noch Dateien übrig → SB-Marker
+- OCI `eingang/`: Datei bleibt in `eingang/<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:
+
+1. Quarkus lädt Dateien + Marker hoch, schlägt dann beim SFTP-Rename 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
+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.
 
 ---