Sistema de Notificações Progressivas

Documentação Técnica Completa

v1.0.0Produção

1. Visão Geral do Sistema

Arquitetura e funcionamento do sistema de notificações automáticas

O sistema de notificações progressivas envia automaticamente **7 notificações** para prestadores antes do início de cada ação, garantindo alta taxa de comparecimento e confirmação de presença.

Fluxo de Funcionamento

Agendamento: Ao criar alocação, sistema calcula 7 horários de notificação

Ajuste: Horários entre 00h-06h são ajustados (janela silenciosa)

Processamento: Cron job verifica notificações pendentes a cada 5 minutos

Envio: Notificação push enviada para celular do prestador

Registro: Status atualizado para ENVIADA e log gravado

2. Marcos Temporais (7 Notificações)

Mensagens personalizadas para cada momento antes da ação

12h antes12H_ANTES

Confirme sua presença

⏰ Confirme sua presença na ação [AÇÃO] que inicia às [HORA]. Acesse o app agora!

Objetivo: Primeira notificação para confirmação de presença

8h antes8H_ANTES

Última chance de confirmar

⏰ Última chance de confirmar presença na ação [AÇÃO]. Não perca essa oportunidade!

Objetivo: Reforço para prestadores que ainda não confirmaram

6h antes6H_ANTES

Vaga será reaberta

⚠️ Atenção! Sem confirmação, a vaga da ação [AÇÃO] será reaberta. Fale com o recrutador se necessário.

Objetivo: Alerta crítico de perda de vaga

2h antes2H_ANTES

Revise informações

📋 Ação [AÇÃO] em 2h! Revise informações, orientações e confirme presença no grupo WhatsApp.

Objetivo: Preparação final e checklist

1h antes1H_ANTES

Mensagem motivacional

💪 Falta 1h! Faça o seu melhor, contamos com você!

Objetivo: Motivação e engajamento

30min antes30MIN_ANTES

Motores aquecidos

🚀 Motores aquecidos! Faltam 30min para começar.

Objetivo: Lembrete de proximidade

5min antes5MIN_ANTES

Realize check-in

📍 Últimos 5min! Em instantes, realize seu check-in.

Objetivo: Ação imediata: fazer check-in

3. Janela Silenciosa (00h-06h)

Ajuste automático de notificações para respeitar horário de descanso

Notificações calculadas entre **00h00 e 06h00** são automaticamente ajustadas para o horário mais próximo fora da janela silenciosa, respeitando o descanso dos prestadores.

Algoritmo de Ajuste

1. Detectar horário na janela

Se horário original está entre 00h00 e 06h00

2. Calcular alternativas

• Opção A: Antecipar para 23h59 do dia anterior

• Opção B: Adiar para 06h00 do mesmo dia

3. Escolher mais próximo

Comparar diferença em minutos e escolher menor distância

✅ Exemplo 1: Antecipar

Horário original: 02h00

Opção A: 23h59 (2h01min antes)

Opção B: 06h00 (4h depois)

Escolhido: 23h59 ✓

✅ Exemplo 2: Adiar

Horário original: 05h30

Opção A: 23h59 (5h31min antes)

Opção B: 06h00 (30min depois)

Escolhido: 06h00 ✓

4. Configuração de Cron Jobs

Endpoints e configurações para execução automática

Processamento de Notificações Progressivas

A cada 5 minutos

Endpoint:

POST /api/trpc/cronJobs.processarNotificacoesProgressivas

Body (JSON):

{
  "cronToken": "<CRON_SECRET_TOKEN>"
}

Configuração Vercel Cron (vercel.json):

{
  "crons": [{
    "path": "/api/cron/notificacoes-progressivas",
    "schedule": "*/5 * * * *"
  }]
}

Configuração GitHub Actions:

name: Processar Notificações
on:
  schedule:
    - cron: '*/5 * * * *'
jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Call endpoint
        run: |
          curl -X POST https://seu-dominio.com/api/trpc/cronJobs.processarNotificacoesProgressivas \
            -H "Content-Type: application/json" \
            -d '{"cronToken":"${{ secrets.CRON_SECRET_TOKEN }}"}'

Verificação de Alertas de Confirmação

A cada 1 hora

Endpoint:

POST /api/trpc/cronJobs.verificarAlertasConfirmacao

Configuração Vercel Cron:

{
  "crons": [{
    "path": "/api/cron/alertas-confirmacao",
    "schedule": "0 * * * *"
  }]
}

🔐 Segurança: Token CRON_SECRET_TOKEN

O token CRON_SECRET_TOKEN é gerado automaticamente e está disponível nas variáveis de ambiente. Use-o para autenticar chamadas aos endpoints de cron jobs.

5. Monitoramento e Logs

Ferramentas para acompanhar o sistema em produção

Log de Notificações

Acesse /admin/notificacoes-log para visualizar:

• Notificações agendadas
• Notificações enviadas
• Status de leitura
• Falhas e retries

Relatório de Confirmações

Acesse /admin/relatorio-confirmacoes para métricas:

• Taxa de confirmação global
• Tempo médio até confirmação
• Prestadores com baixa taxa
• Exportação CSV

Logs do Servidor

Monitore os logs do console para acompanhar execução dos cron jobs:

[2026-02-23 14:00:00] [CRON] Processando notificações progressivas...
[2026-02-23 14:00:01] [NOTIF] 3 notificações pendentes encontradas
[2026-02-23 14:00:02] [PUSH] Enviando para prestador ID 42: "Falta 1h! Faça o seu melhor..."
[2026-02-23 14:00:03] [SUCCESS] Notificação ID 156 enviada com sucesso
[2026-02-23 14:00:03] [CRON] Processamento concluído: 3 enviadas, 0 falhas

6. Troubleshooting

Problemas comuns e soluções

❌ Notificações não estão sendo enviadas

Causas possíveis:

• Cron job não configurado ou não está executando
• Token CRON_SECRET_TOKEN inválido
• Erro de conexão com API de push notifications

Soluções:

✓ Verificar configuração do cron job (Vercel/GitHub Actions)
✓ Validar token nas variáveis de ambiente
✓ Checar logs do servidor para erros de API
✓ Testar endpoint manualmente via Postman/curl

❌ Notificações duplicadas

Causas possíveis:

• Múltiplos cron jobs configurados
• Retry automático executando múltiplas vezes

Soluções:

✓ Verificar se há apenas um cron job ativo
✓ Checar tabela notificacoes_agendadas para duplicatas
✓ Limpar notificações antigas com status PENDENTE

❌ Prestador não recebe push no celular

Causas possíveis:

• Permissões de notificação desativadas no celular
• Token de push notification expirado
• App não instalado como PWA

Soluções:

✓ Orientar prestador a ativar notificações nas configurações do celular
✓ Pedir para prestador fazer logout/login para renovar token
✓ Instruir instalação do app via 'Adicionar à tela inicial'

❌ Horários ajustados incorretamente

Causas possíveis:

• Timezone do servidor diferente do esperado
• Lógica de janela silenciosa com bug

Soluções:

✓ Verificar timezone do servidor (deve ser America/Sao_Paulo)
✓ Testar função calcularHorariosNotificacoes com diferentes horários
✓ Executar testes unitários: pnpm test server/notificacoes

Sistema Configurado e Operacional

Para dúvidas ou suporte, acesse a página de Teste de Notificações ou entre em contato com a equipe técnica.