mivita/docs/BusinessUpdateCalculatedFields.md

Business Update Calculated Fields Command

Übersicht

Der Command business:update-calculated-fields aktualisiert bereits gespeicherte UserBusiness-Einträge mit den neuen berechneten Feldern für Level-Qualifikationen.

Zweck

Nach der Korrektur der Karriere-Level-Berechnung müssen bereits in der Datenbank gespeicherte UserBusiness-Einträge aktualisiert werden, um die neuen berechneten Felder zu erhalten:

Neue Felder:

1. calc_qual_kp (in UserBusiness)

   • Die berechnete KP-Qualifikation für den erreichten Level
   • Zeigt an, wie viele KP-Punkte tatsächlich für die Qualifikation verwendet wurden

2. _calculated_qual_kp (in Level-Arrays)

   • Für qual_user_level_next, next_qual_user_level, next_can_user_level
   • Die berechnete KP für jeden spezifischen Level

3. _calculated_payline_points (in Level-Arrays)

   • Die Payline-Punkte basierend auf den spezifischen Paylines des Levels

4. _calculated_payline_points_qual_kp (in Level-Arrays)

   • Die Gesamtpunkte (Payline + Rest-KP) für den Level

Verwendung

Grundlegende Syntax

# Einzelner Monat
php artisan business:update-calculated-fields {year} {month}

# Ganzes Jahr (alle 12 Monate)
php artisan business:update-calculated-fields {year}

Mit Dry-Run (Testlauf)

# Einzelner Monat
php artisan business:update-calculated-fields {year} {month} --dry-run

# Ganzes Jahr
php artisan business:update-calculated-fields {year} --dry-run

Im Dry-Run Modus werden keine Änderungen in der Datenbank gespeichert. Der Command zeigt nur an, welche Einträge aktualisiert werden würden.

Beispiele

Aktualisiere November 2025

php artisan business:update-calculated-fields 2025 11

Aktualisiere das ganze Jahr 2025

php artisan business:update-calculated-fields 2025

Das wird alle 12 Monate von Januar bis Dezember 2025 aktualisieren.

Testlauf für Oktober 2025

php artisan business:update-calculated-fields 2025 10 --dry-run

Testlauf für das ganze Jahr 2025

php artisan business:update-calculated-fields 2025 --dry-run

Ablauf

Einzelner Monat

1. Lade UserBusiness-Einträge: Alle Einträge für den angegebenen Monat/Jahr
2. Berechne neue Felder: Für jeden Eintrag werden die berechneten Felder hinzugefügt
3. Speichere Änderungen: Nur wenn Änderungen vorhanden sind (und nicht im Dry-Run)
4. Zeige Statistik: Anzahl aktualisierter, übersprungener und fehlerhafter Einträge

Ganzes Jahr

1. Durchlaufe alle 12 Monate: Januar (1) bis Dezember (12)
2. Für jeden Monat:
   • Lade UserBusiness-Einträge
   • Berechne neue Felder
   • Speichere Änderungen
   • Zeige Monats-Statistik
3. Zeige Jahres-Zusammenfassung: Gesamtstatistik über alle Monate

Was wird berechnet?

calc_qual_kp (für aktuellen Level)

$rest_kp = max(0, $sales_volume_points_KP_sum - $qual_kp);
$calc_qual_kp = $rest_kp > 0 ? $qual_kp : $sales_volume_points_KP_sum;

• Wenn Rest-KP > 0: Nutze die volle qual_kp des Levels
• Sonst: Nutze alle verfügbaren KP-Punkte

Für Level-Arrays (next_qual_user_level, etc.)

$payline_points = sum($business_lines[1..paylines]['points']);
$rest_kp = max(0, $sales_volume_points_KP_sum - $level['qual_kp']);
$payline_points_qual_kp = $payline_points + $rest_kp;
$calculated_qual_kp = $rest_kp > 0 ? $level['qual_kp'] : $sales_volume_points_KP_sum;

Output

Einzelner Monat

Der Command zeigt:

