mivita/dev/2026-01-28/BUSINESS_FORCE_EXECUTE.md

# BUSINESS_FORCE_EXECUTE - Test-Server Konfiguration

## Übersicht

Die ENV-Variable `BUSINESS_FORCE_EXECUTE` erlaubt es, die Business-Commands auch an Tagen auszuführen, die nicht dem konfigurierten Ausführungstag entsprechen.

**⚠️ WICHTIG:** Diese Variable sollte **NUR auf Test-Servern** verwendet werden!

---

## Verwendung

### Auf Test-Server aktivieren

**1. .env Datei bearbeiten:**

```bash
# In .env Datei hinzufügen:
BUSINESS_FORCE_EXECUTE=true
```

**2. Commands testen:**

```bash
# Command kann jetzt an jedem Tag ausgeführt werden
php artisan business:store-optimized 0 0

# Erwartete Ausgabe:
# ⚠️  BUSINESS_FORCE_EXECUTE ist aktiv - Command wird trotz falschem Tag ausgeführt!
# ⚠️  Dies sollte NUR auf Test-Servern verwendet werden!
# ✅ Command wird ausgeführt...
```

### Auf Live-Server DEAKTIVIEREN

**In .env Datei auf Live-Server:**

```bash
# NICHT setzen oder explizit auf false:
# BUSINESS_FORCE_EXECUTE=false

# Oder ganz weglassen (Standard ist false)
```

---

## Vorteile der neuen Lösung

### ✅ Vor dem Fix (mit auskommentiertem return)

**Problem:**

```php
if ($executeDay !== $presentDay) {
    $this->info('NOT RUN ...');
    //  return 0;  // ← Auskommentiert während Entwicklung
}
// ❌ Command läuft weiter, auch wenn er nicht sollte!
```

**Nachteile:**

- Entwickler vergisst Kommentar zu entfernen
- Command läuft versehentlich auf Live-Server
- Git-Commit enthält auskommentiertes return
- Schwer zu debuggen

### ✅ Nach dem Fix (mit ENV-Variable)

**Lösung:**

```php
private function shouldExecuteToday(): bool
{
    $executeDay = (int) Setting::getContentBySlug('day-exectute-business-structur');
    $presentDay = (int) date('d');

    if ($executeDay !== $presentDay) {
        // Überschreibung NUR mit ENV-Variable möglich
        if (env('BUSINESS_FORCE_EXECUTE', false) === true) {
            $this->warn("⚠️  BUSINESS_FORCE_EXECUTE ist aktiv!");
            return true;
        }

        return false;  // ← IMMER hier, kann nicht auskommentiert werden
    }

    return true;
}
```

**Vorteile:**

- ✅ Kein Code muss auskommentiert werden
- ✅ Funktioniert sofort auf Test-Server (mit ENV)
- ✅ Sicher auf Live-Server (ohne ENV)
- ✅ Klare Warnungen wenn Force aktiv ist
- ✅ Besseres Logging
- ✅ Fallback wenn Setting leer ist

---

## Zusätzliche Features

### 1. Automatischer Fallback

Wenn das Setting `day-exectute-business-structur` leer ist:

```php
if ($executeDay === 0) {
    $executeDay = 1;  // Standard: Tag 1
    $this->warn('Setting ist leer - verwende Standard: Tag 1');
}
```

**Vorteil:** Command funktioniert auch wenn Setting vergessen wurde zu setzen.

### 2. Besseres Logging

```
[2026-01-28 03:00:02] BusinessStoreOptimized: Configured Day: 1, Present Day: 28
[2026-01-28 03:00:02] BusinessStoreOptimized: NOT EXECUTED - wrong day (expected: 1, today: 28)
```

**Vorteil:** Klar erkennbar warum Command nicht läuft.

### 3. Visuelle Warnungen

Wenn `BUSINESS_FORCE_EXECUTE=true`:

```
⚠️  BUSINESS_FORCE_EXECUTE ist aktiv - Command wird trotz falschem Tag ausgeführt!
⚠️  Dies sollte NUR auf Test-Servern verwendet werden!
```

**Vorteil:** Entwickler sieht sofort, dass Force-Mode aktiv ist.

---

## Test-Szenarien

### Szenario 1: Test-Server - Entwicklung

```bash
# .env
BUSINESS_FORCE_EXECUTE=true

# Command kann jederzeit ausgeführt werden
php artisan business:store-optimized 12 2025
php artisan business:store-optimized 0 0

# ✅ Läuft ohne Probleme
```

### Szenario 2: Live-Server - Normalbetrieb

```bash
# .env
# BUSINESS_FORCE_EXECUTE nicht gesetzt (oder =false)

# Scheduler ruft täglich auf:
# php artisan business:store-optimized 0 0

# Nur am Tag 1 wird tatsächlich ausgeführt:
# 01.02.2026 03:00 → ✅ EXECUTED
# 02.02.2026 03:00 → ❌ NOT EXECUTED
# 03.02.2026 03:00 → ❌ NOT EXECUTED
# ...
# 01.03.2026 03:00 → ✅ EXECUTED
```

### Szenario 3: Live-Server - Manuelle Ausführung

