cbazza/AFC-Demo

Fork 0

Files

T

cbazza a36d2b4cc4 fix: added new command - complete rebuild

2025-11-20 11:54:08 +01:00

10 KiB

Raw Blame History

Backend Sync & Transform Commands

Dokumentation für die manuellen Artisan Commands zum Synchronisieren und Transformieren von Backend-Daten.

Übersicht

Das System verfügt über 3 Haupt-Commands zur Datensynchronisation:

backend:sync-data-pool - Synchronisiert Daten vom Backend-Schema in den Data Pool
backend:transform-data-pool - Transformiert Data Pool in Companies + Transactions
backend:rebuild - Kompletter Rebuild (Sync + Transform in einem Schritt)

1. Backend Sync Command

Synchronisiert Daten von backend.transactions + backend.transaction_outputs nach public.backend_data_pool.

Verwendung

Incremental Sync (Standard)

Nur neue oder geänderte Datensätze seit dem letzten Sync:

php artisan backend:sync-data-pool --incremental

Full Sync

Kompletter Rebuild - löscht alle Daten im Data Pool und baut sie neu auf:

php artisan backend:sync-data-pool --full

Statistiken anzeigen

Zeigt nur Statistiken an, ohne Sync durchzuführen:

php artisan backend:sync-data-pool --stats

Im Hintergrund über Queue

Führt den Sync asynchron über die Queue aus:

php artisan backend:sync-data-pool --full --queue

Batch-Größe anpassen

Definiert, wie viele Records pro Batch verarbeitet werden (Standard: 1000):

php artisan backend:sync-data-pool --full --batch-size=2000

Optionen

Option	Beschreibung	Default
`--full`	Kompletter Sync (truncate + rebuild)	false
`--incremental`	Nur neue/geänderte Records	false
`--batch-size`	Records pro Batch	1000
`--queue`	Im Hintergrund ausführen	false
`--stats`	Nur Statistiken anzeigen	false

Datenbankverbindungen

Source: DB::connection('pgsql') → backend.transactions, backend.transaction_outputs
Target: DB::table('backend_data_pool') → public.backend_data_pool

Was passiert beim Sync?

Full Sync:
- Truncate backend_data_pool
- Alle done Transactions vom Backend laden
- Mit transaction_outputs joinen
- In Batches in Data Pool schreiben
Incremental Sync:
- Letzten Sync-Zeitstempel ermitteln
- Nur Records mit last_modified_at > last_synced_at laden
- In Batches in Data Pool schreiben

2. Transform Command

Transformiert Daten aus backend_data_pool in die Production-Tables companies und transactions.

Verwendung

Standard Transformation

php artisan backend:transform-data-pool

Statistiken anzeigen

php artisan backend:transform-data-pool --stats

Im Hintergrund über Queue

php artisan backend:transform-data-pool --queue

Batch-Größe anpassen

php artisan backend:transform-data-pool --batch-size=200

Optionen

Option	Beschreibung	Default
`--batch-size`	Records pro Batch	100
`--queue`	Im Hintergrund ausführen	false
`--stats`	Nur Statistiken anzeigen	false

Datenbankverbindungen

Source: DB::table('backend_data_pool') → public.backend_data_pool
Target: Eloquent Models → public.companies, public.transactions

Was passiert bei der Transformation?

Alle eindeutigen transaction_id aus Data Pool laden
Für jede Transaction:
- Company erstellen/aktualisieren:
  - Name: corporate_entity
  - Country, Sector, HQ, Summary, Legal Name extrahieren
  - KYC Risk Level aus risk_score berechnen
- Transaction erstellen/aktualisieren:
  - Reference, Amount, Currency, Counterparty
  - Risk Score & Level mapping
  - Status basierend auf Risk Level
  - Alle output_keys als JSON-Felder speichern

Risk Score Mapping

Backend verwendet eine Skala von -100 bis 100:

Backend Score	Risk Level	Transaction Status
-100 bis 20	`critical`	True Positive
20 bis 80	`high`	False Positive
80 bis 100	`low`	Cleared

Für das Frontend wird der Score auf 0-255 normalisiert:

normalized = ((score + 100) / 200) * 255

3. Complete Rebuild Command

Führt Full Sync + Transformation in einem Schritt aus.

Verwendung

Standard Rebuild

php artisan backend:rebuild

Mit angepassten Batch-Größen

php artisan backend:rebuild --batch-size=2000 --transform-batch-size=150

Im Hintergrund über Queue

php artisan backend:rebuild --queue

Hinweis: Bei --queue wird nur der Sync-Job in die Queue geschickt. Die Transformation muss manuell gestartet werden, nachdem der Sync abgeschlossen ist.

Optionen

Option	Beschreibung	Default
`--batch-size`	Records pro Batch (Sync)	1000
`--transform-batch-size`	Records pro Batch (Transform)	100
`--queue`	Im Hintergrund ausführen	false

Ablauf

Step 1/2: Full Sync from Backend
- Truncate backend_data_pool
- Sync alle done Transactions
Step 2/2: Transform Data Pool
- Companies erstellen/aktualisieren
- Transactions erstellen/aktualisieren

Automatisierung mit Laravel Scheduler

Die Commands sind bereits im Laravel Scheduler konfiguriert (routes/console.php):

Aktuelle Schedule

// Incremental Sync: Alle 6 Stunden (0:00, 6:00, 12:00, 18:00)
Schedule::job(new SyncBackendDataPool(fullSync: false, batchSize: 1000))
    ->everySixHours()
    ->name('sync-backend-data-pool-incremental')
    ->withoutOverlapping(1800);

