# ワークフローのエクスポートとリプレイ

Queuetyを使うと、ワークフローの完全な実行履歴を移植可能なJSON形式でエクスポートし、別の環境でリプレイできます。本番環境のバグをローカルで再現したり、環境間でワークフローを移行したり、監査したりするのに役立ちます。

## ワークフローのエクスポート

### PHP API

ワークフローIDを指定して`Queuety::export_workflow()`を呼び出します。JSONにシリアライズ可能な配列が返されます:

```php
use Queuety\Queuety;

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

JSON文字列を直接取得するには:

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

| オプション | 説明 |
|---|---|
| `<id>` | ワークフローID（必須） |
| `--output=<file>` | JSONを書き込むファイルパス。既定では標準出力に出力します |

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

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

## ワークフローのリプレイ

### PHP API

エクスポートデータを指定して`Queuety::replay_workflow()`を呼び出します。新しいワークフロー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>
```

| オプション | 説明 |
|---|---|
| `<file>` | エクスポートしたJSONファイルのパス（必須） |

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

## JSONの構造

エクスポートには、ワークフローの全状態、関連ジョブ、トレースイベント、ログエントリー、保存済みシグナル、アーティファクト、チャンク、ワークフロー依存関係の待機行がすべて含まれます:

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

上の例では一部のフィールドを省略しています。実際のエクスポートには、各イベント行のすべてのトレース列が含まれます。

ワークフローのエクスポートでは、元の実行時に設定されていた`definition_version`、`definition_hash`、`idempotency_key`などのワークフローメタデータも保持されます。

## リプレイの仕組み

エクスポートしたワークフローをリプレイすると、次の処理が行われます:

1. エクスポートされた状態とステップ定義を使って、新しいワークフロー行が作成されます
2. 新しいワークフローの名前は`{original_name}_replay_{timestamp}`です
3. 過去のワークフローイベントとログが新しい環境に再挿入されます
4. 保存済みシグナルとワークフロー待機の依存行が、過去の状態としてリプレイされます
5. 元のワークフローがまだ`running`だった場合、現在のステップが処理用にキューへ登録されます。Repeatステップと`start_workflows()`ステップは再登録されないため、そのいずれかで停止するリプレイはジョブがないまま`running`の状態になります（[#17](https://github.com/inline0/queuety/issues/17)）
6. 元のワークフローが`waiting_for_signal`、`waiting_for_workflows`、`paused`、`failed`、`cancelled`、または`completed`だった場合、そのステータスはリプレイしたワークフローにも引き継がれます

リプレイしたワークフローには新しいIDが割り当てられ、元のワークフローとは独立して動作します。元のワークフローには影響しません。

`waiting_for_workflows`のリプレイでは、エクスポートされた依存行が同じワークフローIDで再作成されます。監査や、依存ワークフローも存在する環境では便利ですが、環境間で依存IDが自動的に割り当て直されることはありません。

## 活用例

### 本番環境のバグを再現する

本番環境で失敗したワークフローをエクスポートし、ローカルでリプレイします:

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

リプレイしたワークフローは、元とまったく同じ状態およびステップ定義を持ちます。実行中のワークフローでは現在のステップが再キューイングされ、中断した地点から実行を続けられます。一時停止中または待機中のワークフローは、確認できるようにその停止状態で再作成されます。

### 環境間でワークフローを移行する

エクスポートとリプレイを使って、ワークフローをステージング環境から本番環境へ（またはその逆へ）移動します:

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

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

### 監査とアーカイブ

長期保存やコンプライアンス対応のために、完了したワークフローをエクスポートします。JSONファイルには、入力、出力、実行前後の状態、タイミングデータ、エラーの詳細を含む完全な実行履歴が保存されます。

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