gala-ki-spielwiese/workflow_dateieingang.md

# 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 löschen                                       │
│       → bei ungültiger ZIP: .error (manuelle Prüfung nötig)     │
│       → bei Infrastrukturfehlern: kein Löschen, Retry           │
│  3e. Marker eingang/<zip-name>/_READY_FOR_DB_PROCESSING_        │
│       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)              │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│  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-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 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 erfolgreichem Delete auf SFTP & Marker in OCI) werden die Dateien abgearbeitet


**Service: OCI-Marker-Upload fehlgeschlagen**
- 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

- 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 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 gelöschte ZIP nicht erneut verarbeitet

**DB: Verarbeitung einer einzelnen Datei schlägt fehl**
- 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)**
- 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 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-Delete gesetzt

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 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 3g, schneller Pfad).
Ohne die Invariante könnte folgender Race entstehen:

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 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-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 gelöschte ZIP 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:

1. Direkt durch `p_run_ba_korrespondenz_dateieingang_automation` (Schritt 1)
2. 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.