Dokumentation aktualisiert auf quarkus und besser strukturiert

2026-04-08 14:18:07 +02:00
parent 39390e94e5
commit d9adccf63c
15 changed files with 2216 additions and 21 deletions
--- a/workflow_dateieingang.md
+++ b/workflow_dateieingang.md
@@ -1,6 +1,6 @@
-# Workflow: Automatischer Dateieingang via n8n → OCI Object Storage → DB
+# Workflow: Automatischer Dateieingang — SFTP → OCI Object Storage → DB

-**Stand:** 2026-04-07
+**Stand:** 2026-04-08

 ---

@@ -9,10 +9,13 @@
 | System | Rolle |
 |---|---|
 | **SFTP-Server** | Quelle — externer Lieferant legt ZIP-Dateien ab |
-| **n8n** | Middleware — holt ZIP, entpackt, lädt Dateien + Marker in OCI hoch |
+| **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
@@ -24,23 +27,25 @@
 │  1. Unterordner in eingang/ mit Marker vorhanden?               │
 │     → ja: Dateien verarbeiten (gleiche Logik wie Schritt 4-6)   │
 │                                                                 │
-│  2. n8n Webhook auslösen (fire & forget)                        │
+│  2. Dateieingang Service aufrufen (fire & forget)               │
+│     HTTP POST /api/process-incoming  (Header: X-Api-Key)        │
 └────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
 ┌─────────────────────────────────────────────────────────────────┐
-│  n8n Workflow                                                   │
+│  Dateieingang Service (Quarkus, läuft im Hintergrund)           │
 │                                                                 │
-│  3a. ZIP-Datei vom SFTP-Server herunterladen                    │
-│  3b. ZIP entpacken                                              │
+│  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)              │
-│       → "Continue on Error" AUS: ein Fehler stoppt alles        │
+│       → Fehler stoppt Verarbeitung dieser ZIP                   │
 │  3d. Marker eingang/<zip-name>/_READY_FOR_DB_PROCESSING_        │
 │       hochladen                                                 │
-│  3e. ZIP auf SFTP umbenennen / verschieben                      │
+│  3e. ZIP auf SFTP umbenennen (.processed oder .error)           │
 │       → erst NACH erfolgreichem Marker-Upload                   │
-│  3f. ORDS-Endpunkt aufrufen                                     │
+│  3f. ORDS-Endpunkt aufrufen (pck_auto_import.p_process_incoming)│
+│  3g. Lokale Arbeitsdateien löschen                              │
 └────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
@@ -80,21 +85,19 @@ bucket/
 ```

 Der Marker bleibt solange erhalten bis **alle** Dateien des Unterordners
-erfolgreich verarbeitet wurden. So werden fehlgeschlagene Dateien beim
-nächsten Lauf erneut aufgegriffen.
+erfolgreich verarbeitet wurden. Fehlgeschlagene Dateien werden beim nächsten Lauf erneut versucht.

 ---

 ## 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
+**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
- Beim nächsten Stundenlauf lädt n8n die ZIP erneut herunter
- Bereits hochgeladene Dateien werden überschrieben (OCI PUT idempotent)
+- Bereits hochgeladene Dateien werden beim nächsten Trigger überschrieben (OCI PUT idempotent)

-**n8n: ORDS-Aufruf schlägt fehl**
+**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

@@ -115,9 +118,10 @@ nächsten Lauf erneut aufgegriffen.

 Der Zustand steckt im Dateisystem:
 - Unterordner mit Marker = Batch bereit oder teilweise verarbeitet
- Unterordner ohne Marker = unvollständiger n8n-Upload, wird ignoriert
+- 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 —
@@ -127,5 +131,5 @@ 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.
+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.