# Workflow-Zeitreise

Queuety kann einen Workflow auf einen früheren Schritt zurücksetzen und die Ausführung von dort fortsetzen. Das ist nützlich, wenn ein Schritt eine fehlerhafte Ausgabe erzeugt hat, du es mit einer anderen Konfiguration erneut versuchen möchtest oder beschädigte Daten beheben musst, ohne den gesamten Workflow neu zu starten.

Das Zurücksetzen stützt sich auf das [Workflow-Ereignisprotokoll](https://queuety.inline0.dev/de/docs/workflows/event-log). Für den Zielschritt muss das Ereignisprotokoll `state_after`-Daten enthalten.

## Einen Workflow zurücksetzen

### PHP API

Rufe `Queuety::rewind_workflow()` mit der Workflow-ID und dem Index des Schritts auf, zu dem du zurücksetzen möchtest:

```php
use Queuety\Queuety;

// Rewind workflow 42 to step 1.
// The state is restored to the snapshot taken after step 1 completed,
// and step 2 is enqueued for re-execution.
Queuety::rewind_workflow( $workflow_id, to_step: 1 );
```

Der Parameter `to_step` ist der nullbasierte Index des Schritts, dessen abgeschlossener Zustand wiederhergestellt werden soll. Die Ausführung wird mit dem _nächsten_ Schritt fortgesetzt (to_step + 1).

### CLI

```bash
wp queuety workflow rewind <id> <step>
```

| Option | Beschreibung |
|---|---|
| `<id>` | Workflow-ID (erforderlich) |
| `<step>` | Schrittindex, auf den zurückgesetzt werden soll, beginnend bei 0 (erforderlich) |

```bash
wp queuety workflow rewind 42 1
```

## So funktioniert es

Wenn du einen Workflow auf Schritt N zurücksetzt:

1. Wird das Ereignisprotokoll nach dem `state_after`-Wert abgefragt, der nach Abschluss von Schritt N aufgezeichnet wurde
2. Wird ein `RuntimeException` ausgelöst, wenn kein Snapshot vorhanden ist
3. Wird die Workflow-Zeile gesperrt
4. Wird der Workflow-Zustand durch den Snapshot ersetzt, wobei alle reservierten Schlüssel (`_steps`, `_queue`, `_priority` usw.) aus der aktuellen Workflow-Zeile erhalten bleiben
5. Wird `current_step` auf N + 1 und `status` auf `running` gesetzt
6. Werden alle Felder `error_message` und `failed_at` geleert
7. Wird der Schritt mit Index N + 1 zur Verarbeitung eingereiht
8. Wird ein `workflow_rewound`-Protokollereignis aufgezeichnet

Anschließend übernimmt der Worker den eingereihten Schritt und der Workflow läuft ab diesem Punkt wie gewohnt weiter.

## Voraussetzungen

Zum Zurücksetzen werden `state_after`-Daten im Ereignisprotokoll benötigt. Das Ereignisprotokoll zeichnet sie automatisch für jedes `step_completed`-Ereignis auf. Wurde das Ereignisprotokoll bereinigt (über `WorkflowEventLog::prune()`) und ist der Zustand des Zielschritts nicht mehr vorhanden, schlägt das Zurücksetzen fehl.

Stelle sicher, dass die Aufbewahrungsdauer deines Ereignisprotokolls den Zeitraum abdeckt, auf den du möglicherweise zurücksetzen musst.

## Anwendungsfälle

### Einen fehlerhaften Schritt-Handler korrigieren

Wenn ein Schritt-Handler aufgrund eines Fehlers falsche Ausgaben erzeugt hat, kannst du den Fix bereitstellen und den Workflow zurücksetzen:

```php
// Step 2 (CallLLMHandler) produced garbled output due to a prompt bug.
// After fixing CallLLMHandler, rewind to step 1 so step 2 runs again
// with the corrected handler.
Queuety::rewind_workflow( $workflow_id, to_step: 1 );
```

### Mit einer anderen Konfiguration erneut versuchen

Wenn ein Schritt aufgrund externer Faktoren fehlgeschlagen ist (API-Ratenbegrenzung, ungültige Zugangsdaten), korrigiere die Konfiguration und setze den Workflow zurück, um den Schritt erneut auszuführen:

```php
// Step 3 failed because the API key was expired.
// After updating the key, rewind to step 2 so step 3 retries.
Queuety::rewind_workflow( $workflow_id, to_step: 2 );
```

### Fehlerhafte Daten wiederherstellen

Wenn ein früherer Schritt fehlerhafte Daten in den Zustand eingebracht hat, setze den Workflow auf einen bekannten gültigen Snapshot zurück:

```php
// Step 0 fetched correct data, but step 1 corrupted it.
// Rewind to step 0 to restore the good state and re-run step 1.
Queuety::rewind_workflow( $workflow_id, to_step: 0 );
```

## Vergleich mit erneutem Versuch

| Aspekt | `retry_workflow()` | `rewind_workflow()` |
|---|---|---|
| Fortsetzung ab | Fehlgeschlagenem Schritt | Beliebigem vorherigen Schritt |
| Zustand | Aktueller Workflow-Zustand | Aus dem Ereignisprotokoll wiederhergestellt `state_after` |
| Voraussetzung | Workflow hat den Status `failed` | Snapshot des Ereignisprotokolls beim Zielschritt |
| Status danach | `running` | `running` |
| Protokollereignis | keines | `workflow_rewound` |