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: `agent-backend/docs/Architecture.md`  
Details zur DB-Verarbeitung: `database/docs/plan_pck_net_storage.md`

---

## Ablauf

```
┌─────────────────────────────────────────────────────────────────┐
│  APEX Automation (stündlich)                                    │
│                                                                 │
│  1. Unterordner in eingang/ mit Marker vorhanden?               │
│     → ja: Dateien verarbeiten (gleiche Logik wie Schritt 4-6)   │
│                                                                 │
│  2. Dateieingang Service aufrufen (fire & forget)               │
│     HTTP POST /api/process-incoming  (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. Marker eingang/<zip-name>/_READY_FOR_DB_PROCESSING_        │
│       hochladen                                                 │
│  3e. ZIP auf SFTP umbenennen (.processed oder .error)           │
│       → erst NACH erfolgreichem Marker-Upload                   │
│  3f. ORDS-Endpunkt aufrufen (pck_auto_import.p_process_incoming)│
│  3g. Lokale Arbeitsdateien löschen                              │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│  Oracle DB (via ORDS-Endpunkt oder APEX Automation)             │
│                                                                 │
│  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
erfolgreich verarbeitet wurden. Fehlgeschlagene Dateien werden beim nächsten Lauf erneut versucht.

---

## 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: 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

**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`
- Marker bleibt erhalten → nächste Dateien im Batch werden weiterverarbeitet
- Beim nächsten Lauf wird die fehlgeschlagene Datei erneut versucht

**DB: p_move_object schlägt nach erfolgreichem Import fehl**
- Rollback des Imports → sauberer Ausgangszustand
- Datei bleibt in `eingang/<zip-name>/`, Marker bleibt erhalten
- Nächster Lauf versucht es erneut

---

## 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.