Jobs CRON

Registry centralizado em supabase/functions/_shared/cron-jobs.ts (SSOT)

1. Visão Geral

Job	Schedule (BRT)	Schedule (UTC)	Cron	Edge Function
Gerar Faturas	Último dia do mês 03:00	06:00	`0 6 28-31 * *`	`faturamento-cron`
Lembrete D-5	Diário 06:00	09:00	`0 9 * * *`	`faturamento-cron`
Marcar Vencidas	Diário 04:30	07:30	`30 7 * * *`	`faturamento-cron`
Régua de Cobrança	Diário 09:00	12:00	`0 12 * * *`	`faturamento-cron`
Manutenção	Diário 04:00	07:00	`0 7 * * *`	`maintenance-cron`
Health Check	A cada 6h	00:00, 06:00, 12:00, 18:00	`0 /6 * *`	`healthcheck-cron`

2. Gerar Faturas Mensal

Ação: gerar_faturas
Quando: Último dia de cada mês às 03:00 BRT
Function: faturamento-cron

Parâmetros (body JSON)

Campo	Tipo	Obrigatório	Descrição
`action`	string	Sim	`gerar_faturas`
`manual`	boolean	Não	`true` para execução manual (bypassa guard de último dia do mês)
`referencia_mes`	string	Não	`YYYY-MM-01`. Quando presente e `manual: true`, usa esse mês em vez de `calcularProximoMes()`. Permite processar meses retroativos.
`triggered_by`	string	Não	UUID do usuário que disparou
`triggered_by_name`	string	Não	Nome do usuário

Tarefas

Busca escolas com assinatura ativa
Completa faturas skeleton ou cria novas para o mês de referência
Cria link de pagamento (MercadoPago Checkout Pro)
Emite boleto bancário (bolbradesco) em background via EdgeRuntime.waitUntil — best-effort, não bloqueia o cron nem aborta a geração das demais faturas. PDF fica disponível em escola_faturas.boleto_pdf_url para download imediato pela escola. Skip silencioso quando escola não tem CNPJ ou endereço completo.
Envia mensagem WhatsApp com link para gestores

Ações de Log

Ação	Tipo
`faturamento.gerar_faturas_started`	Início
`faturamento.gerar_faturas_executado`	Sucesso
`faturamento.link_gerado`	Link individual
`faturamento.sms_enviado`	Mensagem individual
`faturamento.erro`	Erro individual
`faturamento.cron_erro`	Erro fatal
`faturamento.cron_alerta`	Alerta (2 falhas)
`faturamento.cron_critico`	Crítico (3 falhas)
`faturamento.alerta_faturas_sem_link`	Alerta de saúde (0 processadas)

Métricas Extraídas

links_gerados — Total de links criados
sms_enviados — Total de mensagens enviadas

3. Lembrete D-5 Diário

Ação: lembrete_d5
Quando: Diariamente às 06:00 BRT
Function: faturamento-cron

Tarefas

Busca faturas com vencimento em 5 dias
Filtra faturas pendentes sem lembrete enviado
Envia mensagem WhatsApp de lembrete
Cria notificação in-app

Ações de Log

Ação	Tipo
`faturamento.lembrete_d5_started`	Início
`faturamento.lembrete_d5_executado`	Sucesso

Métricas Extraídas

lembretes_enviados — Total de lembretes
sms_enviados — Total de mensagens

3.1 Marcar Vencidas Diário

Ação: marcar_vencidasQuando: Diariamente às 04:30 BRT (antes da régua, para que o estado esteja fresco) Function: faturamento-cronpg_cron jobid: 11 — marcar-vencidas-diario (cron 30 7 * * * UTC, agendado em 2026-05-06)

Tarefas

Busca faturas com status_pagamento = 'pendente' e vencimento_em definido.
Filtra com isPastDateBRT() (BRT canônico, UTC−3 fixo — proibido new Date() cru).
UPDATE em lote: status_pagamento = 'vencido', marcada_vencida_em = now() (filtro defensivo status_pagamento = 'pendente').

Ações de Log

Ação	Tipo
`faturamento.marcar_vencidas_started`	Início
`faturamento.marcar_vencidas_executado`	Sucesso
`faturamento.fatura_marcada_vencida`	Lote (até 50 IDs no detalhe)

Métricas Extraídas

marcadas_vencidas — Total de faturas que transitaram de pendente→vencido.

3.2 Régua de Cobrança Diária

Ação: regua_cobrancaQuando: Diariamente às 09:00 BRT (após marcar_vencidas) Function: faturamento-cronpg_cron jobid: 12 — regua-cobranca-diario (cron 0 12 * * * UTC, agendado em 2026-05-06) SSOT dos gatilhos: _shared/cobranca-regua.ts (espelha src/lib/cobranca-regua.ts).

