Initialen Implementierungsplan hinzugefügt

2026-04-08 08:37:58 +02:00
commit 39390e94e5
3 changed files with 684 additions and 0 deletions
--- a/workflow_dateieingang.md
+++ b/workflow_dateieingang.md
@@ -0,0 +1,131 @@
+# Workflow: Automatischer Dateieingang via n8n → OCI Object Storage → DB
+
+**Stand:** 2026-04-07
+
+---
+
+## Beteiligte Systeme
+
+| System | Rolle |
+|---|---|
+| **SFTP-Server** | Quelle — externer Lieferant legt ZIP-Dateien ab |
+| **n8n** | Middleware — 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 |
+
+---
+
+## Ablauf
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  APEX Automation (stündlich)                                    │
+│                                                                 │
+│  1. Unterordner in eingang/ mit Marker vorhanden?               │
+│     → ja: Dateien verarbeiten (gleiche Logik wie Schritt 4-6)   │
+│                                                                 │
+│  2. n8n Webhook auslösen (fire & forget)                        │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  n8n Workflow                                                   │
+│                                                                 │
+│  3a. ZIP-Datei vom SFTP-Server herunterladen                    │
+│  3b. ZIP entpacken                                              │
+│  3c. Alle Dateien in OCI eingang/<zip-name>/ hochladen          │
+│       (Unterordner aus der ZIP werden beibehalten)              │
+│       → "Continue on Error" AUS: ein Fehler stoppt alles        │
+│  3d. Marker eingang/<zip-name>/_READY_FOR_DB_PROCESSING_        │
+│       hochladen                                                 │
+│  3e. ZIP auf SFTP umbenennen / verschieben                      │
+│       → erst NACH erfolgreichem Marker-Upload                   │
+│  3f. ORDS-Endpunkt aufrufen                                     │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  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. So werden fehlgeschlagene Dateien beim
+nächsten Lauf erneut aufgegriffen.
+
+---
+
+## Fehlerfall-Verhalten
+
+**n8n: Upload einer Datei schlägt fehl**
+- Workflow stoppt sofort ("Continue on Error" ist aus)
+- Kein Marker wird geschrieben, ZIP bleibt unverändert auf SFTP
+- ORDS wird nicht aufgerufen
+- Beim nächsten Stundenlauf lädt n8n die ZIP erneut herunter
+- Bereits hochgeladene Dateien werden überschrieben (OCI PUT idempotent)
+
+**n8n: 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 n8n-Upload, wird ignoriert
+- Datei im Zielordner = erfolgreich verarbeitet
+- Datei noch in `eingang/<zip-name>/` = noch ausstehend oder fehlgeschlagen
+
+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**. n8n-Workflow wird dabei neu angestoßen —
+läuft also ebenfalls stündlich, zeitlich versetzt nach dem Automation-Start.