# 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

```bash
# 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)

```bash
# 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

```bash
php artisan business:update-calculated-fields 2025 11
```

### Aktualisiere das ganze Jahr 2025

```bash
php artisan business:update-calculated-fields 2025
```

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

### Testlauf für Oktober 2025

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

### Testlauf für das ganze Jahr 2025

```bash
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)

```php
$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.)

```php
$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:

```bash
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