Scheduler

O Scheduler do MUCRM permite executar Jobs automaticamente em horários específicos utilizando expressões cron. Toda configuração é feita diretamente dentro do próprio Job.

Como Funciona

O Scheduler verifica todos os Jobs do sistema e adiciona automaticamente na fila aqueles que devem ser executados no momento atual.

cron:run
    ↓
scheduler verifica jobs
    ↓
cron expression bate?
 ├── NÃO → ignora
 └── SIM → adiciona na fila
                    ↓
                jobs:run
                    ↓
              worker executa

Criando um Scheduler

Basta adicionar o método schedule() dentro do Job:

<?php

namespace MUCRM\shared\jobs;

use MUCRM\engine\queue\job;

class weekly_ranking_reset extends job
{
    public function schedule(): string
    {
        return '@weekly';
    }

    public function handle(): void
    {
        Ranking::truncate();
    }
}

Todo domingo à meia-noite o ranking será resetado automaticamente.

Jobs Normais

Jobs sem método schedule() não são executados automaticamente. Eles funcionam apenas via dispatch():

class SendRecoveryEmail extends Job
{
    public function handle(): void
    {
        mailer::send(...);
    }
}

Expressões Cron

O Scheduler utiliza formato cron tradicional:

return '@everyMinute';

return '@everyFiveMinutes';

return '@everyTenMinutes';

return '@hourly';

return '@daily';

return '@weekly';

return '0 21 * * 6';

Exemplo Real

<?php

namespace MUCRM\shared\jobs;

use MUCRM\engine\queue\job;
use MUCRM\engine\support\log;

class CastleSiegeReward extends Job
{
    public function schedule(): string
    {
        return '0 21 * * 6';
    }

    public function handle(): void
    {
        Guild::rewardOwner();

        log::info(
            'Premiação do Castle Siege entregue'
        );
    }
}

Todo sábado às 21:00 a guild vencedora receberá premiação automática.

Scheduler e Queue

O Scheduler NÃO executa Jobs diretamente. Ele apenas adiciona jobs na fila. Quem executa os Jobs é o jobs:run.

Evitando Jobs Duplicados

O MUCRM possui sistema interno de assinatura (signature) para impedir duplicações automáticas em Jobs agendados. Isso evita:

• Premiações duplicadas
• Resets duplicados
• Eventos repetidos
• Múltiplas execuções simultâneas

Comandos

Processar Scheduler

php mucrm cron:run

Processar Queue

php mucrm jobs:run

Configuração na Hospedagem

O ideal é executar cron:run a cada 1 minuto no Cron da hospedagem:

* * * * * php /home/site/mucrm cron:run

E manter jobs:run em execução contínua no servidor:

php mucrm jobs:run

Boas Práticas

• Utilize Scheduler apenas para tarefas automáticas
• Evite Jobs pesados em horários críticos
• Utilize logs para auditoria
• Utilize retries em tarefas externas
• Monitore failed jobs
• Mantenha o worker sempre online

Exemplos de Uso

Ideal para:

• Reset de rankings
• Premiações automáticas
• Eventos semanais
• Limpeza de logs
• Backups automáticos
• Envio de relatórios
• Sincronizações
• Verificações periódicas
• Manutenção automática

Exemplo Completo

<?php

namespace MUCRM\shared\jobs;

use MUCRM\engine\queue\job;
use MUCRM\engine\support\log;

class WeeklyTopReset extends Job
{
    public function schedule(): string
    {
        return '@weekly';
    }

    public function handle(): void
    {
        Ranking::truncate();

        log::info(
            'Ranking semanal resetado'
        );
    }
}