# Viaggio nel tempo nei flussi di lavoro

Queuety può riportare un flusso di lavoro a un passaggio precedente e riprendere l'esecuzione da quel punto. È utile quando un passaggio ha prodotto un output errato, quando volete riprovare con una configurazione diversa o quando dovete recuperare dati corrotti senza riavviare l'intero flusso di lavoro.

Il ripristino si basa su [Workflow Event Log](https://queuety.inline0.dev/it/docs/workflows/event-log). Il registro eventi deve contenere i dati `state_after` per il passaggio di destinazione.

## Ripristinare un flusso di lavoro

### PHP API

Chiamate `Queuety::rewind_workflow()` con l'ID del flusso di lavoro e l'indice del passaggio a cui tornare:

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

Il parametro `to_step` è l'indice, a partire da zero, del passaggio il cui stato completato deve essere ripristinato. L'esecuzione riprende dal passaggio _successivo_ (to_step + 1).

### CLI

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

| Opzione | Descrizione |
|---|---|
| `<id>` | ID del workflow (obbligatorio) |
| `<step>` | Indice del passaggio a cui tornare, a partire da 0 (obbligatorio) |

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

## Come funziona

Quando riportate un flusso di lavoro al passaggio N:

1. Il registro eventi viene interrogato per recuperare il valore `state_after` registrato al completamento del passaggio N
2. Se non esiste uno snapshot, viene generata un'eccezione `RuntimeException`
3. La riga del flusso di lavoro viene bloccata
4. Lo stato del flusso di lavoro viene sostituito con lo snapshot, mantenendo tutte le chiavi riservate (`_steps`, `_queue`, `_priority`, ecc.) della riga corrente
5. `current_step` viene impostato su N + 1 e `status` viene impostato su `running`
6. I campi `error_message` e `failed_at` vengono cancellati
7. Il passaggio all'indice N + 1 viene accodato per l'elaborazione
8. Viene registrato un evento di log `workflow_rewound`

Il worker elabora quindi il passaggio accodato e il flusso di lavoro prosegue normalmente da quel punto.

## Requisiti

Per ripristinare un flusso di lavoro, il registro eventi deve contenere i dati `state_after`. Il registro eventi li registra automaticamente per ogni evento `step_completed`. Se il registro eventi è stato ridotto (tramite `WorkflowEventLog::prune()`) e lo stato del passaggio di destinazione non esiste più, il ripristino non riuscirà.

Assicuratevi che il periodo di conservazione del registro eventi copra l'intervallo a cui potreste dover tornare.

## Casi d'uso

### Correggere un gestore di passaggio difettoso

Se un gestore di passaggio conteneva un bug che produceva un output errato, potete distribuire la correzione e ripristinare il flusso:

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

### Riprovare con una configurazione diversa

Quando un passaggio non è riuscito per fattori esterni (API limiti di frequenza, credenziali non valide), correggete la configurazione e ripristinate il flusso per rieseguirlo:

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

### Recuperare dati errati

Se un passaggio precedente ha inserito dati errati nello stato, ripristinate uno snapshot noto come valido:

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

## Confronto con i nuovi tentativi

| Aspetto | `retry_workflow()` | `rewind_workflow()` |
|---|---|---|
| Riprende da | Il passaggio non riuscito | Qualsiasi passaggio precedente |
| Stato | Stato attuale del flusso di lavoro | Ripristinato dallo snapshot del registro eventi `state_after` |
| Requisito | Il flusso di lavoro è nello stato `failed` | Snapshot del registro eventi al passaggio di destinazione |
| Stato successivo | `running` | `running` |
| Evento di log | nessuno | `workflow_rewound` |