Guia Completo do Sistema de Scheduler

Este documento fornece um overview técnico detalhado sobre o funcionamento doScheduler, cobrindo gatilhos, estados de execução, orquestração e configurações.

1. Visão Geral

OScheduleré o motor de agendamento do framework, atuando como uma fachada (Facade) para gerenciar tarefas em segundo plano (Jobs). Ele coordena o motor Quartz, gerencia contextos multi-tenant e mantém a sincronização de estado em cluster.

2. Alta Disponibilidade (HA) e Failover

O sistema foi projetado para operar em ambientes críticos onde a falha de um servidor não deve interromper as tarefas agendadas.

Como funciona o Failover?

O mecanismo deFailover(contingência) transfere automaticamente as tarefas de um servidor que falhou para outro saudável:

1.Monitoramento (Ping):Todas as instâncias ativas do RuB atualizam um sinal de vida ("ping") no banco de dados regularmente (a cada minuto). 2.Detecção de Queda:Se um executor parar de responder (não atualizar o ping) por mais de2 minutos, o orquestrador o marca automaticamente comoOffline. 3.**Redirecionamento Automático:**Quando um Job precisa ser executado, o agendador verifica sua lista de Tags associadas. Se o servidor dono da primeira Tag estiver Offline, o sistema tenta a segunda Tag, e assim por diante. 4.**Recuperação:**Assim que o servidor original volta a ficar Online e atualiza seu ping, ele retoma automaticamente a responsabilidade pelas suas tarefas na próxima execução agendada.

Executor Primário e Conceito de "Catch-All"

OExecutor Primárioé uma função vital no cluster, atuando como o responsável por todas as tarefas que não possuem um destino específico.

*O que é Catch-All?É o comportamento de "apanha-tudo". Se um Job ou Gatilho (Trigger) não tiver nenhumaTag associada, ele será ignorado por executores comuns. Apenas o executor marcado comoPrimárioprocessará essas tarefas "sem etiqueta". *Auto-Reatribuição do Primário: * O sistema garante que sempre exista um (e apenas um) executor primário ativo por empresa. * Se o executor primário atual ficarOffline(mais de 2 minutos sem sinal de vida), o próximo executor saudável que realizar o monitoramento iráse promover automaticamentea novo Primário. * Isso garante que as tarefas globais ou sem tags nunca parem de rodar, mesmo que o servidor principal sofra uma queda.

O que são Executores e Tags?

Para o gerenciamento da carga e redundância, o sistema utiliza dois conceitos fundamentais:

***Executores (Instâncias do RuB):**Cada servidor onde o RuB está rodando é um executor potencial. *Identificação Única (UUID):Cada executor deve ter um identificador único universal (UUID) fixo configurado no config.ini. Isso éCRÍTICOem HA para que o servidor não perca sua identidade ao reiniciar. ***Executor Primário (Catch-All):**Através da interface, um executor pode ser definido como Primário. *Tags (Afinidade):São etiquetas que vinculam tarefas a servidores específicos. *Vínculo Tag-Executor:Cada Tag pertence aexactly unExecutor. *Vínculo Job-Tag:Um Job pode tervárias Tags. Aordemdas tags no Job define a prioridade de execução (quem é o principal e quem são os reservas).

📢Importante

Para quem NÃO utiliza Alta Disponibilidade: Em ambientes de servidor único, as configurações deExecutoreseTagsnão ficam disponíveis para edição. Nestes casos, o destaque é que o sistema utiliza automaticamente osContextosdo RuB como Tags de afinidade. Isso garante que o agendador funcione de forma transparente e idêntica às versões anteriores.

3. Gatilhos (Triggers)

AsTriggersdefinem a regra de disparo ("Quando o trabalho deve ser executado?"). Elas utilizam expressõesCron para determinar os horários exatos de ativação.

Estados do Gatilho (TriggerStatus)

4. Estados de Execução (ExecutionStatus)

OExecutionStatusdetalha o ciclo de vida de uma instância específica de execução do Job.

Fluxo de Estados de Execução

