bellinatiperez/mautic-campaign-watch-bundle

Monitor and fix orphan leads in Mautic campaigns

0.0.2 2025-11-28 03:37 UTC

Requires

• php: >=8.0

MIT

README

Plugin para monitoramento e correção de leads órfãos em campanhas do Mautic.

Descrição

O Campaign Watch identifica e gerencia leads que foram adicionados a campanhas mas não tiveram nenhum evento disparado (leads órfãos). Também monitora leads com múltiplas re-entradas em campanhas.

Funcionalidades

• Dashboard de Monitoramento: Visualização centralizada de estatísticas de campanhas
• Detecção de Leads Órfãos: Identifica leads sem eventos disparados
• Análise de Re-entradas: Monitora leads que re-entraram múltiplas vezes (3x+)
• Correção em Massa: Incrementa rotação de leads órfãos para forçar reprocessamento
• Ações Individuais: Corrigir ou remover leads específicos
• Exportação CSV: Exporta dados de órfãos e re-entradas
• Filtros: Por campanha e período (7, 14, 30, 60, 90 dias)
• Comando CLI: Verificação automatizada via cron

Instalação

1. Copie a pasta MauticCampaignWatchBundle para plugins/
2. Limpe o cache:

   php bin/console cache:clear

3. Acesse Configurações > Plugins e ative o plugin

Uso

Interface Web

Acesse via menu: Canais > Monitor de Campanhas

A interface exibe:

• Cards de Estatísticas: Campanhas ativas, total de leads, órfãos, re-entradas
• Tabela de Leads Órfãos: Lista paginada com ações
• Resumo de Re-entradas: Contagem por severidade (médio: 5-9x, alto: 10x+)

Ações Disponíveis

Ação	Descrição
Corrigir	Incrementa a rotação do lead para forçar reprocessamento
Remover	Remove o lead da campanha (marca como manually_removed)
Corrigir Todos	Corrige todos os órfãos da página atual
Exportar CSV	Baixa lista de órfãos ou re-entradas

Comando CLI

# Verificar leads órfãos (últimos 7 dias)
php bin/console mautic:campaigns:check-orphans

# Especificar período
php bin/console mautic:campaigns:check-orphans --days=30

# Campanha específica
php bin/console mautic:campaigns:check-orphans --campaign=123

# Corrigir automaticamente
php bin/console mautic:campaigns:check-orphans --fix

Tabelas do Banco de Dados

O plugin consulta as seguintes tabelas do Mautic:

Tabela	Uso
campaign_leads	Associação lead-campanha, flag manually_removed
campaign_lead_event_log	Histórico de eventos disparados
campaigns	Dados das campanhas
leads	Dados dos contatos

Estrutura de campaign_leads

-- Campos relevantes
lead_id          -- ID do contato
campaign_id      -- ID da campanha
manually_removed -- 1 = removido manualmente
manually_added   -- 1 = adicionado manualmente
rotation         -- Contador de re-entradas
date_added       -- Data de entrada
date_last_exited -- Data da última saída

Lógica de Detecção

Lead Órfão

Um lead é considerado órfão quando:

1. Está em campaign_leads com manually_removed = 0
2. Não possui nenhum registro em campaign_lead_event_log para a mesma campanha/rotação
3. Foi adicionado dentro do período de análise

Query de Detecção

SELECT cl.lead_id, cl.campaign_id, cl.rotation
FROM campaign_leads cl
LEFT JOIN campaign_lead_event_log clel
    ON cl.lead_id = clel.lead_id
    AND cl.campaign_id = clel.campaign_id
    AND cl.rotation = clel.rotation
WHERE cl.manually_removed = 0
    AND cl.date_added >= DATE_SUB(NOW(), INTERVAL ? DAY)
    AND clel.id IS NULL

Configuração de Cron

Para monitoramento automático, adicione ao crontab:

# Verificar órfãos diariamente às 6h
0 6 * * * php /path/to/mautic/bin/console mautic:campaigns:check-orphans --days=7

# Verificar e corrigir automaticamente
0 6 * * * php /path/to/mautic/bin/console mautic:campaigns:check-orphans --days=7 --fix

Traduções

O plugin inclui traduções para:

• Inglês (en_US)
• Português Brasil (pt_BR)

Estrutura do Plugin

MauticCampaignWatchBundle/
├── Command/
│   └── CheckOrphanLeadsCommand.php    # Comando CLI
├── Config/
│   └── config.php                      # Rotas, menu, serviços
├── Controller/
│   └── CampaignWatchController.php    # Controlador principal
├── Resources/
│   └── views/
│       └── CampaignWatch/
│           ├── index.html.twig        # Dashboard principal
│           └── campaign.html.twig     # Detalhes da campanha
├── Translations/
│   ├── en_US/
│   │   └── messages.ini
│   └── pt_BR/
│       └── messages.ini
├── MauticCampaignWatchBundle.php      # Classe do bundle
└── README.md

Requisitos

• Mautic 4.x / 5.x
• PHP 7.4+
• Acesso ao banco de dados (leitura/escrita em campaign_leads)

Licença

Proprietário - Uso interno

Changelog

v1.1.0

• Interface web com dashboard
• Filtros por campanha e período
• Ações de correção e remoção
• Exportação CSV
• Traduções PT-BR

v1.0.0

• Comando CLI para detecção de órfãos
• Correção automática via --fix