Skip to content

Tarefas Agendadas & Crons no Cloudflare (Cloudflare Cron Triggers)

Tarefas Agendadas (Cron Triggers & Background Tasks)

Section titled “Tarefas Agendadas (Cron Triggers & Background Tasks)”

O Prime Crown utiliza os Cron Triggers nativos do Cloudflare Workers para executar rotinas operacionais assíncronas em segundo plano, sem necessidade de servidores externos.


O Worker chat-do chama o dispatch a cada cinco minutos. O dispatch registra um heartbeat e entrega as rotinas ao servidor. Cada rotina aplica sua própria janela de execução. Para os horários de negócio, a referência é Londres.

  • A cada tick: envio de mensagens de chat agendadas, fechamento de canais expirados, recuperação de canais em falta, processamento de traduções adiadas, resumos de conversas e geração de despesas recorrentes pendentes.
  • A cada dia de Londres: maybeRefreshTurnover recalcula o faturamento por empresa. maybeRefreshIntegrityAudit atualiza o resultado usado em Billing → Integrity. O GET /api/atomic/integrity-audit lê o resultado salvo e calcula na primeira leitura se ainda não houver um. Check now recalcula por POST. As duas rotas exigem ADMIN ou MANAGER.
  • A cada hora: o processamento da fila consulta mudanças no QuickBooks por empresa para recuperar avisos perdidos, e o monitor da linha WhatsApp verifica coexistência, conexão, webhook e acesso. A correção de coordenadas de endereço tem sua própria janela horária.

E. Faxina Semanal do Banco D1 (Housekeeping Cron / /api/cron/housekeeping)

Section titled “E. Faxina Semanal do Banco D1 (Housekeeping Cron / /api/cron/housekeeping)”
  • Frequência: Semanal (executado via dispatch-scheduled com throttle automático de 7 dias, ou sob demanda via POST /api/cron/housekeeping).
  • Função: Mantém o banco D1 enxuto, rápido e estritamente dentro dos limites da Cloudflare:
    1. Expurga registros de system_logs com mais de 45 dias.
    2. Remove orçamentos não aceitos (lead_quotes sem visita) parados há mais de 30 dias e, depois, os leads que não viraram cliente e estão 30 dias sem atividade (mensagem ou orçamento).
    3. Expurga pedidos e tokens temporários já expirados (whatsapp_access_requests, password_reset_tokens, webauthn_challenges).

F. Governança de Mídia no Cloudflare R2 (Storage Lifecycle)

Section titled “F. Governança de Mídia no Cloudflare R2 (Storage Lifecycle)”
  • Frequência: Diariamente gerenciado nativamente pela Cloudflare.
  • Função: Expiração automática de fotos de inspeção e checklist de tarefas com mais de 12 meses (365 dias), preservando metadados no D1 e prevenindo custos desnecessários com arquivos órfãos.

G. Extensão Automática de Recorrência (Recurrence Auto-Extend Cron / /api/cron/recurrence-auto-extend)

Section titled “G. Extensão Automática de Recorrência (Recurrence Auto-Extend Cron / /api/cron/recurrence-auto-extend)”
  • Frequência: Semanal (executado via dispatch-scheduled uma vez por semana ISO de Londres: a semana é reservada antes do trabalho com um id fixo em system_logs, AUTO-EXTEND-<semana>, então duas chamadas sobrepostas não geram visitas em dobro; uma falha libera a reserva, ou via chamada autenticada POST /api/cron/recurrence-auto-extend). Suporta dry-run via GET.
  • Função: Projeta e cria automaticamente visitas futuras para séries ativas (recurring_series.status = 'ACTIVE') que terminam em menos de 60 dias, garantindo que o calendário da empresa nunca fique desabastecido.
  • Gestão por Exceção (Issues): Caso a equipe titular tenha conflito de horário na nova data (visita sobreposta ou funcionária em férias/licença aprovada em timeOffsJson), o sistema cria a visita com status PENDING e sem equipe atribuída (assignedEmployeeIds = []). Dessa forma, ela entra automaticamente na aba Issues (OpsCommander > Issues) e na Agenda para alocação manual sem travar o agendamento do cliente.
  • Trava Financeira: Séries de clientes com faturas vencidas há mais de 30 dias são ignoradas (skippedOverdueDebt), evitando comprometer a frota com inadimplentes graves.
  • Visita nova, dados novos: cada visita herda o preço da série e as horas por pessoa, nunca os eventos da última (dinheiro recebido, gorjeta, reembolso, uso de mudança grátis, forma de pagamento); o checklist nasce desmarcado.
  • Proteção D1: Gravações divididas em lotes seguros de 4 registros para nunca estourar o teto de 100 variáveis SQL por query do Cloudflare D1.

H. Aviso de chegada atrasada (alertLateArrivals, functions/api/cron/lateArrivalAlerts.ts)

Section titled “H. Aviso de chegada atrasada (alertLateArrivals, functions/api/cron/lateArrivalAlerts.ts)”
  • Frequência: a cada tick do dispatch-scheduled (5 min).
  • Função: visita SCHEDULED com equipe, 15 min (o mesmo prazo da seção Late da Agenda) a 3 h depois do início e sem check-in → push para cada ADMIN/MANAGER, categoria TEAM (respeita o opt-out “Staffing”), abrindo em /?view=LIVE_TRACKER&reqId=, e para cada pessoa da equipe da visita (desde 2026-09-24; quem da equipe é gerente recebe só o do escritório), “Not clocked in”, pedindo o check-in ou avisar o escritório no chat da tarefa, abrindo a visita no próprio Schedule (lateArrivalCrewUrl, /?view=SCHEDULE&reqId=); sem gerente cadastrado a equipe ainda recebe. Uma vez por visita: o aviso é reconhecido por qualquer um dos dois links em notification_history (que sendPushToUser grava antes do envio), sem lista de ids — sem teto de parâmetros do D1.

