Fila e cron

O Correios Updater não consulta os Correios de forma síncrona quando o cliente acessa o site — todo trabalho pesado acontece em segundo plano, em duas etapas: o cron do WordPress agenda a rodada, e o Action Scheduler do WooCommerce processa cada pedido individualmente. Esta página explica como esse encadeamento funciona.

Por que dois sistemas?

• Cron do WordPress é simples mas executa tudo em uma chamada só. Se você tem 200 pedidos pra checar, o WordPress travaria por minutos.
• Action Scheduler é uma fila assíncrona — cada pedido vira uma tarefa separada, processada em pequenos lotes em requisições subsequentes. Não trava o site.

A combinação é: o cron é o "gatilho" (a cada 3 horas, dispara), e a fila é o "executor" (processa pedido por pedido em paralelo controlado).

Fluxo completo

1. Cron WordPress dispara correios_updater_queue.
2. Plugin chama push_orders_to_queue().
3. Esse método busca todos os pedidos elegíveis (status em Status para se verificar + tem código de rastreio).
4. Pra cada pedido, agenda uma tarefa correios_updater_handle_event na fila.
5. Antes de agendar novas, cancela as tarefas antigas (evita ficar acumulando se a rodada anterior demorou).
6. Action Scheduler processa cada tarefa: chama os Correios pra cada código, compara com o último visto, dispara mudança de status / e-mail se aplicável.

Intervalo do cron

Padrão: 180 minutos (3 horas).

O intervalo é registrado via wp_schedule_event. Pra mudar, use o filtro correios_updater_cron_interval:

add_filter( 'correios_updater_cron_interval', function() {
    return 60; // checa a cada hora
});

Mais informações em Filtros disponíveis.

Forçar rodada manual

Duas formas:

1. Pela tela de configurações. Em WooCommerce → Configurações → Correios Updater há um botão pra forçar a verificação.
2. Pela URL. Logado como admin, abra:

   https://sua-loja.com/wp-admin/?correios-updater-force-cron
   

Isso popula a fila imediatamente. As tarefas individuais ainda passam pelo Action Scheduler — então não é "instantâneo", mas começa em segundos.

Onde as tarefas ficam

O Action Scheduler tem painel próprio em Ferramentas → Tarefas Agendadas (tools.php?page=action-scheduler). Procure pelo grupo correios_updater. Lá você vê:

• Tarefas pendentes (vão rodar ainda).
• Tarefas em execução.
• Tarefas concluídas (com timestamp e log resumido).
• Tarefas que falharam (com mensagem do erro).

Útil pra debugar quando algo está travado.

Diagnóstico: cron não está rodando

Sintomas:

• Pedidos novos com código de rastreio não atualizam status, mesmo passando horas.
• O Rastreio teste funciona (a credencial está ok).

Causas comuns:

• DISABLE_WP_CRON está true no wp-config.php. Sem isso o WordPress não agenda nada — você precisa de um cron externo do servidor batendo em wp-cron.php.
• Hospedagem com cron quebrado. Sites com pouco tráfego não disparam o cron sozinho (o WP precisa de uma visita pra rodar). Configure um cron de servidor:

  */15 * * * * curl -s https://sua-loja.com/wp-cron.php?doing_wp_cron > /dev/null
  

• Plugin de cache agressivo. Se o cache não deixa o wp-cron.php ser chamado, o cron quebra.

Mais em Solução de problemas.

Hooks relacionados

• correios_updater_queue — hook do cron que dispara a montagem da fila. Não chame direto a não ser que saiba o que está fazendo.
• correios_updater_handle_event — hook do Action Scheduler que processa um pedido individualmente. Idem.

Veja Actions disponíveis e Filtros disponíveis pra hooks úteis pra customização.