# Trabalho em segundo plano

Eventos de recursos, a fila de jobs e tarefas agendadas.

O trabalho que não deve atrasar uma requisição de página roda em segundo plano: e-mails de confirmação, importações, chamadas a outros sistemas, relatórios noturnos. O Nimbly tem três partes para isso: eventos de recursos, uma fila de jobs e um agendador.

## Eventos de recursos

Um recurso declara o que acontece depois que um registro é criado, alterado ou excluído:

```json
"events": {
  "create": ["job:lead-created"],
  "update": ["lead-updated"]
}
```

- Um nome simples executa uma função logo depois da gravação. `lead-updated` chama `lead_updated($event)` de `lib/lead-updated.php` num módulo.
- Uma entrada `job:` coloca um job na fila em vez disso, para que a requisição termine na hora e o trabalho aconteça um instante depois.

O evento traz a ação, o recurso, o UUID do registro e os dados dele.

## Jobs

Um job na fila é tratado por uma função com o nome do seu tipo, no `lib/` de um módulo:

```php
<?php
// ext/modules/leads/lib/lead-created.php

function lead_created_job($job)
{
    $lead = $job['payload']['data'] ?? [];
    load_library('email');
    load_library('env');
    set_variable('lead', $lead);
    $sent = email([
        'service' => env('MAIL_SERVICE', 'resend'),
        'from' => env('MAIL_FROM'),
        'from_name' => env('MAIL_FROM_NAME'),
        'recipient' => $lead['email'],
        'subject' => 'Thank you for your message',
        'tpl' => 'email-lead-thanks',
    ]);
    if (!$sent) {
        throw new Exception('Confirmation email not sent');
    }
    return true;
}
```

Um job que lança um erro é tentado de novo, por padrão até cinco vezes. Um job que falha de vez é marcado como falho, aparece no admin e é informado por e-mail a `SYSTEM_ALERT_EMAIL`. Coloque um job na fila a partir do seu próprio código com `job_enqueue('report-build', ['month' => '2026-10'])`.

A fila guarda o que fazer e os dados, nunca comandos. `/nb-admin/jobs` mostra os jobs na fila, em execução, concluídos e falhos, com o último erro de cada um.

## O agendador

O agendador roda a cada minuto. Ele sempre executa a manutenção do framework: a fila de jobs, a limpeza de sessões, de jobs antigos e de histórico antigo, e o resumo das estatísticas a cada hora. Um projeto acrescenta suas próprias tarefas em `ext/cli/schedule.inc`, ou por ambiente em `schedule.prod.inc` e `schedule.stage.inc`:

```php
<?php
return [
    ['id' => 'report-nightly', 'command' => 'report:build', 'daily_at' => '02:00', 'timezone' => 'Europe/Amsterdam'],
    ['id' => 'rates-refresh', 'command' => 'rates:refresh', 'every_minutes' => 15],
];
```

O `./nimbly schedule:init` cria esses arquivos. Os comandos próprios são registrados em `ext/cli/commands.php`.

Num contêiner, o agendador inicia sozinho. Num servidor próprio, ele é instalado uma vez por servidor; veja [Jobs e o agendador](/pt/docs/operate/jobs/). O `./nimbly schedule:status` informa se cada tarefa rodou no horário.