graph TD
    Start([Disparo da Trigger]) --> Preparing[<b>PREPARING</b><br/>Preparando]
    Preparing --> Check{Validações}
    Check -- "Semáforo Cheio" --> RedSem["<b>ABORTED_RED_SEMAPHORE</b><br/>Semáforo Vermelho"]
    Check -- "Concorrência" --> ParAbort["<b>PARALLEL_ABORTED</b><br/>Paralelo"]
    Check -- "Skip / Timeout" --> Skip["<b>SKIPPED</b><br/>Pulado"]
    Check -- "JobInfo Ausente" --> NoInfo["<b>NO_JOBINFO</b><br/>Sem Metadados"]
    
    Check -- "Liberado" --> Running["<b>RUNNING</b><br/>Em Execução"]
    
    Running --> End{Resultado}
    End -- "Sucesso" --> Success["<b>SUCCESS</b><br/>Sucesso"]
    End -- "Erro" --> Fail["<b>FAIL</b><br/>Falha"]
    End -- "Interrupção" --> Int["<b>INTERRUPTED</b><br/>Interrompido"]
    End -- "Crash do Servidor" --> Lost["<b>UNABLE_TO_DETERMINE</b><br/>Indeterminado"]

    style Preparing fill:#f9f,stroke:#333
    style Running fill:#2196F3,stroke:#fff,color:#fff
    style Success fill:#4CAF50,stroke:#333,color:#fff
    style Fail fill:#F44336,stroke:#fff,color:#fff

5. Auditoria vs. Execução Real

No registro de Histórico, há uma distinção técnica fundamental que o usuário deve compreender:

*Registro de "Preparando" (PREPARING): É um registro deauditoria. Ele prova que o Scheduler "tentou" disparar o Job no horário correto. Mesmo que o Job seja bloqueado por um semáforo, o histórico registrará a tentativa e o motivo do bloqueio. *Registro de "Início" (RUNNING): Indica que o Job passou por todas as validações e o código Java começou a ser executado. Aduração realdo Job no histórico é contabilizada apenas a partir deste ponto.

6. Orquestração e Sincronização

A Orquestração garante que múltiplos servidores (Executores) operem de forma harmônica em um Cluster, alinhando as tags de afinidade e agendamentos automaticamente.

*Sincronização Automática: O sistema consulta o Orquestrador global automaticamente em um intervalo configurável ( padrão de15 segundos). *Funcionamento: O executor comunica seu ID, recebe asTags de Afinidadeatuais, remove gatilhos órfãos e atualiza agendamentos dinamicamente.

Fluxo de Orquestração

graph LR
    Timer([Intervalo Configurável]) --> Fetch[Consulta Orquestrador]
    Fetch --> Tags[Sincroniza Tags de Afinidade]
    Tags --> Cleanup[Remove Triggers Órfãs]
    Cleanup --> Update[Registra/Atualiza Triggers]
    Update --> Timer
    
    style Timer fill:#e1f5fe,stroke:#01579b

7. Configurações (config.ini)

Principais chaves de configuração do Scheduler (prefixo interno: com.gicbrasil.framework.):

8. Configuração no Programa Agenda de Execuções

Em ambientes configurados paraAlta Disponibilidade, utilize os menus do programaAgenda de Execuçõespara operacionalizar a orquestração. Caso contrário, estas opções estarão indisponíveis.

Passo 1: Identificar os Executores

No menuExecutores, você verá a lista de instâncias conectadas. Clique em editar para dar uma descrição amigável ( ex: "Servidor de Integração").

*Executor Primário (Catch-All):Nesta tela, você pode definir um executor comoPrimário. O executor primário atua como um "apanha-tudo" (catch-all), aceitando processar qualquer Job que não tenha uma Tag específica ou que não encontre seu executor preferencial disponível. ***Identificação:**Certifique-se de que o UUID exibido condiz com o configurado no config.ini.

Passo 2: Criar e Vincular Tags

No menuTags, crie etiquetas para as especialidades dos seus servidores (ex: INTEGRACOES, RELATORIOS). Vincule cada Tag a um Executor específico.

Passo 3: Associar Jobs às Tags

No cadastro daAgenda de Execuções, associe uma ou mais Tags a cada Job.

• Se associar mais de uma Tag, a ordem define a prioridade de failover.
• Exemplo: Tag 1 = SERVIDOR_A, Tag 2 = SERVIDOR_B. O Job rodará no A; se o A cair, rodará no B.

9. Exemplos Práticos de Uso

Distribuição de Carga (Load Balancing)

Se você tem integrações volumosas, pode criar uma tag INTEGRACOES vinculada a um servidor mais potente e associar todos os Jobs de integração a essa tag.

Redundância Total

Para um Job crítico, associe as Tags de todos os seus servidores (Ex: TAG_SERV_1, TAG_SERV_2). O sistema garantirá que o Job rode sempre que houver ao menos um servidor online.