# Voyage dans le temps dans les workflows

Queuety permet de revenir à une étape antérieure du workflow et de reprendre l’exécution à partir de ce point. C’est utile si une étape a produit un résultat incorrect, si vous souhaitez réessayer avec une configuration différente ou si vous devez récupérer des données corrompues sans redémarrer tout le workflow.

Le retour en arrière repose sur le [journal des événements du workflow](https://queuety.inline0.dev/fr/docs/workflows/event-log). Celui-ci doit contenir des données `state_after` pour l’étape cible.

## Revenir en arrière dans un workflow

### PHP API

Appelez `Queuety::rewind_workflow()` avec l’identifiant du workflow et l’index de l’étape à laquelle revenir :

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

Le paramètre `to_step` est l’index à partir de zéro de l’étape dont l’état terminé doit être restauré. L’exécution reprend à l’étape _suivante_ (to_step + 1).

### CLI

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

| Option | Description |
|---|---|
| `<id>` | ID du workflow (obligatoire) |
| `<step>` | Index de l’étape à rétablir, à partir de 0 (obligatoire) |

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

## Fonctionnement

Lorsque vous ramenez un workflow à l’étape N :

1. Le journal des événements est consulté pour obtenir la valeur `state_after` enregistrée après la fin de l’étape N
2. Si aucun instantané n’existe, une `RuntimeException` est levée
3. La ligne du workflow est verrouillée
4. L’état du workflow est remplacé par l’instantané, en conservant toutes les clés réservées (`_steps`, `_queue`, `_priority`, etc.) de la ligne de workflow actuelle
5. `current_step` est défini sur N + 1 et `status` sur `running`
6. Tous les champs `error_message` et `failed_at` sont effacés
7. L’étape à l’index N + 1 est mise en file d’attente pour traitement
8. Un événement de journal `workflow_rewound` est enregistré

Le worker récupère ensuite l’étape mise en file d’attente, et le workflow reprend normalement à partir de là.

## Prérequis

Le retour en arrière nécessite des données `state_after` dans le journal des événements. Celui-ci les enregistre automatiquement pour chaque événement `step_completed`. Si le journal des événements a été purgé (via `WorkflowEventLog::prune()`) et que l’état de l’étape cible n’existe plus, le retour en arrière échouera.

Assurez-vous que la durée de conservation du journal des événements couvre la période à laquelle vous pourriez devoir revenir.

## Cas d’utilisation

### Corriger un gestionnaire d’étape défectueux

Si un gestionnaire d’étape contenait un bug produisant un résultat incorrect, vous pouvez déployer le correctif et revenir en arrière :

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

### Réessayer avec une configuration différente

Lorsqu’une étape a échoué à cause de facteurs externes (API limite de débit, identifiants incorrects), corrigez la configuration et revenez en arrière pour la relancer :

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

### Récupérer après des données erronées

Si une étape antérieure a injecté des données erronées dans l’état, revenez à un instantané connu comme fiable :

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

## Comparaison avec une nouvelle tentative

| Aspect | `retry_workflow()` | `rewind_workflow()` |
|---|---|---|
| Reprise à partir de | L’étape en échec | N’importe quelle étape précédente |
| État | État actuel du workflow | Restauré depuis l’`state_after` du journal des événements |
| Nécessite | Que le workflow soit au statut `failed` | Un instantané du journal des événements à l’étape cible |
| Statut après | `running` | `running` |
| Événement de journal | aucun | `workflow_rewound` |