```bash
# Admin muss manuell für alten Monat ausführen
php artisan business:store-optimized 11 2025 --clear

# Funktioniert jederzeit, da spezifische Parameter
# (nicht 0 0, daher kein Vormonat-Check)
```

---

## Migration Guide

### Schritt 1: Test-Server

```bash
# 1. Code aktualisieren (Git pull)
git pull origin main

# 2. ENV-Variable setzen
echo "BUSINESS_FORCE_EXECUTE=true" >> .env

# 3. Testen
php artisan business:store-optimized 0 0

# Erwartete Ausgabe:
# ⚠️  BUSINESS_FORCE_EXECUTE ist aktiv...
# ✅ Command wird ausgeführt
```

### Schritt 2: Live-Server

```bash
# 1. Backup erstellen
php artisan backup:run

# 2. Code aktualisieren
cd /home/ploi/mivita.care
git pull origin main

# 3. ENV prüfen (NICHT setzen!)
grep BUSINESS_FORCE_EXECUTE .env
# Sollte NICHTS finden oder =false

# 4. Cache leeren
php8.4 artisan config:clear
php8.4 artisan cache:clear

# 5. Testen (falscher Tag)
php8.4 artisan business:store-optimized 0 0

# Erwartete Ausgabe:
# ❌ Command wird NICHT ausgeführt - falscher Tag
```

---

## Troubleshooting

### Problem: Command läuft auf Live nicht mehr

**Symptom:**

```
❌ Command wird NICHT ausgeführt - falscher Tag (erwartet: 1, heute: 28)
```

**Lösung:**

- Das ist **korrekt**! Command sollte nur am Tag 1 laufen
- Warte bis zum 1. des nächsten Monats
- Oder führe manuell aus: `php artisan business:store-optimized 12 2025`

### Problem: Setting ist leer

**Symptom:**

```
Setting "day-exectute-business-structur" ist leer oder 0. Verwende Standard: Tag 1
```

**Lösung:**

```bash
php artisan tinker --execute="
\$setting = \App\Models\Setting::where('slug', 'day-exectute-business-structur')->first();
if (!\$setting) {
    \$setting = new \App\Models\Setting();
    \$setting->slug = 'day-exectute-business-structur';
}
\$setting->content = '1';
\$setting->save();
echo 'Setting updated to: 1\n';
"
```

### Problem: FORCE_EXECUTE auf Live aktiv

**Symptom:**

```
⚠️  BUSINESS_FORCE_EXECUTE ist aktiv - Command wird trotz falschem Tag ausgeführt!
```

**Lösung:**

```bash
# .env Datei bearbeiten
nano .env

# Zeile entfernen oder auf false setzen:
BUSINESS_FORCE_EXECUTE=false

# Cache leeren
php artisan config:clear
```

---

## Best Practices

### ✅ DO

- ENV-Variable NUR auf Test-Servern setzen
- Klare Dokumentation in .env.example
- Logs regelmäßig prüfen
- Cache nach ENV-Änderungen leeren

### ❌ DON'T

- NIEMALS auf Live-Server `BUSINESS_FORCE_EXECUTE=true` setzen
- Kein Code-Auskommentieren mehr für Tests
- Keine manuellen Scheduler-Anpassungen für Tests
- Nicht vergessen Setting zu setzen (day-exectute-business-structur)

---

## Zusammenfassung

| Aspekt          | Alt (mit Kommentar)  | Neu (mit ENV)             |
| --------------- | -------------------- | ------------------------- |
| **Test-Server** | Code auskommentieren | ENV-Variable setzen       |
| **Live-Server** | Kommentar vergessen  | ENV nicht setzen (sicher) |
| **Sicherheit**  | ❌ Fehleranfällig    | ✅ Sicher                 |
| **Wartbarkeit** | ❌ Schwierig         | ✅ Einfach                |
| **Logging**     | ⚠️ Basic             | ✅ Ausführlich            |
| **Fallback**    | ❌ Kein              | ✅ Automatisch            |

---

## Weitere Verbesserungen (optional)

### Idee 1: Command mit --force Flag

```php
protected $signature = 'business:store-optimized {month} {year} {--clear} {--force}';

if ($this->option('force')) {
    $this->warn('--force Flag aktiv - Tag-Check wird übersprungen');
    return true;
}
```

### Idee 2: Notification bei Force-Ausführung

```php
if (env('BUSINESS_FORCE_EXECUTE', false) === true) {
    \Mail::to('admin@mivita.care')->send(
        new \App\Mail\BusinessForcedExecutionMail()
    );
}
```

### Idee 3: Test-Modus in UI anzeigen

```php
// In Layout-Header
@if(env('BUSINESS_FORCE_EXECUTE', false))
    <div class="alert alert-warning">
        ⚠️ TEST-MODUS: Business-Commands laufen mit FORCE_EXECUTE
    </div>
@endif
```

---

## Support

Bei Fragen oder Problemen:

1. Logs prüfen: `storage/logs/laravel.log`
2. ENV-Variable prüfen: `php artisan config:show`
3. Setting prüfen: `php artisan tinker` → `Setting::where('slug', 'day-exectute-business-structur')->first()`
4. Dokumentation: `/dev/28-01-2026/business-store-timing-fix.md`