Jobs, filas e scheduler

O SteerCrew usa execução assíncrona para eventos internos, flows e WhatsApp. O código dos jobs já faz parte da aplicação; implantação precisa manter workers e scheduler ativos.

Filas obrigatórias

Fila	Consumidor	O que processa
events	StoreInternalEvent	Persiste eventos de negócio e inicia flows assinantes.
whatsapp	SendWhatsAppMessage	Envia mensagens e registra resposta/erro do provedor.
workflows	ExecuteWorkflow, ResumeWorkflowWait	Executa grafos e retoma esperas.
default	Jobs sem fila específica	Compatibilidade com tarefas gerais do framework.

Worker recomendado:

php artisan queue:work --queue=events,whatsapp,workflows,default --sleep=3 --tries=3 --timeout=90

O composer dev usa queue:listen com uma tentativa para facilitar desenvolvimento. O Docker Compose também fornece um worker com até três tentativas. Dimensione concorrência somente depois de medir a fila; mais workers não corrigem dependência indisponível.

Jobs atuais

ExecuteWorkflow

Busca a execução e sua definição, chama o engine, finaliza o flow pai quando houver e registra falha sanitizada se o job esgotar tentativas. É idempotente no nível de criação da execução e dos efeitos que possuem chaves próprias; mesmo assim, APIs externas devem respeitar o Idempotency-Key enviado pelo node.

ResumeWorkflowWait

Busca uma espera pendente. Se não existir, já tiver sido consumida ou ainda estiver no futuro, termina sem efeito. Caso contrário, retoma o engine.

SendWhatsAppMessage

Ignora mensagem já enviada/simulada, simula em execução de teste e chama a Meta em produção. Sucesso salva o ID do provedor; falha salva mensagem e payload técnico antes de relançar a exceção.

StoreInternalEvent

É um listener enfileirado, não uma classe de job. Persiste o evento, monta o contexto, trata correlações de espera e cria execuções para assinaturas ativas. Conversas atribuídas ou bloqueadas não iniciam automações de mensagem.

Scheduler

Mantenha uma única estratégia:

php artisan schedule:work

ou cron chamando php artisan schedule:run a cada minuto.

Rotina	Frequência	Função
workflows:tick	Cada minuto, sem sobreposição	Dispara agendas vencidas e enfileira retomada de waits.
workflows:prune	Diária, sem sobreposição	Aplica retenção de execuções, logs, auditoria e eventos internos.

Valide com php artisan schedule:list. Scheduler ativo sem worker ainda deixa jobs pendentes.

Retenção

Padrões por flow:

• produção: 90 dias;
• manual e teste: 30 dias;
• logs de execução: 30 dias;
• payload final: estrutura redigida;
• auditoria geral: 15 dias;
• eventos internos processados: 15 dias, exceto project.status_changed, preservado para a timeline.

Administradores podem ajustar retenção do flow dentro dos limites da tela. A limpeza só remove execuções em estado final; não apaga espera pendente.

Operar com segurança

Após deploy:

1. Aplique configuração e migrações.
2. Reinicie workers graciosamente para carregar o novo código.
3. Confira php artisan schedule:list.
4. Monitore fila, jobs falhos e tempo até processamento.
5. Execute um evento controlado e confirme seu histórico.

Comandos de leitura úteis:

php artisan queue:failed
php artisan schedule:list

Não limpe a fila inteira nem reexecute todos os jobs falhos sem identificar efeitos externos. Para sintomas e evidências, consulte Diagnóstico.

Quando adicionar uma fila

Uma nova fila só é necessária quando isolamento operacional estiver comprovado. Ao criá-la, atualize job/listener, worker local, Docker/supervisor, produção, monitoramento e esta página. Se não houver requisito de isolamento, reutilize uma fila existente.