Lógica de Envio de Notificações Sequenciais (Intervalos 1, 3 e 5 dias)

Visão Geral

Este documento explica a lógica de agendamento de notificações de faturas vencidas, implementada para evitar múltiplas notificações em sequência e respeitar dias úteis (finais de semana e feriados).

Conceitos Fundamentais

Dia Útil

Intervalos de Notificação

Por padrão, enviamos notificações em 3 momentos:

Janela de Envio

Apenas faturas com ≤ 5 dias de atraso (contados a partir do vencimento original) recebem notificações.

Lógica de Agendamento Sequencial

Regra Principal

As datas de notificação são calculadas de forma sequencial e sempre normalizadas para dia útil:

1. Primeiro intervalo (N=1)

Data agendada = vencimento original + 1 dia. Se cair em fim de semana/feriado → empurra para o próximo dia útil.

2. Demais intervalos (N=3, N=5)

Sempre calculados a partir da data do primeiro intervalo. Se cair em fim de semana/feriado → empurra para o próximo dia útil.

Exemplo Detalhado

Case 1: Vencimento no Sábado (27/09/2025)

Resumo:

Vencimento: 27/09 (sáb) → 1 dia: 29/09 (seg) → 3 dias: 01/10 (qua) → 5 dias: 03/10 (sex)

Case 2: Vencimento no Domingo (21/09/2025)

Resumo:

Vencimento: 21/09 (dom) → 1 dia: 22/09 (seg) → 3 dias: 24/09 (qua) → 5 dias: 26/09 (sex)

Case 3: Vencimento em Dia Útil (26/09/2025)

Resumo:

Vencimento: 26/09 (sex) → 1 dia: 29/09 (seg) → 3 dias: 01/10 (qua) → 5 dias: 03/10 (sex)

Case 4: Com Feriado no Meio (03/10 é feriado)

Resumo:

Vencimento: 26/09 (sex) → 1 dia: 29/09 (seg) ✓ → 3 dias: 01/10 (qua) ✓ → 5 dias: descartado (excede janela de 5 dias)

Regras de Elegibilidade

Métodos de Pagamento Aceitos

Exclusões

Condições de Envio

Implementação

Arquivos Principais

Scheduler Utilitário

Arquivo: src/Notifications/Custom/Helpers/InvoiceNotificationScheduler.php

Função: Contém toda a lógica de dia útil, normalização e agendamento sequencial.

Notificação Inteligente

Arquivo: src/Notifications/Custom/OrderDetailsSmartLateNotification.php

Função: Implementa o envio usando o scheduler.

Como Adicionar Novos Intervalos

    // Em OrderDetailsSmartLateNotification.php
    private array $intervals = [1, 3, 5, 7]; // Adiciona intervalo de 7 dias
    

Testes

Script de Teste

Arquivo: src/Notifications/Custom/tests_scheduler_instancias.php

Execução: php modules/addons/lknhooknotification/src/Notifications/Custom/tests_scheduler_instancias.php

Vantagens desta Abordagem

Fluxograma de Decisão

┌─────────────────────┐
│ Hoje é dia útil?    │
└──────┬──────────────┘
       │ Não → FIM (não envia nada)
       │ Sim
       ▼
┌─────────────────────┐
│ Busca faturas       │
│ status = Overdue    │
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ Para cada fatura:   │
│ Método elegível?    │
└──────┬──────────────┘
       │ Não → próxima fatura
       │ Sim
       ▼
┌─────────────────────┐
│ Calcula agenda      │
│ para [1, 3, 5]      │
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ Algum intervalo     │
│ bate com hoje?      │
└──────┬──────────────┘
       │ Não → próxima fatura
       │ Sim
       ▼
┌─────────────────────┐
│ Atraso ≤ 5 dias?    │
└──────┬──────────────┘
       │ Não → próxima fatura
       │ Sim
       ▼
┌─────────────────────┐
│ ✓ ENVIA NOTIFICAÇÃO │
└─────────────────────┘

Perguntas Frequentes

Por que não enviar no dia do vencimento efetivo?

Porque queremos dar um dia de "tolerância" antes de começar as cobranças.

O que acontece se a fatura for paga entre notificações?

O sistema considera apenas faturas com status Overdue.

E se o feriado empurrar a notificação para além de 5 dias?

A notificação é descartada.

Posso ter intervalos não sequenciais?

Sim! O scheduler ordena automaticamente.

Como adicionar feriados?

Insira na tabela gk2_hollidays com a coluna date.

Manutenção

Para ajustar o comportamento:

Dados da revisão