# Ekspor dan Replay Alur Kerja

Queuety dapat mengekspor seluruh riwayat eksekusi alur kerja ke format JSON portabel dan me-replay-nya di lingkungan lain. Ini berguna untuk mereproduksi bug produksi secara lokal, memigrasikan alur kerja antarlingkungan, dan melakukan audit.

## Mengekspor alur kerja

### PHP API

Panggil `Queuety::export_workflow()` dengan ID alur kerja. Fungsi ini mengembalikan array yang dapat diserialisasi sebagai JSON:

```php
use Queuety\Queuety;

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

Untuk mendapatkan string JSON secara langsung:

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

| Opsi | Deskripsi |
|---|---|
| `<id>` | ID workflow (wajib) |
| `--output=<file>` | Jalur file untuk menulis JSON. Default-nya stdout. |

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

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

## Me-replay alur kerja

### PHP API

Panggil `Queuety::replay_workflow()` dengan data ekspor. Fungsi ini mengembalikan ID alur kerja baru:

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

| Opsi | Deskripsi |
|---|---|
| `<file>` | Jalur ke file JSON yang diekspor (wajib) |

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

## Struktur JSON

Ekspor mencakup seluruh status alur kerja, tugas terkait, peristiwa jejak, entri log, sinyal tersimpan, artefak, potongan, dan baris tunggu dependensi alur kerja apa pun:

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

Beberapa kolom disingkat pada contoh di atas. Ekspor sebenarnya menyertakan semua kolom jejak dari setiap baris peristiwa.

Ekspor alur kerja juga mempertahankan metadata alur kerja seperti `definition_version`, `definition_hash`, dan `idempotency_key` jika metadata tersebut ditetapkan pada proses awal.

## Cara kerja replay

Saat Anda me-replay alur kerja yang diekspor:

1. Baris alur kerja baru dibuat dengan status dan definisi langkah yang diekspor
2. Nama alur kerja baru adalah `{original_name}_replay_{timestamp}`
3. Peristiwa dan log alur kerja historis dimasukkan kembali ke lingkungan baru
4. Sinyal tersimpan dan baris dependensi workflow-wait diputar ulang sebagai status historis
5. Jika alur kerja awal masih `running`, langkah saat ini dimasukkan ke antrean untuk diproses. Langkah Repeat dan `start_workflows()` tidak dimasukkan kembali ke antrean, jadi replay yang berhenti pada salah satunya tetap `running` tanpa tugas ([#17](https://github.com/inline0/queuety/issues/17))
6. Jika status alur kerja awal adalah `waiting_for_signal`, `waiting_for_workflows`, `paused`, `failed`, `cancelled`, atau `completed`, status tersebut dipertahankan pada alur kerja hasil replay

Alur kerja hasil replay mendapat ID baru dan berjalan secara independen. Alur kerja ini tidak memengaruhi yang asli.

Untuk replay `waiting_for_workflows`, baris dependensi yang diekspor dibuat ulang dengan ID alur kerja yang sama. Ini berguna untuk audit dan lingkungan tempat alur kerja dependensi tersebut juga tersedia, tetapi ID dependensi tidak dipetakan ulang secara otomatis antarlingkungan.

## Kasus penggunaan

### Mereproduksi bug produksi

Ekspor alur kerja yang gagal dari produksi, lalu replay secara lokal:

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

Alur kerja hasil replay memiliki status dan definisi langkah yang persis sama. Alur kerja yang berjalan memasukkan kembali langkah saat ini ke antrean sehingga Anda dapat melanjutkan eksekusi dari titik berhenti. Alur kerja yang dijeda atau menunggu dibuat ulang dalam status tertahan tersebut untuk diperiksa.

### Memigrasikan alur kerja antarlingkungan

Pindahkan alur kerja dari staging ke produksi (atau sebaliknya) dengan mengekspor dan me-replay-nya:

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

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

### Audit dan pengarsipan

Ekspor alur kerja yang selesai untuk penyimpanan jangka panjang atau kepatuhan. File JSON berisi seluruh riwayat eksekusi, termasuk input, output, status sebelum/sesudah, data waktu, dan detail error.

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