alertForgottenCheckouts avisa a pessoa que ainda está em campo 15 minutos após as horas contratadas, contadas a partir do check-in dela. O aviso é individual e não altera a remuneração.

I. Coordenadas de endereço (maybeGeocodeAddresses, functions/api/cron/geocodeAddresses.ts)

Section titled “I. Coordenadas de endereço (maybeGeocodeAddresses, functions/api/cron/geocodeAddresses.ts)”
  • Frequência: de hora em hora (marcador ADDRESS_GEOCODE_RUN em system_logs), só quando há trabalho.
  • Função: endereço com CEP e sem lat/lng recebe o centro do CEP (lib/geocode.ts, postcodes.io em lotes de 100, até 300 por execução); depois a cópia do endereço nas visitas (address_snapshot_json) sem coordenadas recebe as do endereço que ela nomeia. Sem bump de versão: uma gravação antiga que apague as coordenadas é refeita na hora seguinte. A gravação de cliente e de funcionária (atomic/clients.ts, atomic/employees.ts) já preenche na hora, no waitUntil; o cron cobre a carga antiga (em 2026-09-23, 240 de 244 endereços de clientes estavam sem coordenadas) e falhas do serviço. A busca tolera ponto/traço e a letra O digitada no lugar do zero (postcodeCandidates: pergunta as duas formas e fica com a que existe — “TW1O 7QT” → TW10 7QT); nenhuma outra adivinhação, e o CEP gravado não muda. CEP incompleto (“KT10”) ou inexistente fica sem coordenadas e é tentado de novo a cada hora.

J. Geração Semanal Automática de Folha (maybeRunAutoPayroll, functions/api/cron/autoPayroll.ts)

Section titled “J. Geração Semanal Automática de Folha (maybeRunAutoPayroll, functions/api/cron/autoPayroll.ts)”
  • Frequência: Semanal às Segundas-feiras às 03:00 AM de Londres (configurável em payrollConfig: runDayOfWeek = 1, runHourLondon = 3, cutoffStrategy = 'YESTERDAY').
  • Função: Gera rascunhos de folha de pagamento (DRAFT) de forma totalmente autônoma em segundo plano na madrugada de segunda-feira.
  • Ciclo Fechado (Segunda a Domingo 23:59:59): O ciclo compreende 7 dias completos, iniciando na Segunda-feira e encerrando no final de Domingo (YESTERDAY). As tarefas finalizadas até 23:59:59 de domingo entram no ciclo. Tarefas fechadas posteriormente entram automaticamente na folha seguinte.
  • Idempotência Semanal: Registra previamente claim único em system_logs (AUTO-PAYROLL-<YYYY-MM-DD>) ancorado na segunda-feira, impedindo disparos múltiplos ou retries conflitantes na mesma semana.
  • Retro Tasks: Ingestão automática de qualquer tarefa elegível finalizada após folhas passadas, integrando-a na rodada corrente sem intervenção manual.
  • Notificação: Dispara alerta Push aos administradores detalhando o total a pagar e número de holerites criados, ou registra PAYROLL_AUTO_SKIPPED caso não haja tarefas pendentes de pagamento.

K. Liberação Semanal de Holerites à Equipe (maybeReleaseSundayPayslips, functions/api/cron/payrollRelease.ts)

Section titled “K. Liberação Semanal de Holerites à Equipe (maybeReleaseSundayPayslips, functions/api/cron/payrollRelease.ts)”
  • Frequência: A cada tick do dispatch-scheduled (5 min) e no fechamento da folha (atomic/payrollRuns.ts).
  • Função: Mantém os holerites gerados em rascunho e em aberto totalmente invisíveis para a equipe enquanto o gerente confere a folha na segunda-feira. Assim que o gerente confere e fecha o ciclo (CLOSED), a rotina libera a visualização dos holerites aos funcionários e dispara notificações Push individuais (Weekly Payslip Ready).
  • Idempotência & Auditoria: Grava claim único em system_logs com a chave PAYROLL_RELEASE_<runId> e ação PAYROLL_STAFF_RELEASED, garantindo disparo único mesmo em múltiplos ticks do cron.

O Worker chat-do dispara as rotinas pelo seu Cron Trigger (*/5 * * * *) chamando /api/cron/dispatch-scheduled e /api/whatsapp/process-queue com um bearer secreto. A rotina semanal do Google Business Profile (/api/cron/gbp-weekly) foi removida: as publicações vivem em social/ no repositório do site (prime-crown-cleaning), com um único texto e npm run social:publish. Esse segredo é CRON_SECRET, próprio das rotinas. Antes era o JWT_SECRET — a chave que assina todas as sessões — trafegando a cada cinco minutos e guardado num segundo Worker.

isCronCaller (functions/api/common/cronAuth.ts) compara em tempo constante e aceita somente CRON_SECRET. O Worker chat-do recusa o tick se esse segredo faltar — JWT_SECRET já não autentica rotinas.