← Voltar ao índice

📣 BWC Pulse

Cockpit de marketing — analytics de redes sociais, Meta Ads e Funil Vivo (React Flow) com conversão ao vivo. Arquitetura MockAdapter→MetaAdapter sem tocar na UI.

URL: pulse.bwccorp.com.br
Frontend: Next.js 14
Banco: SQLite (Prisma)
Porta: 3050
Repo: local (git local, sem push)
Status: ✅ Rodando
Next.js 14 Prisma (SQLite) React Flow (@xyflow/react) Meta Graph API Meta Marketing API TypeScript

Especificação do Produto

Missão

Cockpit unificado de marketing: painel de redes sociais (Instagram, Facebook, YouTube, TikTok), Meta Ads com ROAS/CPC/CPA e alertas automáticos, e Funil Vivo — canvas React Flow com métricas ao vivo injetadas por adapter intercambiável (Mock → Meta) sem alterar a UI.

Usuários-alvo

Time de marketing BWC Corp — gestores de tráfego, analistas de redes sociais e diretores que acompanham funil de conversão ao vivo.

Infra

Systemd user service bwc-marketing.service — Caddy → 172.18.0.1:3050

Arquitetura de Adapter (MockAdapter → MetaAdapter)

A UI nunca fala com a Meta diretamente. Ela consome /api/metrics?keys=..., que delega a um MetricsAdapter plugável:

Para ir de Mock para Meta: setar META_ACCESS_TOKEN + META_IG_USER_ID/META_AD_ACCOUNT_ID no ambiente do serviço. Zero mudança de código.

Modelos Prisma (SQLite — 5 models)

Funnel — layout React Flow serializado em JSON (nodes + edges, com metas por estágio) · Snapshot — histórico de métricas por stageKey (comparativo semana a semana) · SocialAccount — contas de rede conectadas (instagram, facebook, youtube, tiktok) com followers/reach/engagement · Campaign — campanhas Meta Ads com spend/revenue/impressions/clicks/conversions · Diagram — diagramas livres (modo Lucid genérico) · Setting — configurações chave-valor (ex.: roas_alert_threshold)

Funil Vivo — features do canvas
Jobs Cron automatizados

Protegidos por CRON_SECRET via query param ?key=.... Notificações via sendTelegram().

Endpoints principais da API

Métricas do Funil — /api/metrics

GET /api/metrics?keys=ig_reach,leads,checkout,paid
Retorna valores atuais das métricas solicitadas via MetricsAdapter plugável. Resposta: { values: { stageKey: number }, at: ISO }. Fonte: Mock (dev) ou Meta real (quando credenciais presentes).

Status do Adapter — /api/status

GET /api/status
Informa qual fonte de dados está ativa. Resposta: { dataSource: "meta" | "mock", live: boolean }.

Redes Sociais — /api/social

GET /api/social
Lista contas de redes sociais conectadas com totais agregados. Resposta: { accounts: SocialAccount[], totals: { followers, reach, avgEngagement } }.

Meta Ads — /api/ads

GET /api/ads
Lista campanhas Meta Ads enriquecidas com ROAS, CPC, CPM, CTR, CPA e flag de alerta. Resposta: { campaigns, totals: { spend, revenue, conversions, blendedRoas }, threshold, alerts }. Alertas disparados quando campanha de conversão ativa fica abaixo do threshold de ROAS configurado.

Funil Vivo — /api/funnels

GET /api/funnels
Lista todos os funis salvos (id, name, updatedAt, data JSON com nodes + edges).
POST /api/funnels
Cria novo funil. Body: { name, data } onde data é o JSON serializado do canvas React Flow.
GET /api/funnels/:id
Retorna funil completo por ID.
PUT /api/funnels/:id
Atualiza layout do funil (salvar do canvas). Body: { name?, data? }.
DELETE /api/funnels/:id
Remove funil do banco.

Diagramas Livres — /api/diagrams

GET /api/diagrams
Lista diagramas genéricos (modo Lucid — sem métricas de funil).
POST /api/diagrams
Cria diagrama. Body: { name, data? }.
PUT /api/diagrams/:id
Atualiza diagrama.
DELETE /api/diagrams/:id
Remove diagrama.

Sync Meta — /api/sync

POST /api/sync
Puxa dados reais da Meta (Graph API + Marketing API) e grava no banco: upsert da conta Instagram, recriação de campanhas e snapshot de métricas. Retorna { ok, synced: { instagram, campaigns } }. Retorna 400 se credenciais não configuradas.

Relatório — /api/report

GET /api/report
Relatório analítico computado: score do funil, grade, gargalo (menor conversão entre estágios) e variações semana a semana (WoW) com base em snapshots históricos.

Configurações — /api/settings

GET /api/settings
Retorna todas as configurações como mapa chave-valor (ex.: roas_alert_threshold).
PUT /api/settings
Upsert de configuração. Body: { key, value }.

Jobs Cron — /api/cron/:job

POST /api/cron/snapshot
Grava snapshot das métricas atuais no banco para histórico WoW. Protegido por ?key=CRON_SECRET.
POST /api/cron/digest
Calcula score/grade/gargalo do funil e envia digest formatado via Telegram. Protegido por ?key=CRON_SECRET.
POST /api/cron/alerts
Detecta campanhas de conversão ativas abaixo do threshold de ROAS e envia alerta Telegram (com dedupe — não re-alerta campanhas já notificadas). Protegido por ?key=CRON_SECRET.

Saúde

GET /api/health
Healthcheck. Retorna status do servidor e conexão com banco.

Variáveis de Ambiente

DATABASE_URLCaminho do SQLite (ex.: file:./pulse.db) META_ACCESS_TOKENToken de system user da Meta (long-lived) com escopos: instagram_basic, instagram_manage_insights, pages_read_engagement, ads_read META_IG_USER_IDID da conta Instagram Business/Creator META_AD_ACCOUNT_IDID da conta de anúncios (só números, sem "act_") META_FB_PAGE_ID(Opcional) ID da página do Facebook META_GRAPH_VERSION(Opcional) Versão da Graph API — default v21.0 CRON_SECRETChave para proteger endpoints /api/cron/* via ?key=... TELEGRAM_BOT_TOKENToken do bot Telegram para alertas e digest TELEGRAM_CHAT_IDChat ID do destinatário das notificações
Sem META_ACCESS_TOKEN + META_IG_USER_ID/META_AD_ACCOUNT_ID o app roda em modo Mock — Funil Vivo "respira" com dados simulados, sem nenhuma chamada externa.

Arquitetura de Deploy

bwc-marketing.service (systemd user)
  └─ Next.js 14 (porta 3050)
       ↑
  Caddy Reverse Proxy → 172.18.0.1:3050
       ↑
  pulse.bwccorp.com.br (HTTPS — Cloudflare + Let's Encrypt)

Fonte de dados (plugável via env):
  MockMetricsAdapter  ←─ sem credenciais Meta (modo dev/demo)
  MetaMetricsAdapter  ←─ com META_ACCESS_TOKEN (modo produção)
       ↕
  ApiMetricsAdapter (FunilVivo.tsx → /api/metrics → adapter acima)

Jobs agendados (cron externo ou systemd timer):
  POST /api/cron/snapshot  → historico WoW
  POST /api/cron/digest    → Telegram digest diário
  POST /api/cron/alerts    → Telegram ROAS alert (dedupe)

Gerado automaticamente — BlackCat Corp • Voltar ao índice