• Progress Bar während der Verarbeitung
• Memory-Nutzung alle 100 Einträge
• Abschließende Statistik:
  • Anzahl aktualisierter Einträge
  • Anzahl übersprungener Einträge (bereits aktualisiert)
  • Anzahl Fehler
• Ausführungszeit

Beispiel Output:

Starte Update für Monat: 11 | Jahr: 2025
[Command Start] Memory: 12.5 MB / 512 MB (2.44%) | Peak: 12.5 MB
Gefunden: 1547 UserBusiness-Einträge
 1547/1547 [============================] 100%
[Nach 100 Einträgen] Memory: 45.3 MB / 512 MB (8.85%) | Peak: 48.2 MB
...

Update abgeschlossen:
  - Aktualisiert: 1547
  - Übersprungen: 0
  - Fehler: 0
UPDATE COMPLETED SUCCESSFULLY | Zeit: 12sec :345.6789 ms

Ganzes Jahr

Der Command zeigt:

• Für jeden Monat:
  • Progress Bar
  • Monats-Statistik
  • Memory-Nutzung nach dem Monat
• Abschließende Jahres-Zusammenfassung

Beispiel Output:

Starte Update für ALLE MONATE des Jahres: 2025
======================================================================

┌─────────────────────────────────────────────────────────────────────┐
│ Verarbeite Monat: 01/2025                                           │
└─────────────────────────────────────────────────────────────────────┘
  Gefunden: 1245 UserBusiness-Einträge
 1245/1245 [============================] 100%
  ✓ Monat 1 abgeschlossen: 1245 aktualisiert, 0 übersprungen, 0 Fehler
[Nach Monat 1] Memory: 48.2 MB / 512 MB (9.41%) | Peak: 52.1 MB

┌─────────────────────────────────────────────────────────────────────┐
│ Verarbeite Monat: 02/2025                                           │
└─────────────────────────────────────────────────────────────────────┘
  Gefunden: 1367 UserBusiness-Einträge
 1367/1367 [============================] 100%
  ✓ Monat 2 abgeschlossen: 1367 aktualisiert, 0 übersprungen, 0 Fehler
[Nach Monat 2] Memory: 51.3 MB / 512 MB (10.02%) | Peak: 55.4 MB

[... weitere Monate ...]

======================================================================
ZUSAMMENFASSUNG FÜR DAS JAHR 2025:
======================================================================
Verarbeitete Monate:     12/12
Fehlgeschlagene Monate:  0
Gesamt aktualisiert:     15432
Gesamt übersprungen:     0
Gesamt Fehler:           0
======================================================================
JAHRES-UPDATE ABGESCHLOSSEN | Zeit: 145sec :678.9012 ms
[Command End] Memory: 62.8 MB / 512 MB (12.27%) | Peak: 68.2 MB

Migration

Vor dem ersten Ausführen des Commands muss die Migration ausgeführt werden:

php artisan migrate

Die Migration fügt das neue Feld calc_qual_kp zur user_businesses Tabelle hinzu.

Integration mit BusinessStoreOptimized

Nach Ausführung von business:store-optimized können die berechneten Felder automatisch befüllt werden. Die neue Logik in BusinessUserItemOptimized.php sorgt dafür, dass bei neuen Berechnungen die Felder korrekt gesetzt werden.

Fehlerbehandlung

• Fehler bei einzelnen Einträgen führen nicht zum Abbruch
• Fehler werden geloggt und in der Statistik angezeigt
• Memory-Nutzung wird überwacht (Warnung bei >80%)

Performance

• Verarbeitet ca. 100-150 Einträge pro Sekunde
• Memory-Nutzung: ca. 30-50 MB für 1000 Einträge
• Kann für mehrere Monate/Jahre nacheinander ausgeführt werden

Hinweise

• Der Command ist idempotent (kann mehrfach ausgeführt werden)
• Bereits vorhandene Felder werden nicht überschrieben
• Nutze --dry-run für Tests vor der Produktionsausführung
• Empfohlen: Backup vor der ersten Ausführung