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
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

Tarefas

1. Busca escolas com assinatura ativa
2. Gera faturas para o próximo mês
3. Cria links de pagamento (MercadoPago)
4. 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)

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

1. Busca faturas com vencimento em 5 dias
2. Filtra faturas pendentes sem lembrete enviado
3. Envia mensagem WhatsApp de lembrete
4. 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

---

4. Manutenção Diária

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

1. 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.
2. Schema probes — Verifica integridade do schema (tabelas, colunas, constraints)
3. 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):

1. Admin seleciona job
2. Confirma execução manual
3. Edge Function é chamada com action do registry
4. 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