# Työnkulun vienti ja toisto

Queuety voi viedä työnkulun koko suoritushistorian siirrettävään JSON-muotoon ja toistaa sen toisessa ympäristössä. Tämä on hyödyllistä tuotantovirheiden toistamiseen paikallisesti, työnkulkujen siirtämiseen ympäristöjen välillä ja auditointiin.

## Työnkulun vieminen

### PHP API

Kutsu `Queuety::export_workflow()` työnkulun tunnuksella. Se palauttaa JSON-sarjoitettavan taulukon:

```php
use Queuety\Queuety;

$data = Queuety::export_workflow( $workflow_id );
```

Saat suoraan JSON-merkkijonon seuraavasti:

```php
$json = json_encode( $data, JSON_PRETTY_PRINT );
file_put_contents( '/tmp/workflow-42.json', $json );
```

### CLI

```bash
wp queuety workflow export <id> [--output=<file>]
```

| Valitsin | Kuvaus |
|---|---|
| `<id>` | Työnkulun tunniste (pakollinen) |
| `--output=<file>` | JSON-tiedoston tallennuspolku. Oletusarvo on vakiotuloste. |

```bash
# Print to stdout
wp queuety workflow export 42

# Write to a file
wp queuety workflow export 42 --output=/tmp/workflow-42.json
```

## Työnkulun toistaminen

### PHP API

Kutsu `Queuety::replay_workflow()` vientitiedoilla. Se palauttaa uuden työnkulun tunnuksen:

```php
use Queuety\Queuety;

$json = file_get_contents( '/tmp/workflow-42.json' );
$data = json_decode( $json, true );

$new_id = Queuety::replay_workflow( $data );
```

### CLI

```bash
wp queuety workflow replay <file>
```

| Valitsin | Kuvaus |
|---|---|
| `<file>` | Viedyn JSON-tiedoston polku (pakollinen) |

```bash
wp queuety workflow replay /tmp/workflow-42.json
# Success: Workflow replayed. New workflow ID: 85.
```

## JSON-rakenne

Vienti sisältää työnkulun koko tilan, siihen liittyvät työt, jälkitapahtumat, lokimerkinnät, tallennetut signaalit, artefaktit, palat ja kaikki työnkulkujen riippuvuusodotusten rivit:

```json
{
    "workflow": {
        "id": 42,
        "name": "generate_report",
        "status": "failed",
        "state": { "user_id": 1, "_steps": [...], "_queue": "default" },
        "current_step": 2,
        "total_steps": 4,
        "parent_workflow_id": null,
        "parent_step_index": null,
        "started_at": "2026-03-28 10:00:00",
        "completed_at": null,
        "failed_at": "2026-03-28 10:05:00",
        "error_message": "API timeout",
        "deadline_at": null
    },
    "jobs": [
        {
            "id": 100,
            "queue": "default",
            "handler": "App\\Handlers\\FetchDataHandler",
            "payload": {},
            "status": "completed",
            "attempts": 1,
            "max_attempts": 3,
            "step_index": 0
        }
    ],
    "events": [
        {
            "id": 1,
            "job_id": 100,
            "step_index": 0,
            "step_name": "fetchData",
            "step_type": "single",
            "handler": "App\\Handlers\\FetchDataHandler",
            "event": "step_completed",
            "input": { "user_id": 1 },
            "output": { "records": 150 },
            "state_before": { "user_id": 1 },
            "state_after": { "user_id": 1, "records": 150 },
            "context": { "source": "api" },
            "error": null,
            "duration_ms": 230,
            "created_at": "2026-03-28 10:00:01"
        }
    ],
    "logs": [
        {
            "id": 1,
            "event": "workflow_started",
            "handler": "generate_report",
            "created_at": "2026-03-28 10:00:00"
        }
    ],
    "signals": [],
    "artifacts": [],
    "chunks": [],
    "wait_dependencies": [],
    "exported_at": "2026-03-28T12:00:00+00:00",
    "queuety_version": "0.22.0"
}
```

Osa kentistä on yllä olevassa esimerkissä lyhennetty. Todellinen vienti sisältää kaikkien tapahtumarivien kaikki jälkisarakkeet.

Työnkulkujen viennit säilyttävät myös työnkulun metatiedot, kuten `definition_version`, `definition_hash` ja `idempotency_key`, jos ne asetettiin alkuperäiselle suoritukselle.

## Toiston toiminta

Kun toistat viedyn työnkulun:

1. Luodaan uusi työnkulkumerkintä, jossa on viety tila ja vaihemääritelmät
2. Uuden työnkulun nimi on `{original_name}_replay_{timestamp}`
3. Historialliset työnkulun tapahtumat ja lokit lisätään uudelleen uuteen ympäristöön
4. Tallennetut signaalit ja työnkulun odotuksen riippuvuusrivit toistetaan historiallisena tilana
5. Jos alkuperäinen työnkulku oli edelleen `running`, nykyinen vaihe lisätään käsiteltäväksi. Repeat- ja `start_workflows()`-vaiheita ei lisätä uudelleen jonoon, joten jos toisto pysähtyy niihin, työnkulku jää tilaan `running` ilman työtä ([#17](https://github.com/inline0/queuety/issues/17))
6. Jos alkuperäisen työnkulun tila oli `waiting_for_signal`, `waiting_for_workflows`, `paused`, `failed`, `cancelled` tai `completed`, sama tila säilyy toistetussa työnkulussa

Toistettu työnkulku saa uuden tunnuksen ja toimii itsenäisesti. Se ei vaikuta alkuperäiseen.

`waiting_for_workflows`-toistoissa viedyt riippuvuusrivit luodaan uudelleen samoilla työnkulkujen tunnuksilla. Tämä on hyödyllistä auditointiin ja ympäristöissä, joissa kyseiset riippuvuustyönkulut ovat myös olemassa, mutta riippuvuustunnuksia ei yhdistetä automaattisesti ympäristöjen välillä.

## Käyttötapaukset

### Tuotantovirheiden toistaminen

Vie epäonnistunut työnkulku tuotantoympäristöstä ja toista se paikallisesti:

```bash
# On production
wp queuety workflow export 42 --output=/tmp/workflow-42.json

# Copy the file to your local environment

# On local
wp queuety workflow replay /tmp/workflow-42.json
```

Toistetulla työnkululla on täsmälleen sama tila ja samat vaihemääritelmät. Käynnissä olevissa työnkuluissa nykyinen vaihe lisätään uudelleen jonoon, jotta suoritusta voi jatkaa siitä, mihin se jäi. Keskeytetyt tai odottavat työnkulut luodaan tarkastelua varten uudelleen samaan estettyyn tilaan.

### Työnkulkujen siirtäminen ympäristöjen välillä

Siirrä työnkulku testiympäristöstä tuotantoon tai päinvastoin viemällä ja toistamalla se:

```bash
# On staging
wp queuety workflow export 15 --output=workflow.json

# On production
wp queuety workflow replay workflow.json
```

### Auditointi ja arkistointi

Vie valmistuneet työnkulut pitkäaikaista säilytystä tai vaatimustenmukaisuutta varten. JSON-tiedosto sisältää koko suoritushistorian, myös syötteet, tulosteet, tilan ennen ja jälkeen, ajoitustiedot ja virheiden tiedot.

```php
$data = Queuety::export_workflow( $workflow_id );
// Store $data in your archive system, S3, etc.
```