State Management

Last Updated: Juli 2025
Version: 1.0 - Spatie Laravel Model States
Status: ✅ Aktuell - Basierend auf aktueller Implementierung

Übersicht

Das System verwendet Spatie Laravel Model States für die Zustandsverwaltung verschiedener Entitäten.

State Transitions

User States

📋 Mermaid-Code kopieren

stateDiagram-v2
    [*] --> Requested : Registrierung
    Requested --> Active : Email bestätigt / Admin approval
    Active --> Deactivated : Deaktivierung
    Deactivated --> Active : Reaktivierung
    
    note right of Requested
        Neue Benutzerregistrierung
        Wartet auf Bestätigung
    end note
    
    note right of Active
        Voll funktionsfähiger Account
        Kann alle Features nutzen
    end note
    
    note right of Deactivated
        Temporär deaktiviert
        Keine Anmeldung möglich
    end note

Order States

📋 Mermaid-Code kopieren

stateDiagram-v2
    [*] --> Open : Auftrag erstellt
    Open --> Assigned : Sprachmittler zugewiesen
    Open --> NotMatched : Keine Sprachmittler gefunden
    Assigned --> InProgress : Service gestartet
    InProgress --> Completed : Service beendet
    Completed --> InvoiceCreated : Rechnung erstellt
    InvoiceCreated --> PaymentReceived : Zahlung erhalten
    NotMatched --> Open : Erneute Suche
    
    note right of Open
        Wartet auf Sprachmittler-Zuweisung
        ORDER_REQUESTS werden erstellt
    end note
    
    note right of Assigned
        Sprachmittler hat angenommen
        ASSIGNMENT erstellt
    end note
    
    note right of Completed
        Service durchgeführt
        Bereit für Abrechnung
    end note

OrderRequest States

📋 Mermaid-Code kopieren

stateDiagram-v2
    [*] --> Requested : Sprachmittler benachrichtigt
    Requested --> Accepted : Sprachmittler nimmt an
    Requested --> Rejected : Sprachmittler lehnt ab
    Requested --> Expired : Timeout erreicht
    
    Accepted --> [*] : Assignment erstellt
    Rejected --> [*] : Nächster Kandidat
    Expired --> [*] : Nächster Kandidat
    
    note right of Accepted
        Order.state = Assigned
        Assignment erstellt
    end note
    
    note right of Rejected
        rejection_reason gespeichert
        previous_rejections updated
    end note
    
    note right of Expired
        timeout_at überschritten
        attempt_number erhöht
    end note

Invoice States

📋 Mermaid-Code kopieren

stateDiagram-v2
    [*] --> Draft : Rechnung erstellt
    Draft --> Submitted : Eingereicht zur Prüfung
    Submitted --> Approved : Von Admin genehmigt
    Submitted --> Rejected : Von Admin abgelehnt
    Approved --> Paid : Zahlung erhalten
    Rejected --> Draft : Korrektur erforderlich
    
    note right of Draft
        Automatisch erstellt
        Editierbar
    end note
    
    note right of Submitted
        Wartet auf Admin-Prüfung
        Nicht mehr editierbar
    end note
    
    note right of Approved
        Bereit für Zahlung
        Rechnung versandt
    end note

State Implementation

Model Konfiguration

// Order Model
use Spatie\ModelStates\HasStates;

class Order extends Model
{
    use HasStates;
    
    protected $casts = [
        'state' => OrderState::class,
    ];
    
    public function updateStatus($newState, ?string $reason = null): bool
    {
        try {
            $this->state->transitionTo($newState);
            $this->save();
            
            // Log state change
            activity('order_state_changed')
                ->on($this)
                ->withProperties(['new_state' => $newState::class, 'reason' => $reason])
                ->log('Order state changed');
                
            return true;
        } catch (TransitionNotFound $e) {
            return false;
        }
    }
}

State Classes

// Base State Class
abstract class OrderState extends State
{
    abstract public function color(): string;
    abstract public function label(): string;
    
    public static function config(): StateConfig
    {
        return parent::config()
            ->default(Open::class)
            ->allowTransition(Open::class, Assigned::class)
            ->allowTransition(Open::class, NotMatched::class)
            ->allowTransition(Assigned::class, InProgress::class)
            ->allowTransition(InProgress::class, Completed::class)
            ->allowTransition(Completed::class, InvoiceCreated::class);
    }
}

State Queries

Verfügbare Helper

// Alle offenen Orders
$openOrders = Order::whereState('state', Open::class)->get();

// Orders mit bestimmten States
$activeOrders = Order::whereStateIn('state', [
    Open::class, 
    Assigned::class, 
    InProgress::class
])->get();

// State Transitions prüfen
if ($order->state->canTransitionTo(Assigned::class)) {
    $order->state->transitionTo(Assigned::class);
}

Custom Scopes

// Order Model
public function scopeAwaitingAssignment($query)
{
    return $query->whereState('state', Open::class);
}

public function scopeInProgress($query)
{
    return $query->whereStateIn('state', [
        Assigned::class,
        InProgress::class
    ]);
}

public function scopeCompleted($query)
{
    return $query->whereStateIn('state', [
        Completed::class,
        InvoiceCreated::class,
        PaymentReceived::class
    ]);
}

Frontend Integration

Status Display

Die States werden für das Frontend in lesbare Strings konvertiert:

// Order Model
public function getStatusAttribute(): string
{
    return match($this->state::class) {
        Open::class => 'Offen',
        Assigned::class => 'Zugewiesen',
        InProgress::class => 'In Bearbeitung',
        Completed::class => 'Abgeschlossen',
        NotMatched::class => 'Keine Sprachmittler',
        default => 'Unbekannt'
    };
}

Color Coding

// State Classes
class Open extends OrderState
{
    public function color(): string { return 'orange'; }
    public function label(): string { return 'Offen'; }
}

class Assigned extends OrderState  
{
    public function color(): string { return 'blue'; }
    public function label(): string { return 'Zugewiesen'; }
}

class Completed extends OrderState
{
    public function color(): string { return 'green'; }
    public function label(): string { return 'Abgeschlossen'; }
}

---

Tags: #state-management #spatie #laravel #workflow #transitions