Gatilhos

Régua	Dias de atraso	Tom
`d3`	3	Aviso após compensação (boleto compensa em até D+3 — primeiro toque seguro)
`d10`	10	Cobrança firme
`d17`	17	Aviso de bloqueio iminente

Demais atrasos (1..2, 4..9, 11..16, >17) são ignorados (sem reenvio).

Por que D+3 em vez de D+1? Boletos bancários podem levar até 3 dias úteis para compensar na conta da empresa após o pagamento. Disparar lembrete em D+1 gera ruído com clientes que pagaram na data certa — D+3 elimina esse falso-positivo. Régua antiga (d1/d7/d15) mantida como template histórico (não é mais usada pelo cron).

Idempotência

Garantida pelo índice único parcial uq_fatura_cobrancas_regua_auto em (fatura_id, regua_dia) WHERE origem='regua_auto' AND status IN ('enviado','entregue','lido'). Race entre workers é tratada como sucesso silencioso.

Tarefas

Carrega faturas vencido + dados da escola (escolas.nome).
Para cada uma calcula diasAtraso (BRT) e mapeia para régua via calcularReguaParaDiasAtraso.
Renderiza template cobranca_d{3|10|17} (_shared/sms-templates.ts).
Envia via helper enviarCobranca({ origem: 'regua_auto', ... }) — Wasender→Twilio, log estruturado em fatura_cobrancas.

Ações de Log

Ação	Tipo
`faturamento.regua_cobranca_started`	Início
`faturamento.regua_cobranca_executado`	Sucesso
`faturamento.cobranca_envio_automatico`	Envio individual OK
`faturamento.cobranca_noop`	Idempotência (já enviada)
`faturamento.cobranca_falha`	Falha individual

Métricas Extraídas

cobrancas_disparadas — Envios bem-sucedidos
cobrancas_skip — Sem destinatário ou já enviada (noop)
cobrancas_falhas — Falhas (ambos providers caíram)

Rate-limit

Bulk respeita o atraso default de 6s entre envios do Wasender (skipDelay=false).

Ação: manutencao
Quando: Diariamente às 04:00 BRT
Function: maintenance-cron

10 Tarefas de Cleanup

#	Tarefa	Ação de Log	Critério
1	OTPs do sistema	`manutencao.cleanup_login_otps`	`> 24 horas`
2	OTPs do portal	`manutencao.cleanup_portal_otps`	`> 24 horas`
3	Tentativas de login (portal)	`manutencao.cleanup_portal_tentativas`	`> 7 dias`
4	Notificações antigas	`manutencao.cleanup_notificacoes`	`> 7 dias`
5	Tokens de cadastro	`manutencao.cleanup_cadastro_tokens`	Expirados
6	Check sessão WhatsApp	`manutencao.check_whatsapp_session`	Diário
7	Token blacklist	`manutencao.cleanup_token_blacklist`	Expirados
8	Métricas rate limit portal	`manutencao.cleanup_portal_rate_metrics`	`> 30 dias`
9	Cooldown alertas	`manutencao.cleanup_alert_cooldown`	`> 24 horas`
10	Anonimização IPs (LGPD)	`manutencao.anonimizar_ips_lgpd`	`> 6 meses`

Check de Sessão WhatsApp

Verifica status da sessão Wasender via API
Se sessão desconectada → alerta push ntfy para admins
Cooldown: 24h entre alertas de sessão

Métricas Extraídas

total_removidos — Total de registros limpos

5. Health Check Periódico

Ação: healthcheck
Quando: A cada 6 horas (00:00, 06:00, 12:00, 18:00 UTC)
Function: healthcheck-cron

Probes

Write probes — Testa operações de escrita (INSERT/DELETE) em fluxos críticos (faturamento, inscrições, portais). Dados de teste isolados (ano_edicao = 1900) para evitar colisões.
Schema probes — Verifica integridade do schema (tabelas, colunas, constraints)
Dependency probes — Valida conectividade com serviços externos (Wasender, MercadoPago, ntfy)

Ações de Log

Ação	Tipo
`healthcheck.executado`	Sucesso
`healthcheck.falha`	Falha em um ou mais probes
`healthcheck.degradado`	Probes OK mas com latência alta ou erro parcial
`healthcheck.erro`	Erro fatal na execução

Métricas Extraídas

Resultado por probe (sucesso/falha/latência)

6. Política de Retry e Escalação

Aplica-se a Gerar Faturas e Manutenção:

Etapa	Condição	Ação
Retry	Falha	Tenta novamente em 15 minutos
Alerta	2 falhas consecutivas	Notificação in-app para admins
Crítico	3 falhas consecutivas	Mensagem WhatsApp para admins + alerta push ntfy.sh + status CRÍTICO

