# Exportação e reprodução de fluxos de trabalho

Queuety pode exportar o histórico completo de execução de um fluxo de trabalho em um formato portátil JSON e reproduzi-lo em outro ambiente. Isso é útil para reproduzir localmente bugs de produção, migrar fluxos de trabalho entre ambientes e fazer auditorias.

## Exportar um fluxo de trabalho

### PHP API

Chame `Queuety::export_workflow()` com o ID do fluxo de trabalho. Ele retorna um array serializável em JSON:

```php
use Queuety\Queuety;

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

Para obter diretamente uma string 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>]
```

| Opção | Descrição |
|---|---|
| `<id>` | ID do fluxo de trabalho (obrigatório) |
| `--output=<file>` | Caminho do arquivo onde gravar o JSON. O padrão é stdout. |

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

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

## Reproduzir um fluxo de trabalho

### PHP API

Chame `Queuety::replay_workflow()` com os dados da exportação. Ele retorna o novo ID do fluxo de trabalho:

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

| Opção | Descrição |
|---|---|
| `<file>` | Caminho para o arquivo JSON exportado (obrigatório) |

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

## Estrutura de JSON

A exportação contém o estado completo do fluxo de trabalho, os trabalhos associados, eventos de rastreamento, entradas de registro, sinais armazenados, artefatos, blocos e quaisquer linhas de espera por dependências do fluxo de trabalho:

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

Alguns campos estão abreviados no exemplo acima. A exportação real inclui todas as colunas de rastreamento de cada linha de evento.

As exportações de fluxos de trabalho também preservam metadados, como `definition_version`, `definition_hash` e `idempotency_key`, quando definidos na execução original.

## Como funciona a reprodução

Ao reproduzir um fluxo de trabalho exportado:

1. Uma nova linha de fluxo de trabalho é criada com o estado exportado e as definições das etapas
2. O nome do novo fluxo de trabalho é `{original_name}_replay_{timestamp}`
3. Os eventos e registros históricos do fluxo de trabalho são reinseridos no novo ambiente
4. Os sinais armazenados e as linhas de dependências de espera do fluxo de trabalho são reproduzidos como estado histórico
5. Se o fluxo de trabalho original ainda estiver `running`, a etapa atual será enfileirada para processamento. As etapas Repeat e `start_workflows()` não são enfileiradas novamente; portanto, uma reprodução que pare em uma delas permanece `running` sem um trabalho ([#17](https://github.com/inline0/queuety/issues/17))
6. Se o fluxo de trabalho original estiver `waiting_for_signal`, `waiting_for_workflows`, `paused`, `failed`, `cancelled` ou `completed`, esse status será preservado no fluxo de trabalho reproduzido

O fluxo de trabalho reproduzido recebe um novo ID e funciona de forma independente. Ele não afeta o original.

Para reproduções `waiting_for_workflows`, as linhas de dependência exportadas são recriadas com os mesmos IDs de fluxo de trabalho. Isso é útil para auditorias e para ambientes onde esses fluxos de trabalho dependentes também existem, mas não remapeia automaticamente os IDs de dependência entre ambientes.

## Casos de uso

### Reproduzir bugs de produção

Exporte um fluxo de trabalho com falha da produção e reproduza-o localmente:

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

O fluxo de trabalho reproduzido tem exatamente o mesmo estado e as mesmas definições de etapas. Os fluxos de trabalho em execução enfileiram novamente a etapa atual, para que você possa continuar a execução de onde pararam; os fluxos de trabalho pausados ou em espera são recriados nesse estado bloqueado para inspeção.

### Migrar fluxos de trabalho entre ambientes

Mova um fluxo de trabalho de staging para produção (ou vice-versa) exportando-o e reproduzindo-o:

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

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

### Auditoria e arquivamento

Exporte fluxos de trabalho concluídos para armazenamento de longo prazo ou conformidade. O arquivo JSON contém o histórico completo de execução, incluindo entradas, saídas, estado antes e depois, dados de tempo e detalhes de erros.

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