# Töövoo eksport ja taasesitus

Queuety saab eksportida töövoo täieliku käitusajaloo teisaldatavas JSON-vormingus ja taasesitada selle teises keskkonnas. See on kasulik tootmiskeskkonna vigade kohalikuks taasesitamiseks, töövoogude keskkondade vahel migreerimiseks ja auditeerimiseks.

## Töövoo eksportimine

### PHP API

Kutsu `Queuety::export_workflow()` välja töövoo ID-ga. See tagastab JSON-vormingusse teisendatava massiivi:

```php
use Queuety\Queuety;

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

Et saada otse JSON-string:

```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>]
```

| Suvand | Kirjeldus |
|---|---|
| `<id>` | Töövoo ID (nõutav) |
| `--output=<file>` | Failitee, kuhu kirjutada väärtus JSON. Vaikimisi standardväljundisse. |

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

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

## Töövoo taasesitamine

### PHP API

Kutsu `Queuety::replay_workflow()` välja ekspordiandmetega. See tagastab uue töövoo ID:

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

| Suvand | Kirjeldus |
|---|---|
| `<file>` | Eksporditud JSON faili tee (nõutav) |

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

## Struktuur JSON

Eksport sisaldab töövoo täielikku olekut, seotud töid, jäljesündmusi, logikirjeid, salvestatud signaale, artefakte, tükke ja kõiki töövoogude sõltuvuste ooteandmeid:

```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"
}
```

Mõned väljad on ülaltoodud näites lühendatud. Tegelik eksport sisaldab kõiki jäljeveerge igast sündmuse reast.

Töövoo ekspordid säilitavad ka töövoo metaandmed, näiteks `definition_version`, `definition_hash` ja `idempotency_key`, kui need olid algsel käivitusel määratud.

## Kuidas taasesitus toimib

Eksporditud töövoo taasesitamisel:

1. Luuakse uus töövoo rida eksporditud oleku ja sammusätetega
2. Uue töövoo nimi on `{original_name}_replay_{timestamp}`
3. Ajaloolised töövoosündmused ja logid lisatakse uude keskkonda uuesti
4. Salvestatud signaalid ja töövoo ootamise sõltuvusread taasesitatakse ajaloolise olekuna
5. Kui algne töövoog oli endiselt olekus `running`, lisatakse praegune samm töötlemiseks järjekorda. Kordus- ja `start_workflows()`-samme uuesti järjekorda ei lisata, seega jääb ühel neist peatuv taasesitus olekusse `running` ilma tööta ([#17](https://github.com/inline0/queuety/issues/17))
6. Kui algse töövoo olek oli `waiting_for_signal`, `waiting_for_workflows`, `paused`, `failed`, `cancelled` või `completed`, säilitatakse see olek taasesitatud töövoos

Taasesitatud töövoog saab uue ID ja töötab algsest sõltumatult. See ei mõjuta algset töövoogu.

`waiting_for_workflows` taasesituste korral luuakse eksporditud sõltuvusread uuesti samade töövoo ID-dega. See on kasulik auditeerimiseks ja keskkondades, kus need sõltuvustöövood on samuti olemas, kuid sõltuvuste ID-sid ei vastendata automaatselt eri keskkondade vahel.

## Kasutusjuhud

### Tootmiskeskkonna vigade taasesitamine

Ekspordi tootmiskeskkonnast nurjunud töövoog ja taasesita see kohalikult:

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

Taasesitatud töövoos on täpselt sama olek ja sammusätted. Töötavad töövood lisavad praeguse sammu uuesti järjekorda, et saaksid täitmist jätkata katkestuskohast, peatatud või ootel töövood luuakse aga kontrollimiseks uuesti samasse blokeeritud olekusse.

### Töövoogude migreerimine keskkondade vahel

Töövoo saab viia testkeskkonnast tootmiskeskkonda (või vastupidi), eksportides ja taasesitades selle:

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

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

### Auditeerimine ja arhiveerimine

Ekspordi lõpetatud töövood pikaajaliseks säilitamiseks või nõuetele vastavuse tagamiseks. JSON-fail sisaldab täielikku käitusajalugu, sealhulgas sisendeid, väljundeid, olekut enne ja pärast, ajastuse andmeid ning tõrgete üksikasju.

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