Tráfego que vende

Sistema multicliente de inteligência de tráfego pago. Conecta a conta de anúncios da Meta de cada cliente, cruza a mídia com as vendas e mostra quais anúncios trazem venda, não só clique ou conversa.

Stack: Next.js 16 (App Router), Supabase (Postgres com RLS, Auth, Storage, pgmq, pg_cron, pg_net, Vault) e Vercel.

O roteiro para validar o piloto (GN Coleciona, campanha de 3/11) está em docs/roteiro-teste-piloto.md.

Como está organizado

Pasta	O quê
supabase/migrations/	Esquema, RLS e funções. Toda tabela de dados tem organizacao_id, e o isolamento entre clientes é feito no banco.
src/lib/auth/sessao.ts	Quem está logado e com que papel (dono, gestor, leitura) em qual organização.
src/lib/integracoes/	Clientes da Meta (só leitura) e do Stripe.
src/lib/meta/sincronizacao.ts	Sincronização da Meta: fatiada por mês, retomável pelo cursor.
src/lib/vendas/	Entrada de leads e vendas, comum a todas as fontes (webhook, Stripe, CSV).
src/lib/rastreio/	Regras de rastreio e o teste de ponta a ponta.
src/lib/jobs/worker.ts	Worker da fila.
tests/banco/	Testes de RLS e das consultas num Postgres em memória (PGlite).

Instalação (uma vez)

1. Supabase

1. Crie um projeto em supabase.com (região São Paulo).

2. Em Authentication → Sign In / Providers:

   • desligue “Allow new users to sign up”: contas novas nascem só de convite;
   • deixe o provedor e-mail ligado.

3. Em Authentication → URL Configuration:

   • Site URL = o endereço do sistema (ex.: https://ads.seudominio.com.br);
   • acrescente https://ads.seudominio.com.br/** às Redirect URLs.

4. Aplique as migrações:

   npm install
   npx supabase login
   npm run db:vincular -- --project-ref <ref-do-projeto>
   npm run db:aplicar
   

   Elas criam as tabelas, o RLS, a fila jobs (pgmq), os agendamentos (pg_cron) e o bucket privado criativos.

5. No SQL Editor, crie os dois segredos que o agendador usa para acordar o worker:

   select vault.create_secret('https://ads.seudominio.com.br/api/jobs/processar', 'worker_url');
   select vault.create_secret('<mesmo valor de SEGREDO_WORKER>', 'worker_segredo');
   

2. Variáveis de ambiente

Copie .env.example para .env.local (desenvolvimento) e preencha as mesmas variáveis na Vercel (Settings → Environment Variables):

Variável	Onde pegar
NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY	Supabase → Project Settings → API
CHAVE_CIFRAGEM	Gere com node -e "console.log(require('crypto').randomBytes(32).toString('base64'))". Ela cifra as credenciais dos clientes. Guarde num cofre: se ela se perder, todas as conexões precisam ser cadastradas de novo.
SEGREDO_WORKER	Gere com o mesmo comando. Use o mesmo valor no segredo worker_segredo do Vault.
URL_SISTEMA	Endereço público do sistema
META_API_VERSION	v26.0

3. Vercel

Importe o repositório. É preciso o plano Pro: o worker roda até 5 minutos por chamada (maxDuration = 300), e o plano gratuito corta antes.

4. Primeiro administrador

npm run criar-admin -- [email protected]

Se a conta não existir, o comando a cria e mostra uma senha provisória uma vez.

Uso

Assistente de configuração

Em /o/<organização>/configurar, o assistente leva a pessoa por seis etapas: negócio, Meta, página de destino, fonte de venda, teste completo e resumo. Uma organização nova cai direto nele, e a tela Início mostra onde retomar.

O andamento não é marcado à mão: vem do que o sistema confere (src/lib/onboarding/modelo.ts). Um token removido, por exemplo, volta a aparecer como pendente. As respostas ficam em organizacoes.onboarding.

Cadastrar uma organização (cliente)

1. Entre como administrador e abra Administração (link na página inicial).
2. Informe o nome e o endereço (ex.: gn-coleciona). Você entra como dono da organização.
3. Em Configurações → Membros, convide as pessoas do cliente. O sistema gera um link válido por 7 dias para você mandar a elas; quem recebe cria a própria senha ao abrir.

Conectar a Meta

Em Configurações → Meta, cole o token de um usuário do sistema do portfólio empresarial do cliente, com ads_read e acesso à conta de anúncios. O passo a passo aparece na própria tela.

• O token é validado na hora (leitura de /me e /me/adaccounts) e guardado cifrado.
• Ligue a conta de anúncios e escolha a data de início do histórico. A carga entra na fila.
• Depois disso, a sincronização roda sozinha às 6h, 12h e 18h (horário de Brasília) e reescreve os últimos 7 dias, porque a Meta revisa conversões nessa janela.
• Em Configurações → O que conta como lead e compra, marque as ações da Meta que valem como lead. No GN Coleciona é o cadastro: offsite_conversion.fb_pixel_complete_registration. A lista mostra as ações que já apareceram nas campanhas.

Conectar a fonte de venda

Webhook genérico (qualquer site ou ferramenta de automação):

• Em Configurações → Webhook, gere o token. O endereço é POST /api/webhook/eventos, com Authorization: Bearer whk_….
• O formato aparece na tela: lead, teste_iniciado, venda e reembolso, um por vez ou { "eventos": [...] }.
• Reenviar o mesmo evento não duplica nada.

Stripe:

1. Crie uma chave restrita com leitura em Faturas, Assinaturas, Clientes e Cobranças.
2. Em Configurações → Stripe, cole a chave e informe o campo do metadata da assinatura que guarda o id do lead (no GN: user_id).
3. No Stripe, crie um destino de webhook com o endereço que a tela mostra e os eventos invoice.paid, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted e charge.refunded.
4. Cole o segredo whsec_… na tela e clique em Importar histórico para trazer os últimos 365 dias.

This is the beginning of the README. Read the rest at the original. Read the full README ↗