Unique Jobs

O sistema de Queue do MUCRM possui suporte nativo para Jobs únicos (Unique Jobs). Isso impede que o mesmo Job seja adicionado múltiplas vezes na fila simultaneamente.

Como Funciona

Quando um Job possui assinatura única (signature), o sistema impede duplicações automáticas no banco. Isso é extremamente útil para:

• Resets
• Premiações
• Eventos automáticos
• Tarefas críticas
• Schedulers
• Sincronizações

Problema Sem Unique

cron executa 2x
    ↓
2 jobs iguais entram na fila
    ↓
premiação duplicada

Com Unique

cron executa 2x
    ↓
primeiro job entra
    ↓
segundo job é ignorado

Funcionamento Interno

O MUCRM gera automaticamente uma assinatura baseada em:

classe do job + horário atual

Exemplo Real

<?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();
    }
}

Mesmo que o Scheduler rode múltiplas vezes: somente 1 reset será adicionado na fila.

Quando Utilizar

Ideal para:

• Reset semanal
• Reset diário
• Premiações automáticas
• Eventos globais
• Sincronizações
• Backups automáticos
• Limpeza automática
• Processamento crítico

Quando NÃO Utilizar

Exemplo Errado

SendRecoveryEmail::dispatch([
    'email' => 'player@gmail.com'
]);

Se emails fossem únicos: apenas 1 jogador receberia email.

Scheduler e Unique

Todos os Jobs agendados (schedule()) já funcionam perfeitamente com proteção de duplicação.

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

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

Resultado: premiação executada apenas 1 vez.

Benefícios

• Evita duplicações
• Evita premiações duplas
• Evita múltiplos resets
• Evita concorrência
• Aumenta segurança
• Reduz bugs críticos

Fluxo Interno

scheduler detecta job
        ↓
gera assinatura
        ↓
job já existe?
 ├── SIM → ignora
 └── NÃO → adiciona na fila

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 resetado com sucesso'
        );
    }
}

Boas Práticas

• Utilize Unique Jobs apenas em tarefas globais
• Evite unique em ações por usuário
• Utilize logs para auditoria
• Utilize retries com cautela
• Monitore failed jobs
• Mantenha schedulers idempotentes

Resumo

Unique Jobs evitam execuções duplicadas de tarefas críticas dentro do sistema.