# Työnkulun aikamatka

Queuety voi palauttaa työnkulun aiempaan vaiheeseen ja jatkaa suoritusta siitä kohdasta. Tästä on hyötyä, jos vaihe tuotti virheellistä tulostetta, haluat yrittää uudelleen eri asetuksilla tai sinun on palautettava vioittuneet tiedot käynnistämättä koko työnkulkua uudelleen.

Palautus perustuu kohteeseen [Työnkulun tapahtumaloki](https://queuety.inline0.dev/fi/docs/workflows/event-log). Tapahtumalokissa on oltava kohdevaiheen `state_after`-tiedot.

## Työnkulun palauttaminen aiempaan vaiheeseen

### PHP API

Kutsu kohdetta `Queuety::rewind_workflow()` työnkulun tunnuksella ja sen vaiheen indeksillä, johon haluat palata:

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

Parametri `to_step` on nollasta alkava indeksi vaiheelle, jonka valmistunut tila palautetaan. Suoritus jatkuu _seuraavasta_ vaiheesta (to_step + 1).

### CLI

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

| Valitsin | Kuvaus |
|---|---|
| `<id>` | Työnkulun tunniste (pakollinen) |
| `<step>` | Kelattavan vaiheen järjestysnumero nollasta alkaen (pakollinen) |

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

## Näin se toimii

Kun palautat työnkulun vaiheeseen N:

1. Tapahtumalokista kysytään arvo `state_after`, joka tallennettiin vaiheen N valmistuttua
2. Jos tilannevedosta ei löydy, heitetään poikkeus `RuntimeException`
3. Työnkulkurivi lukitaan
4. Työnkulun tila korvataan tilannevedoksella, mutta nykyisen työnkulkurivin varatut avaimet (`_steps`, `_queue`, `_priority` jne.) säilytetään
5. `current_step`-arvoksi asetetaan N + 1 ja `status`-arvoksi asetetaan `running`
6. Kaikki kentät `error_message` ja `failed_at` tyhjennetään
7. Indeksin N + 1 vaihe asetetaan jonoon käsittelyä varten
8. Lokitapahtuma `workflow_rewound` kirjataan

Työntekijä ottaa sitten käsittelyyn jonoon asetetun vaiheen, ja työnkulku jatkuu siitä eteenpäin tavalliseen tapaan.

## Vaatimukset

Palautus edellyttää `state_after`-tietoja tapahtumalokissa. Tapahtumaloki tallentaa ne automaattisesti jokaiselle tapahtumalle `step_completed`. Jos tapahtumalokia on karsittu kohteen `WorkflowEventLog::prune()` kautta eikä kohdevaiheen tilaa enää ole, palautus epäonnistuu.

Varmista, että tapahtumalokin säilytysaika kattaa ajanjakson, johon saatat joutua palaamaan.

## Käyttötapaukset

### Virheellisen vaihekäsittelijän korjaaminen

Jos vaihekäsittelijässä oli virhe, jonka vuoksi se tuotti väärän tuloksen, voit ottaa korjauksen käyttöön ja palauttaa työnkulun:

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

### Uusi yritys eri asetuksilla

Kun vaihe epäonnistui ulkoisen tekijän (kuten API-nopeusrajoituksen tai virheellisten tunnistetietojen) vuoksi, korjaa asetukset ja suorita vaihe uudelleen palauttamalla työnkulku:

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

### Virheellisistä tiedoista palautuminen

Jos aiempi vaihe lisäsi tilaan virheellisiä tietoja, palaa tunnetusti oikeaan tilannevedokseen:

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

## Vertailu uudelleenyritykseen

| Ominaisuus | `retry_workflow()` | `rewind_workflow()` |
|---|---|---|
| Jatkaa kohdasta | Epäonnistunut vaihe | Mikä tahansa aiempi vaihe |
| Tila | Nykyinen työnkulun tila | Palautetaan tapahtumalokin `state_after`-tietojen perusteella |
| Edellyttää | Työnkulun tilana on `failed` | Tapahtumalokin tilannevedos kohdevaiheesta |
| Tila jälkeen | `running` | `running` |
| Lokitapahtuma | ei mitään | `workflow_rewound` |