title: Conceito: Schedule description: O Schedule como declaração de gatilho periódico e governança de tarefas de cron.

Schedule¶

O Schedule representa a declaração de um gatilho temporal periódico para a execução de tarefas automáticas. Ele define "quando" um trabalho deve ser disparado, desacoplando o cronograma da lógica de execução.

O que é¶

É uma declaração formal de intenção cronológica vinculada a uma Extension ou ao Core do framework. Um Schedule define: * Ação Alvo: Qual orquestrador ou disparador de Command deve ser acionado. * Intervalo: A frequência base de execução (ex: cada hora, diário, uma expressão Cron). * Responsável: A que componente do framework aquele gatilho pertence.

Por que existe¶

O Moodle gerencia tarefas periódicas através das scheduled_tasks, mas defini-las manualmente exige criar classes específicas, metadados em db/tasks.php e gerenciar manualmente intervalos e permissões.

O framework usa Schedules para centralizar essa governança: 1. Visibilidade Arquitetural: Saber quais gatilhos temporais cada extension está registrando no sistema. 2. Automação de Infraestrutura: Permitir que o framework gere ou sincronize automaticamente as tarefas necessárias no Moodle a partir de declarações de alto nível. 3. Desacoplamento de Gatilhos: Um mesmo trabalho (Command) pode ter múltiplos Schedules (um de limpeza rápida a cada hora e outro de auditoria profunda semanal).

Como se relaciona com outros conceitos¶

Schedule vs Command: O Command é o trabalho; o Schedule é o relógio que o desperta. O Schedule não deve conter lógica de negócio; ele deve apenas despachar um Command.
Schedule vs Job: O Schedule é o gatilho fixo; o Job é a instância individual de execução. Se um Schedule disparar um Command que exija governança, um Job será aberto para acompanhar essa execução específica.
Schedule vs Moodle Task API: O Schedule é a declaração do framework; o Moodle via scheduled_task é o Adapter técnico que executa o gatilho.

Decisões de design¶

Sincronização via CLI: Schedules declarados no código não são carregados dinamicamente no banco de dados em cada request. Eles são processados via ferramentas de CLI durante o deploy ou build para gerar os arquivos db/tasks.php e as classes de task correspondentes no Moodle.
Propriedade de Componente: Cada Schedule é obrigatoriamente vinculado a uma Extension ou componente do Core. Isso permite ao administrador desabilitar todos os gatilhos de uma extension desativada de forma limpa.
Precedência do Moodle: Embora o framework sugira um intervalo padrão, o Moodle continua sendo a autoridade final. Configurações feitas pelo administrador na interface do Moodle (excluir ou desativar uma task) têm prioridade sobre as definições do Schedule.

O que não é¶

Não é um Job: O Schedule não registra o sucesso ou falha de uma execução individual; ele apenas "bate o ponto" para que o trabalho comece.
Não é o Executor: O framework não implementa seu próprio motor de cron; ele delega totalmente para o cron.php do Moodle.
Não é para Lógica Interna de Task: Evite colocar if e else complexos no disparador do Schedule. Se a lógica for complexa, mova-a para um Orquestrador ou para um Command Handler.

Perspectiva para builders de extensions¶

Como desenvolvedor de extension: 1. Declare sua Intenção: No seu arquivo de metadados ou classe de extension, declare qual trabalho precisa de execução periódica. 2. Use Adaptadores Existentes: O framework fornece disparadores "coringa" para frequências comuns (diário, semanal). Use-os para plugar comportamentos leves por meio de Hooks ou Listeners. 3. Pense em Lote: Trabalhos periódicos costumam processar muitos registros. Garanta que o Command disparado pelo seu Schedule suporte processamento em massa e limitação de recursos.

Exemplo ilustrativo¶

Fluxo de um Schedule de limpeza de logs:

1. Declaração (Extension): "Daily cleanup of old audit logs" (Cada 24h).
2. Build (Framework): Gera a classe 'local_middag\task\cleanup_logs_task' e registra no Moodle.
3. Gatilho (Moodle Cron): À meia-noite, o Moodle executa a task gerada.
4. Execução (Framework):
   - O orquestrador de limpeza é acionado.
   - Ele despacha um 'cleanup_logs_command'.
   - O 'cleanup_logs_command_handler' executa a deleção no banco.