Módulo: Marketing (Campanhas & Disparos)

Resumo operacional (o que importa)

Tabela base marketing (campanha: título + mensagem + anexos + status)
Fila disparos (cada linha = 1 envio pendente/agendado)
Segmentação grupos_disparos + vínculos de clientes (ex.: grupos_clientes)
API/Config tabela config (endpoint/token/instância, dependendo da instalação)

Fluxo padrão do BarberBot: cria campanha → disparar → gera registros em disparos → um processo/rotina (cron/worker) consome essa fila e faz as chamadas HTTP para a API configurada.

Estrutura de arquivos (onde mexer)

Caminho	Responsabilidade
`sistema/painel/paginas/marketing.php`	Tela do módulo (UI + JS). Controla filtros, cria campanha e dispara para listas/grupos.
`sistema/painel/paginas/marketing/`	Endpoints do módulo (CRUD + fila + uploads/anexos).
`sistema/painel/paginas/grupos_disparos.php`	Tela de grupos/segmentação de disparos (lista de grupos e vínculo de clientes).
`sistema/painel/paginas/grupos_disparos/`	Endpoints do cadastro de grupos + vínculo/importação de clientes + status.

Regra do projeto: telas (*.php na raiz de paginas/) fazem chamadas AJAX para endpoints dentro das subpastas. Ex.: marketing.php → chama marketing/listar.php, marketing/salvar.php, marketing/disparar.php.

sistema/painel/paginas/
  ├─ marketing.php
  ├─ marketing/
  │   ├─ listar.php
  │   ├─ salvar.php
  │   ├─ excluir.php
  │   ├─ disparar.php
  │   ├─ parar_envios.php
  │   ├─ api_parar_disparos.php
  │   ├─ listar_clientes.php
  │   ├─ marketing_texto.php
  │   ├─ marketing_foto.php
  │   ├─ marketing_audio.php
  │   ├─ excluir_imagem.php
  │   ├─ excluir_audio.php
  │   └─ excluir_doc.php
  │
  ├─ grupos_disparos.php
  └─ grupos_disparos/
      ├─ listar.php
      ├─ salvar.php
      ├─ excluir.php
      ├─ mudar-status.php
      ├─ listar_clientes.php
      ├─ add_clientes.php
      ├─ excluir_cliente.php
      └─ importar_clientes.php

Tabelas envolvidas (MySQL)

marketing — cadastro da campanha (título, mensagem, anexos, status).
disparos — fila de envio (cada registro representa um envio individual).
grupos_disparos — grupos/segmentos (ex.: “Clientes VIP”, “Aniversariantes”).
grupos_clientes (ou equivalente) — vínculo cliente ⇄ grupo (nome pode variar na instalação).
config — configurações gerais / API (token/url/instância conforme o projeto).

Ponto crítico: disparos cresce rápido. Índices por status, data, id_marketing e cliente evitam lentidão.

Endpoints e contratos (AJAX)

Importante: o front costuma comparar strings literais. Não mude mensagens de retorno sem ajustar o JS.

Marketing (campanhas)

Endpoint	Método	Parâmetros	Retorno esperado
`marketing/listar.php`	POST	`busca` (filtro texto)	HTML da listagem
`marketing/salvar.php`	POST + FILES	POST: `id`, `titulo`, `msg`, `msg2` FILES: `foto`, `audio`, `documento`	`Salvo com Sucesso` (insert) `Editado com Sucesso` (update)
`marketing/excluir.php`	POST	`id`	`Excluído com Sucesso`
`marketing/excluir_imagem.php`	POST	`id`	`Excluído com Sucesso`
`marketing/excluir_audio.php`	POST	`id`	`Excluído com Sucesso`
`marketing/excluir_doc.php`	POST	`id`	`Excluído com Sucesso`

Disparos (montagem/controle da fila)

Endpoint	Método	Parâmetros	Retorno esperado
`marketing/disparar.php`	POST	`id`, `clientes`, `data`, `hora`, `dispositivos`	`Salvo com Sucesso` (gera a fila em `disparos`)
`marketing/parar_envios.php`	POST	`id` (campanha)	`Parado com Sucesso`
`marketing/listar_clientes.php`	POST	`clientes` (lista/seleção)	`0` ou número total (texto puro)
`marketing/api_parar_disparos.php`	interno	—	Rotina auxiliar (pode chamar API externa dependendo da instância)

Grupos de disparo (segmentação)

Endpoint	Método	Parâmetros	Retorno esperado
`grupos_disparos/listar.php`	POST	`busca`	HTML da listagem
`grupos_disparos/salvar.php`	POST	`id`, `nome`	`Salvo com Sucesso` ou `Grupo já Cadastrado!`
`grupos_disparos/excluir.php`	POST	`id`	`Excluído com Sucesso`
`grupos_disparos/mudar-status.php`	POST	`id`, `acao`	`Alterado` / `ID inválido`
`grupos_disparos/add_clientes.php`	POST	`grupo`, `id` (cliente)	`Adicionado com Sucesso` / `Cliente já Adicionado!`
`grupos_disparos/excluir_cliente.php`	POST	`id` (vínculo)	`Excluído com Sucesso`
`grupos_disparos/importar_clientes.php`	POST	`grupo`, `cliente` (ou parâmetros do import)	HTML/retorno do processo de importação

Fila de disparos (como funciona)

Usuário cria/edita campanha em marketing (texto + anexos).
Ao disparar, o sistema executa marketing/disparar.php.
Esse endpoint insere N registros em disparos (N = quantidade de clientes-alvo).
Um processo (cron/worker) consulta disparos pendentes e envia via API (WhatsApp) usando dados de config.
Ao parar envios, marketing/parar_envios.php interrompe/ajusta status da campanha/fila (conforme regra do seu banco).

Debug rápido: se “não dispara”, verifique se criou registros em disparos. Se criou e não enviou, o problema está no worker/cron/API.

Pontos críticos e segurança

Mensagens literais: retornos como Salvo com Sucesso são contrato com o JS. Não altera no chute.
Uploads: validar MIME/extensão e garantir que a pasta de upload não executa PHP (Apache/Nginx).
Fila grande: paginar listagens e indexar campos do disparos.
Permissão: endpoint de disparo/parar envio é fluxo crítico: validar sessão/permissão antes do SQL.
SQL: preferir PDO->prepare() com bind (onde tiver concatenação de busca, cuidado com injection).

Checklist de debug (sem enrolação)

Campanha salva? (tabela marketing tem registro?)
Clicou disparar? (endpoint marketing/disparar.php retornou Salvo com Sucesso?)
Gerou fila? (tabela disparos tem linhas para essa campanha?)
Worker/cron está rodando? (consome disparos pendentes?)
Config da API existe? (tabela config / token / baseUrl / dispositivo ativo)
Se anexos falham: permissões de pasta + validação de upload + caminho gravado no banco.