## Fluxos de trabalho em um único arquivo

Um fluxo de trabalho pode ser totalmente independente em um único arquivo PHP. Defina as classes das etapas e o builder juntos, coloque o arquivo em um diretório e carregue esse diretório com `Queuety::load_workflows()` (mostrado abaixo). Queuety não examina nenhum diretório por conta própria.

```php
// workflows/onboard-user.php
use Queuety\Queuety;

class CreateAccount implements \Queuety\Step {
    public function handle(array $state): array {
        $user = create_user($state['email']);
        return ['user_id' => $user->id, 'user_name' => $user->name];
    }
    public function config(): array {
        return ['max_attempts' => 3];
    }
}

class SendWelcome implements \Queuety\Step {
    public function handle(array $state): array {
        wp_mail($state['email'], 'Welcome ' . $state['user_name'], '...');
        return ['welcomed' => true];
    }
    public function config(): array {
        return [];
    }
}

return Queuety::define_workflow('onboard_user')
    ->then(CreateAccount::class, 'create_account')
    ->then(SendWelcome::class, 'send_welcome');
```

O arquivo retorna um `WorkflowBuilder`. Cada classe de etapa é definida no próprio arquivo. Quando o arquivo é carregado, as classes ficam disponíveis e o fluxo de trabalho é registrado como um modelo.

## Carregar fluxos de trabalho

Carregue todos os arquivos de fluxo de trabalho de um diretório:

```php
// Load all .php files from the workflows directory
$count = Queuety::load_workflows(__DIR__ . '/workflows/');
```

Ou carregue um único arquivo:

```php
$template = Queuety::load_workflow_file(__DIR__ . '/workflows/onboard-user.php');
```

Depois, despache pelo nome:

```php
$workflow_id = Queuety::run_workflow('onboard_user', ['email' => 'user@example.com']);
```

## Carregamento recursivo

Passe `true` como segundo argumento para examinar subdiretórios:

```php
Queuety::load_workflows(__DIR__ . '/workflows/', recursive: true);
```

Isso permite organizar fluxos de trabalho em pastas:

```
workflows/
├── onboarding/
│   ├── new-user.php
│   └── trial-upgrade.php
├── reports/
│   ├── daily-summary.php
│   └── weekly-digest.php
└── notifications/
    └── digest-email.php
```

## Usar todos os recursos dos fluxos de trabalho

Os fluxos de trabalho em arquivos oferecem suporte a tudo o que o builder oferece, exceto `idempotency_key()`, que não é armazenado no modelo; passe-o por despacho com `Queuety::run_workflow( $name, $payload, [ 'idempotency_key' => '...' ] )`. Atrasos, sinais, etapas paralelas, ramificações condicionais, execução de fluxos de trabalho, manipuladores de cancelamento e redução do estado funcionam:

```php
// workflows/approval-flow.php
use Queuety\Queuety;

class SubmitRequest implements \Queuety\Step {
    public function handle(array $state): array {
        return ['submitted_at' => date('Y-m-d H:i:s')];
    }
    public function config(): array { return []; }
}

class ProcessApproval implements \Queuety\Step {
    public function handle(array $state): array {
        return [
            'approved_by' => $state['approved_by'],
            'processed' => true,
        ];
    }
    public function config(): array { return []; }
}

class CleanupRequest implements \Queuety\Handler {
    public function handle(array $payload): void {
        delete_pending_request($payload['request_id']);
    }
    public function config(): array { return []; }
}

return Queuety::define_workflow('approval_flow')
    ->then(SubmitRequest::class)
    ->delay(hours: 24)
    ->wait_for_signal('approved')
    ->then(ProcessApproval::class)
    ->on_cancel(CleanupRequest::class)
    ->prune_state_after(2);
```

## Quando usar fluxos de trabalho em arquivos

Os fluxos de trabalho em arquivos são ideais quando:

- Um LLM ou gerador de código cria fluxos de trabalho de forma programática
- Um fluxo de trabalho é simples o suficiente para caber em um arquivo
- Você quer manter a lógica das etapas perto da definição do fluxo de trabalho
- Você está prototipando e quer iterar rapidamente

Para fluxos de trabalho maiores, com classes de etapa compartilhadas, middleware complexo ou etapas reutilizadas em vários fluxos de trabalho, a abordagem padrão de arquivos de classe separados com carregamento automático PSR-4 é mais fácil de manter.

## Como funciona

Nos bastidores, os fluxos de trabalho em arquivos usam exatamente o mesmo mecanismo do builder API. Cada etapa é um trabalho separado no banco de dados. O estado flui pela tabela `queuety_workflows`. Não há reprodução, requisito de determinismo nem diferença de desempenho.

Cada chamada de carregamento `require` o arquivo (não `require_once`); portanto, carregue cada arquivo uma vez por solicitação. Carregá-lo duas vezes declara as classes novamente e causa uma falha. O `WorkflowBuilder` retornado é convertido em um `WorkflowTemplate` e armazenado no `WorkflowRegistry`. O despacho e a execução são iguais aos de qualquer outro fluxo de trabalho.