# Viagem no tempo em fluxos de trabalho

Queuety pode voltar um fluxo de trabalho a uma etapa anterior e retomar a execução a partir desse ponto. Isso é útil quando uma etapa produziu uma saída incorreta, quando você quer tentar novamente com uma configuração diferente ou quando precisa se recuperar de dados corrompidos sem reiniciar todo o fluxo de trabalho.

A reversão depende do [Registro de eventos do fluxo de trabalho](https://queuety.inline0.dev/pt/docs/workflows/event-log). O registro de eventos precisa conter dados `state_after` para a etapa de destino.

## Reverter um fluxo de trabalho

### PHP API

Chame `Queuety::rewind_workflow()` com o ID do fluxo de trabalho e o índice da etapa para a qual deseja voltar:

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

O parâmetro `to_step` é o índice da etapa, iniciado em zero, cujo estado concluído deve ser restaurado. A execução é retomada na etapa _seguinte_ (to_step + 1).

### CLI

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

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |
| `<step>` | Índice da etapa para a qual retroceder, começando em 0 (obrigatório) |

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

## Como funciona

Quando você reverte um fluxo de trabalho para a etapa N:

1. O registro de eventos é consultado para obter o valor `state_after` registrado após a conclusão da etapa N
2. Se não houver um snapshot, será lançada uma `RuntimeException`
3. A linha do fluxo de trabalho é bloqueada
4. O estado do fluxo de trabalho é substituído pelo snapshot, preservando todas as chaves reservadas (`_steps`, `_queue`, `_priority` etc.) da linha atual do fluxo de trabalho
5. `current_step` é definido como N + 1 e `status` é definido como `running`
6. Todos os campos `error_message` e `failed_at` são limpos
7. A etapa do índice N + 1 é colocada na fila para processamento
8. Um evento de registro `workflow_rewound` é registrado

Em seguida, o worker processa a etapa colocada na fila, e o fluxo de trabalho prossegue normalmente a partir desse ponto.

## Requisitos

A reversão exige dados `state_after` no registro de eventos. O registro os salva automaticamente para cada evento `step_completed`. Se o registro de eventos tiver sido depurado (por meio de `WorkflowEventLog::prune()`) e o estado da etapa de destino já não existir, a reversão falhará.

Verifique se o período de retenção do registro de eventos abrange o período ao qual você talvez precise voltar.

## Casos de uso

### Corrigir um handler de etapa com defeito

Se um handler de etapa tiver um bug que produziu uma saída incorreta, você pode implantar a correção e reverter:

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

### Tentar novamente com outra configuração

Se uma etapa falhou devido a fatores externos (limite de requisições de API, credenciais incorretas), corrija a configuração e reverta para executá-la novamente:

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

### Recuperar-se de dados incorretos

Se uma etapa anterior tiver inserido dados incorretos no estado, volte a um snapshot íntegro:

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

## Comparação com a nova tentativa

| Aspecto | `retry_workflow()` | `rewind_workflow()` |
|---|---|---|
| Retoma a partir de | A etapa que falhou | Qualquer etapa anterior |
| Estado | Estado atual do fluxo de trabalho | Restaurado do snapshot do registro de eventos `state_after` |
| Requisito | O fluxo de trabalho está com status `failed` | Snapshot do registro de eventos na etapa de destino |
| Status após a operação | `running` | `running` |
| Evento de registro | nenhum | `workflow_rewound` |