// Full Sync: Jeden Sonntag um 3:00 Uhr
Schedule::job(new SyncBackendDataPool(fullSync: true, batchSize: 1000))
    ->weeklyOn(0, '03:00')
    ->name('sync-backend-data-pool-full')
    ->withoutOverlapping(3600);

// Transformation: 30 Minuten nach jedem Sync (0:30, 6:30, 12:30, 18:30)
Schedule::job(new TransformDataPoolToProduction(batchSize: 100))
    ->cron('30 */6 * * *')
    ->name('transform-data-pool-to-production')
    ->withoutOverlapping(1800);

Scheduler aktivieren

Für lokale Entwicklung

php artisan schedule:work

Für Produktion (Crontab)

crontab -e

Folgende Zeile hinzufügen:

* * * * * cd /Users/sebastianfrohlich/Herd/frontend && php artisan schedule:run >> /dev/null 2>&1

Scheduled Tasks anzeigen

php artisan schedule:list

Scheduled Task testen

php artisan schedule:test sync-backend-data-pool-incremental
php artisan schedule:test sync-backend-data-pool-full
php artisan schedule:test transform-data-pool-to-production

Features

Alle Commands bieten

✅ Interaktive Bestätigung - Sicherheitsfrage vor kritischen Operationen ✅ Statistiken vorher/nachher - Direkter Vergleich der Datenänderungen ✅ Batch-Processing - Performante Verarbeitung großer Datenmengen ✅ Queue-Support - Ausführung im Hintergrund möglich ✅ Laravel Prompts - Moderne, benutzerfreundliche CLI-Oberfläche ✅ Error Handling - Robuste Fehlerbehandlung mit Logging ✅ Timeout Protection - 1 Stunde Timeout pro Job ✅ Retry Logic - 3 Versuche bei Fehlern ✅ Overlap Prevention - Verhindert gleichzeitige Ausführung

Datenfluss

┌──────────────────────┐
│  backend.transactions │
│  backend.transaction_│
│       outputs        │
└──────────┬───────────┘
           │
           │ SyncBackendDataPool
           │ (backend:sync-data-pool)
           ▼
┌──────────────────────┐
│ public.backend_data_ │
│        pool          │
└──────────┬───────────┘
           │
           │ TransformDataPoolToProduction
           │ (backend:transform-data-pool)
           ▼
┌──────────────────────┐
│  public.companies    │
│  public.transactions │
└──────────────────────┘

Troubleshooting

Command funktioniert nicht

# Commands neu registrieren
php artisan optimize:clear

# Artisan Cache leeren
php artisan cache:clear

Queue-Jobs laufen nicht

# Queue Worker starten
php artisan queue:work

# Queue Status prüfen
php artisan queue:monitor

Logs prüfen

# Application Logs
tail -f storage/logs/laravel.log

# Nur Sync-Logs
tail -f storage/logs/laravel.log | grep SyncBackendDataPool

# Nur Transform-Logs
tail -f storage/logs/laravel.log | grep TransformDataPoolToProduction

Beispiele

Kompletter Rebuild mit Custom Settings

php artisan backend:rebuild \
  --batch-size=5000 \
  --transform-batch-size=250

Nur neuen Daten synchronisieren und transformieren

php artisan backend:sync-data-pool --incremental
php artisan backend:transform-data-pool

Statistiken aller Systeme anzeigen

php artisan backend:sync-data-pool --stats
php artisan backend:transform-data-pool --stats

Performance-Tipps

Batch-Größe anpassen:
- Kleine Batches (100-500): Weniger RAM, langsamer
- Große Batches (2000-5000): Mehr RAM, schneller

Queue nutzen für lange Jobs:

php artisan backend:sync-data-pool --full --queue

Incremental Sync bevorzugen:
- Full Sync nur wenn wirklich nötig
- Incremental ist viel schneller
Off-Peak Zeiten nutzen:
- Full Sync: Sonntag 3:00 Uhr (bereits konfiguriert)
- Incremental: Alle 6 Stunden (bereits konfiguriert)

Weiterführende Links

routes/console.php - Scheduler Configuration
app/Jobs/SyncBackendDataPool.php - Sync Job
app/Jobs/TransformDataPoolToProduction.php - Transform Job
app/Console/Commands/SyncBackendDataPoolCommand.php
app/Console/Commands/TransformDataPoolCommand.php
app/Console/Commands/RebuildFromDataPoolCommand.php

10 KiB Raw Blame History

Backend Sync & Transform Commands

Übersicht

1. Backend Sync Command

Verwendung

Incremental Sync (Standard)

Full Sync

Statistiken anzeigen

Im Hintergrund über Queue

Batch-Größe anpassen

Optionen

Datenbankverbindungen

Was passiert beim Sync?

2. Transform Command

Verwendung

Standard Transformation

Statistiken anzeigen

Im Hintergrund über Queue

Batch-Größe anpassen

Optionen

Datenbankverbindungen

Was passiert bei der Transformation?

Risk Score Mapping

3. Complete Rebuild Command

Verwendung

Standard Rebuild

Mit angepassten Batch-Größen

Im Hintergrund über Queue

Optionen

Ablauf

Automatisierung mit Laravel Scheduler

Aktuelle Schedule

Scheduler aktivieren

Für lokale Entwicklung

Für Produktion (Crontab)

Scheduled Tasks anzeigen

Scheduled Task testen

Features

Alle Commands bieten

Datenfluss

Troubleshooting

Command funktioniert nicht

Queue-Jobs laufen nicht

Logs prüfen

Beispiele

Kompletter Rebuild mit Custom Settings

Nur neuen Daten synchronisieren und transformieren

Statistiken aller Systeme anzeigen

Performance-Tipps

Weiterführende Links

10 KiB

Raw Blame History