Alertas Push (ntfy.sh)

Complementar ao WhatsApp, alertas push são enviados via ntfy.sh para a equipe técnica em:

CRON falha crítica (3x consecutivas) — prioridade urgent
Sessão WhatsApp desconectada — prioridade urgent
Token revogado reutilizado — prioridade high

Ver detalhes: ALERTAS_PUSH.md

Cooldown de Mensagens

Manutenção: 2 horas entre mensagens de alerta
Faturamento: Sem cooldown adicional (cada ciclo é mensal)

7. Tabela `cron_status`

Referência de saúde dos jobs:

Campo	Tipo	Descrição
`job_name`	TEXT	Nome do job
`status`	TEXT	`operacional`, `alerta`, `critico`
`ultima_execucao`	TIMESTAMPTZ	Último run
`ultima_execucao_sucesso`	TIMESTAMPTZ	Último sucesso
`ultimo_erro`	TEXT	Mensagem de erro
`ultimo_erro_em`	TIMESTAMPTZ	Timestamp do último erro
`tentativas_consecutivas`	INT	Contador de falhas
`proximo_retry`	TIMESTAMPTZ	Próxima tentativa
`sms_critico_enviado_em`	TIMESTAMPTZ	Última mensagem de alerta
`atualizado_em`	TIMESTAMPTZ	Última atualização do registro

8. Trigger Manual (NOC)

Disponível no Monitor CRON (admin-cron-monitor):

Admin seleciona job
Confirma execução manual
Edge Function é chamada com action do registry
Resultado refletido em cron_status e logs_transacoes

⚠️ Aviso: Triggers manuais enviam mensagens reais (WhatsApp) para usuários das escolas.

9. Registry — Fonte da Verdade

O arquivo supabase/functions/_shared/cron-jobs.ts é a única fonte da verdade (SSOT):

Plug & Play: Para adicionar novo job, basta adicionar entrada no registry
Zero alterações em admin-cron-monitor, useAdminCronMonitor ou componentes
Tipos derivados: CronJobName, CronJobAction
Funções utilitárias: mapLogActionToJobName(), classifyLogType(), getJobActions()

Referências

supabase/functions/_shared/cron-jobs.ts — Registry SSOT
supabase/functions/faturamento-cron/index.ts — Faturas + Lembrete
supabase/functions/maintenance-cron/index.ts — Manutenção
supabase/functions/healthcheck-cron/index.ts — Health Check
supabase/functions/_shared/health-probes.ts — Probes de saúde
src/components/admin-cron-monitor.tsx — UI de monitoramento
src/hooks/useAdminCronMonitor.ts — Hook do monitor

Jobs CRON ​

1. Visão Geral ​

2. Gerar Faturas Mensal ​

Parâmetros (body JSON) ​

Tarefas ​

Ações de Log ​

Métricas Extraídas ​

3. Lembrete D-5 Diário ​

Tarefas ​

Ações de Log ​

Métricas Extraídas ​

3.1 Marcar Vencidas Diário ​

Tarefas ​

Ações de Log ​

Métricas Extraídas ​

3.2 Régua de Cobrança Diária ​

Gatilhos ​

Idempotência ​

Tarefas ​

Ações de Log ​

Métricas Extraídas ​

Rate-limit ​

10 Tarefas de Cleanup ​

Check de Sessão WhatsApp ​

Métricas Extraídas ​

5. Health Check Periódico ​

Probes ​

Ações de Log ​

Métricas Extraídas ​

6. Política de Retry e Escalação ​

Alertas Push (ntfy.sh) ​

Cooldown de Mensagens ​

7. Tabela cron_status ​

8. Trigger Manual (NOC) ​

9. Registry — Fonte da Verdade ​

Referências ​

Jobs CRON

1. Visão Geral

2. Gerar Faturas Mensal

Parâmetros (body JSON)

Tarefas

Ações de Log

Métricas Extraídas

3. Lembrete D-5 Diário

Tarefas

Ações de Log

Métricas Extraídas

3.1 Marcar Vencidas Diário

Tarefas

Ações de Log

Métricas Extraídas

3.2 Régua de Cobrança Diária

Gatilhos

Idempotência

Tarefas

Ações de Log

Métricas Extraídas

Rate-limit

10 Tarefas de Cleanup

Check de Sessão WhatsApp

Métricas Extraídas

5. Health Check Periódico

Probes

Ações de Log

Métricas Extraídas

6. Política de Retry e Escalação

Alertas Push (ntfy.sh)

Cooldown de Mensagens

7. Tabela `cron_status`

8. Trigger Manual (NOC)

9. Registry — Fonte da Verdade

Referências