chore: sincroniza projeto para gitea
This commit is contained in:
Tiago
415
SISTEMA-ALERTAS-AUTOMATICOS.md
Normal file
415
SISTEMA-ALERTAS-AUTOMATICOS.md
Normal file
@@ -0,0 +1,415 @@
|
||||
# 🔔 Sistema de Alertas Automáticos de Vencimento
|
||||
|
||||
## 📋 Problema Identificado
|
||||
|
||||
**Situação:**
|
||||
- Venda realizada em 20/10/2025
|
||||
- Primeira parcela com vencimento em 24/10/2025
|
||||
- **Alertas NÃO foram enviados:**
|
||||
- ❌ 3 dias antes (21/10) - Não recebido
|
||||
- ❌ No dia do vencimento (24/10) - Não recebido com PIX
|
||||
|
||||
**Causa:**
|
||||
O sistema de alertas automáticos **não estava configurado** para rodar diariamente às 09:00.
|
||||
|
||||
---
|
||||
|
||||
## ✅ Solução Implementada
|
||||
|
||||
Criamos um sistema completo de alertas automáticos com:
|
||||
|
||||
1. **Script Node.js** que verifica parcelas e envia alertas
|
||||
2. **Cron Job** configurado para executar às 09:00 (Brasília)
|
||||
3. **Geração automática de PIX** no dia do vencimento
|
||||
4. **Logs** de todas as execuções
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Como Instalar
|
||||
|
||||
### Passo 1: Instalar o Cron Job
|
||||
|
||||
```bash
|
||||
cd /home/tiago/Downloads/app_estoque_v1.0.0
|
||||
chmod +x scripts/instalar-cron-alertas.sh
|
||||
./scripts/instalar-cron-alertas.sh
|
||||
```
|
||||
|
||||
O script irá:
|
||||
- ✅ Configurar execução diária às 09:00 (horário de Brasília)
|
||||
- ✅ Criar diretório de logs
|
||||
- ✅ Perguntar se quer fazer um teste imediato
|
||||
- ✅ Mostrar configuração final
|
||||
|
||||
### Passo 2: Configurar Variáveis de Ambiente
|
||||
|
||||
Crie/edite o arquivo `.env` na raiz do projeto:
|
||||
|
||||
```bash
|
||||
# Supabase
|
||||
SUPABASE_URL=https://ydhzylfnpqlxnzfcclla.supabase.co
|
||||
SUPABASE_SERVICE_KEY=seu_service_key_aqui
|
||||
# ou
|
||||
SUPABASE_ANON_KEY=seu_anon_key_aqui
|
||||
|
||||
# Evolution API (configurar no painel admin)
|
||||
# Mercado Pago (configurar no painel admin)
|
||||
```
|
||||
|
||||
### Passo 3: Configurar no Painel Admin
|
||||
|
||||
Acesse o painel admin → Configurações e configure:
|
||||
|
||||
**Evolution API:**
|
||||
- URL da API
|
||||
- Nome da instância
|
||||
- API Key
|
||||
|
||||
**Mercado Pago:**
|
||||
- Access Token (para geração de PIX)
|
||||
|
||||
**Alertas WhatsApp:**
|
||||
- Primeiro alerta: 3 dias antes ✅ ATIVO
|
||||
- Segundo alerta: No dia (0 dias) ✅ ATIVO
|
||||
- Alerta após vencimento: 3 dias após ✅ ATIVO
|
||||
- Mensagens personalizadas para cada tipo
|
||||
|
||||
---
|
||||
|
||||
## 🕐 Como Funciona
|
||||
|
||||
### Execução Automática
|
||||
|
||||
**Horário:** Todos os dias às 09:00 (horário de Brasília)
|
||||
|
||||
**O que o script faz:**
|
||||
|
||||
1. **Busca configurações** do banco de dados
|
||||
2. **Lista todas as parcelas pendentes**
|
||||
3. **Calcula dias para vencimento** de cada parcela
|
||||
4. **Verifica se deve enviar alerta:**
|
||||
- Primeiro alerta: 3 dias antes? ✅
|
||||
- Segundo alerta: No dia? ✅ + Gera PIX
|
||||
- Alerta pós-vencimento: 3 dias após? ✅
|
||||
5. **Substitui variáveis** na mensagem:
|
||||
- `{cliente}` → Nome do cliente
|
||||
- `{valor}` → R$ 150,00
|
||||
- `{quando}` → "em 3 dias" ou "hoje" ou "há 3 dias"
|
||||
- `{parcela}` → "1/3"
|
||||
6. **Envia via WhatsApp** usando Evolution API
|
||||
7. **Registra no histórico** de mensagens
|
||||
8. **Gera log** completo da execução
|
||||
|
||||
---
|
||||
|
||||
## 📱 Tipos de Alertas
|
||||
|
||||
### 1. Primeiro Alerta (3 dias antes)
|
||||
|
||||
**Quando:** 21/10 às 09:00 para vencimento em 24/10
|
||||
|
||||
**Mensagem padrão:**
|
||||
```
|
||||
Olá João! 👋
|
||||
|
||||
Lembramos que você tem uma parcela no valor de R$ 150,00 com vencimento em 3 dias (24/10/2025).
|
||||
|
||||
Agradecemos a atenção!
|
||||
```
|
||||
|
||||
### 2. Segundo Alerta (No dia do vencimento)
|
||||
|
||||
**Quando:** 24/10 às 09:00
|
||||
|
||||
**Mensagem padrão:**
|
||||
```
|
||||
Olá João! 👋
|
||||
|
||||
Sua parcela de R$ 150,00 vence hoje.
|
||||
|
||||
📱 PIX Copia e Cola:
|
||||
```00020126580014br.gov.bcb.pix...```
|
||||
|
||||
Agradecemos!
|
||||
```
|
||||
|
||||
**Ação extra:** Gera PIX automaticamente via Mercado Pago
|
||||
|
||||
### 3. Alerta Após Vencimento (3 dias após)
|
||||
|
||||
**Quando:** 27/10 às 09:00 para vencimento em 24/10
|
||||
|
||||
**Mensagem padrão:**
|
||||
```
|
||||
Olá João! 👋
|
||||
|
||||
Identificamos que a parcela 1/3 no valor de R$ 150,00 venceu há 3 dias (24/10/2025).
|
||||
|
||||
Por favor, regularize o pagamento.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Monitoramento
|
||||
|
||||
### Ver Logs em Tempo Real
|
||||
|
||||
```bash
|
||||
tail -f /home/tiago/Downloads/app_estoque_v1.0.0/logs/alertas-cron.log
|
||||
```
|
||||
|
||||
### Exemplo de Log
|
||||
|
||||
```
|
||||
🕐 Iniciando envio de alertas de vencimento...
|
||||
⏰ Horário: 24/10/2025, 09:00:15
|
||||
|
||||
📋 Configurações carregadas:
|
||||
- Primeiro alerta: 3 dias antes (ATIVO)
|
||||
- Segundo alerta: 0 dias antes (ATIVO)
|
||||
- Alerta pós-vencimento: 3 dias após (ATIVO)
|
||||
|
||||
📦 15 parcela(s) pendente(s) encontrada(s)
|
||||
|
||||
📤 Enviando segundo_alerta para João Silva (5543999762754)...
|
||||
🔄 Gerando PIX para parcela 1...
|
||||
✅ Enviado com sucesso!
|
||||
|
||||
📤 Enviando primeiro_alerta para Maria Santos (5543988776655)...
|
||||
✅ Enviado com sucesso!
|
||||
|
||||
==================================================
|
||||
📊 RESUMO DO ENVIO
|
||||
==================================================
|
||||
✅ Alertas enviados: 8
|
||||
❌ Erros: 0
|
||||
📦 Total de parcelas verificadas: 15
|
||||
==================================================
|
||||
|
||||
✅ Script finalizado com sucesso!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Teste Manual
|
||||
|
||||
Para testar o sistema sem esperar às 09:00:
|
||||
|
||||
```bash
|
||||
cd /home/tiago/Downloads/app_estoque_v1.0.0
|
||||
node scripts/enviar-alertas-parcelas.js
|
||||
```
|
||||
|
||||
Isso executará imediatamente e mostrará:
|
||||
- Quais alertas seriam enviados
|
||||
- Para quais clientes
|
||||
- Resultado de cada envio
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Verificar Cron Instalado
|
||||
|
||||
```bash
|
||||
crontab -l
|
||||
```
|
||||
|
||||
Deve mostrar algo como:
|
||||
```
|
||||
0 12 * * * TZ='America/Sao_Paulo' /usr/bin/node /home/tiago/Downloads/app_estoque_v1.0.0/scripts/enviar-alertas-parcelas.js >> /home/tiago/Downloads/app_estoque_v1.0.0/logs/alertas-cron.log 2>&1
|
||||
```
|
||||
|
||||
**Nota:** `0 12` em UTC = 09:00 em Brasília (UTC-3)
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Troubleshooting
|
||||
|
||||
### Problema: Alertas não são enviados
|
||||
|
||||
**Verificar:**
|
||||
|
||||
1. **Cron está instalado?**
|
||||
```bash
|
||||
crontab -l | grep enviar-alertas-parcelas
|
||||
```
|
||||
|
||||
2. **Script tem permissão de execução?**
|
||||
```bash
|
||||
ls -l scripts/enviar-alertas-parcelas.js
|
||||
chmod +x scripts/enviar-alertas-parcelas.js
|
||||
```
|
||||
|
||||
3. **Configurações estão corretas no admin?**
|
||||
- Evolution API configurada
|
||||
- Mercado Pago configurado
|
||||
- Alertas ATIVOS (toggles verdes)
|
||||
|
||||
4. **Clientes têm WhatsApp cadastrado?**
|
||||
```sql
|
||||
SELECT nome_completo, whatsapp
|
||||
FROM clientes
|
||||
WHERE whatsapp IS NULL OR whatsapp = '';
|
||||
```
|
||||
|
||||
5. **Parcelas estão com status "pendente"?**
|
||||
```sql
|
||||
SELECT * FROM venda_parcelas
|
||||
WHERE status = 'pendente'
|
||||
ORDER BY data_vencimento;
|
||||
```
|
||||
|
||||
6. **Ver logs de erro:**
|
||||
```bash
|
||||
tail -100 logs/alertas-cron.log
|
||||
```
|
||||
|
||||
### Problema: PIX não é gerado
|
||||
|
||||
**Verificar:**
|
||||
|
||||
1. **Mercado Pago Access Token configurado?**
|
||||
- Painel Admin → Configurações → Mercado Pago
|
||||
|
||||
2. **Token válido?**
|
||||
- Tokens expiram, gere um novo se necessário
|
||||
|
||||
3. **Testar geração manual:**
|
||||
- Sistema de Vendas → Parcelas → Botão "PIX"
|
||||
|
||||
### Problema: Mensagens não chegam
|
||||
|
||||
**Verificar:**
|
||||
|
||||
1. **Evolution API está online?**
|
||||
- Teste acessando a URL configurada
|
||||
|
||||
2. **Instância está conectada?**
|
||||
- Verifique no painel da Evolution API
|
||||
|
||||
3. **WhatsApp do cliente correto?**
|
||||
- Formato: apenas números (5543999762754)
|
||||
- Com DDD e código do país
|
||||
|
||||
4. **Testar envio manual:**
|
||||
- Sistema de Vendas → Chat WhatsApp
|
||||
|
||||
---
|
||||
|
||||
## 📅 Cronograma de Alertas
|
||||
|
||||
### Exemplo: Venda em 20/10, vencimento 24/10
|
||||
|
||||
| Data | Hora | Tipo de Alerta | Dias | Ação |
|
||||
|------|------|----------------|------|------|
|
||||
| 21/10 | 09:00 | Primeiro Alerta | -3 dias | Lembrete |
|
||||
| 24/10 | 09:00 | Segundo Alerta | 0 dia (hoje) | Lembrete + PIX |
|
||||
| 27/10 | 09:00 | Pós-Vencimento | +3 dias | Cobrança |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Desinstalar Cron
|
||||
|
||||
Se precisar remover o cron:
|
||||
|
||||
```bash
|
||||
crontab -e
|
||||
```
|
||||
|
||||
Remova a linha que contém `enviar-alertas-parcelas.js` e salve.
|
||||
|
||||
Ou automaticamente:
|
||||
|
||||
```bash
|
||||
crontab -l | grep -v 'enviar-alertas-parcelas' | crontab -
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Personalizar Mensagens
|
||||
|
||||
No painel admin → Configurações → Alertas WhatsApp
|
||||
|
||||
**Variáveis disponíveis:**
|
||||
- `{cliente}` - Primeiro nome do cliente
|
||||
- `{valor}` - Valor formatado (R$ 150,00)
|
||||
- `{quando}` - "em 3 dias", "hoje", "há 3 dias"
|
||||
- `{parcela}` - "1/3", "2/5", etc.
|
||||
|
||||
**Exemplo de mensagem personalizada:**
|
||||
```
|
||||
Oi {cliente}! 😊
|
||||
|
||||
Sua parcela {parcela} de {valor} vence {quando}.
|
||||
|
||||
Qualquer dúvida, estamos aqui!
|
||||
|
||||
*Liberi Kids* 👗👕
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Caso de Uso: Venda 20/10
|
||||
|
||||
**Configuração:**
|
||||
- Primeiro alerta: 3 dias antes ✅
|
||||
- Segundo alerta: No dia ✅
|
||||
- Pós-vencimento: 3 dias após ✅
|
||||
|
||||
**Timeline:**
|
||||
|
||||
| Dia | Evento |
|
||||
|-----|--------|
|
||||
| **20/10** | Venda realizada, parcela 1 vence 24/10 |
|
||||
| **21/10 09:00** | 🔔 Primeiro alerta enviado: "vence em 3 dias" |
|
||||
| **24/10 09:00** | 🔔 Segundo alerta + PIX: "vence hoje" + QR Code |
|
||||
| **27/10 09:00** | 🔔 Alerta pós-venc: "venceu há 3 dias" |
|
||||
|
||||
---
|
||||
|
||||
## ✅ Checklist de Verificação
|
||||
|
||||
Antes de considerar o sistema funcionando, verifique:
|
||||
|
||||
- [ ] Cron instalado e ativo (`crontab -l`)
|
||||
- [ ] Horário correto (09:00 Brasília = 12:00 UTC)
|
||||
- [ ] Evolution API configurada no admin
|
||||
- [ ] Mercado Pago configurado no admin
|
||||
- [ ] Alertas ATIVOS (toggles verdes)
|
||||
- [ ] Mensagens personalizadas configuradas
|
||||
- [ ] Teste manual executado com sucesso
|
||||
- [ ] Logs sendo gerados em `/logs/alertas-cron.log`
|
||||
- [ ] Clientes com WhatsApp cadastrado
|
||||
- [ ] Parcelas com status "pendente"
|
||||
|
||||
---
|
||||
|
||||
## 📞 Suporte
|
||||
|
||||
**Logs importantes:**
|
||||
```bash
|
||||
# Logs do cron
|
||||
tail -f logs/alertas-cron.log
|
||||
|
||||
# Logs do servidor
|
||||
tail -f logs/server.log
|
||||
|
||||
# Histórico de mensagens (SQL)
|
||||
SELECT * FROM mensagens_whatsapp
|
||||
ORDER BY created_at DESC
|
||||
LIMIT 50;
|
||||
|
||||
# Parcelas pendentes
|
||||
SELECT vp.*, v.id_venda, c.nome_completo, c.whatsapp
|
||||
FROM venda_parcelas vp
|
||||
JOIN vendas v ON vp.venda_id = v.id
|
||||
JOIN clientes c ON v.cliente_id = c.id
|
||||
WHERE vp.status = 'pendente'
|
||||
ORDER BY vp.data_vencimento;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Desenvolvido para: Liberi Kids - Moda Infantil** 👗👕
|
||||
**Data: 24 de outubro de 2025**
|
||||
**Versão: 1.0**
|
||||
**Status: ✅ Pronto para Produção**
|
||||
Reference in New Issue
Block a user