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.
1. Cadência
Section titled “1. Cadência”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.
2. Rotinas executadas
Section titled “2. Rotinas executadas”- 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:
maybeRefreshTurnoverrecalcula o faturamento por empresa.maybeRefreshIntegrityAuditatualiza o resultado usado em Billing → Integrity. OGET /api/atomic/integrity-auditlê o resultado salvo e calcula na primeira leitura se ainda não houver um. Check now recalcula porPOST. 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-scheduledcom throttle automático de 7 dias, ou sob demanda viaPOST /api/cron/housekeeping). - Função: Mantém o banco D1 enxuto, rápido e estritamente dentro dos limites da Cloudflare:
- Expurga registros de
system_logscom mais de 45 dias. - Remove orçamentos não aceitos (
lead_quotessem 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). - Expurga pedidos e tokens temporários já expirados (
whatsapp_access_requests,password_reset_tokens,webauthn_challenges).
- Expurga registros de
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-scheduleduma vez por semana ISO de Londres: a semana é reservada antes do trabalho com um id fixo emsystem_logs,AUTO-EXTEND-<semana>, então duas chamadas sobrepostas não geram visitas em dobro; uma falha libera a reserva, ou via chamada autenticadaPOST /api/cron/recurrence-auto-extend). Suporta dry-run viaGET. - 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 statusPENDINGe 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
SCHEDULEDcom 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, categoriaTEAM(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 emnotification_history(quesendPushToUsergrava antes do envio), sem lista de ids — sem teto de parâmetros do D1.
H2. Lembrete de saída
Section titled “H2. Lembrete de saída”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_RUNemsystem_logs), só quando há trabalho. - Função: endereço com CEP e sem
lat/lngrecebe 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, nowaitUntil; 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_SKIPPEDcaso 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_logscom a chavePAYROLL_RELEASE_<runId>e açãoPAYROLL_STAFF_RELEASED, garantindo disparo único mesmo em múltiplos ticks do cron.
🔑 3. Autenticação das rotinas
Section titled “🔑 3. Autenticação das rotinas”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.