Afilium - Plataforma de Gestão de Afiliados

📋 Visão Geral

Afilium é uma plataforma completa de gestão de programa de afiliados, desenvolvida especificamente para integrar com e-commerces e automatizar todo o processo de gestão de afiliados, desde o cadastro até o pagamento de comissões.

🎯 Principais Funcionalidades

📊 Dashboard e Analytics

Dashboard personalizado para administradores e afiliados

Gráficos de desempenho de vendas e comissões

Análise de conversão e métricas de afiliados

Relatórios de afiliados ociosos e performance

👥 Gestão de Afiliados

Cadastro completo de afiliados com aprovação manual

Sistema de níveis de permissão (OWNER, AFFILIATE, MEMBER)

Controle de status (ACTIVE, INACTIVE, PENDING)

Perfis detalhados com informações pessoais e de pagamento

🔗 Sistema de Links

Geração automática de links de afiliados

Rastreamento de cliques em tempo real

Sistema de redirecionamento inteligente

Monitoramento de conversões

💰 Sistema de Comissões e Pagamentos

Cálculo automático de comissões por venda

Sistema de carteira digital para acúmulo de comissões

Processamento de pagamentos com comprovantes

Metas de comissão personalizáveis

📧 Sistema de Email Automático

Emails de boas-vindas para novos afiliados

Notificações de aprovação/rejeição de cadastro

Emails de suspensão de conta

Sistema de convites para novos afiliados

🏗️ Arquitetura Técnica

Stack Principal

Frontend: Next.js 14 + TypeScript + Tailwind CSS

Backend: Next.js API Routes + Prisma ORM

Banco de Dados: MySQL

Autenticação: NextAuth.js

Filas: RabbitMQ para processamento assíncrono

Email: Sistema próprio com fallback

Estrutura do Projeto

src/
├── app/                 # Rotas e páginas (App Router)
├── components/          # Componentes reutilizáveis
├── actions/            # Server Actions
├── lib/                # Utilitários e configurações
├── types/              # Definições de tipos TypeScript
├── services/           # Lógica de negócio
└── schemas/            # Validações Zod

docs/                   # Documentação técnica
prisma/                 # Schema do banco e migrações
scripts/                # Scripts de processamento

👥 Níveis de Permissão

OWNER (Proprietário)

Acesso total à plataforma

Gerenciamento de configurações da empresa

Aprovação/rejeição de afiliados

Gestão de pagamentos

Visualização de todos os relatórios

AFFILIATE (Afiliado)

Dashboard personalizado com suas métricas

Geração de links de afiliação

Visualização de comissões e vendas

Configuração de meta de comissão

Acesso ao sistema de carteira

MEMBER (Membro)

Status temporário antes da aprovação

Acesso limitado até aprovação do cadastro

📋 Regras de Negócio

Cadastro de Afiliados

Processo de Aprovação

Cadastro: Afiliado preenche formulário completo

Status PENDING: Aguarda aprovação manual

Análise: Administrador revisa dados pessoais e de atuação

Decisão: Aprovação (ACTIVE) ou Rejeição (INACTIVE)

Notificação: Email automático informando a decisão

Dados Obrigatórios

Informações pessoais completas (nome, CPF/CNPJ, nascimento)

Endereço completo com CEP

Dados de contato (email, telefone)

Informações de atuação (redes sociais, experiência)

Dados bancários para pagamento (PIX, banco)

Aceite dos termos de uso

Sistema de Comissões

Cálculo Automático

Percentual padrão: 12% sobre o valor da venda

Configurável por empresa através de CompanyConfigs

Status válidos para comissão: approved, paid, attended, invoiced, shipped, delivered

Processamento: Assíncrono via RabbitMQ

Acúmulo na Carteira

Comissões são creditadas automaticamente na carteira do afiliado

Saldo disponível para saque mediante solicitação

Histórico completo de transações

Regras para Afiliado Ocioso

Critérios de Classificação

Afiliado Ocioso: Mais de 60 dias sem vendas

Nunca Vendeu: Afiliados que nunca geraram uma venda

Dias Offline: Contagem desde último login na plataforma

Monitoramento Automático

Dashboard exibe afiliados ociosos em destaque

Alertas visuais para afiliados críticos

Relatórios detalhados de inatividade

Sistema de Pagamentos

Processo de Pagamento

Solicitação: Administrador inicia pagamento para afiliados com saldo

Validação: Sistema verifica saldo disponível na carteira

Processamento: Débito automático da carteira

Comprovante: Upload obrigatório do comprovante de pagamento

Status: Acompanhamento (PENDING → APPROVED → REJECTED)

Validações

Apenas afiliados ACTIVE podem receber pagamentos

Saldo mínimo para pagamento (configurável)

Dados bancários obrigatórios e validados

Controle de Cadastros

Habilitação/Desabilitação

Administradores podem pausar novos cadastros de afiliados

Configuração através de enableNewAffiliates em CompanyConfigs

Página de cadastro exibe mensagem quando desabilitado

🔄 Integrações

Bagy (E-commerce)

Webhook: Recebimento automático de pedidos

Processamento: Identificação de vendas por afiliado

Comissões: Cálculo e creditação automática

Status: Monitoramento em tempo real

RabbitMQ

Cliques: Processamento assíncrono de cliques em links

Vendas: Processamento de vendas e comissões

Carteira: Operações de crédito/débito

Retry: Sistema de reprocessamento automático

📈 Métricas e Relatórios

Dashboard do Administrador

Top afiliados por comissão e vendas

Afiliados ociosos e críticos

Gráficos de performance temporal

Links com baixa conversão

Dashboard do Afiliado

Meta de comissão mensal

Gráfico de comissões por período

Estatísticas de cliques e vendas

Saldo da carteira

🚀 Como Usar o Sistema

Para Administradores

Gerenciar Afiliados

Acesse "Afiliados" no menu principal

Visualize afiliados por status (Ativos, Ociosos, Pendentes)

Clique em um afiliado para ver detalhes completos

Aprove, rejeite ou desative conforme necessário

Processar Pagamentos

Acesse "Pagamentos" no menu

Visualize afiliados com saldo disponível

Selecione afiliados para pagamento

Faça o pagamento via PIX/transferência

Faça upload do comprovante

Configurar Sistema

Acesse "Configurações"

Ajuste percentual de comissão

Habilite/desabilite novos cadastros

Configure integrações

Para Afiliados

Começar a Divulgar

Acesse "Links" no dashboard

Gere seu link personalizado

Compartilhe em suas redes sociais

Acompanhe cliques e vendas

Acompanhar Performance

Visualize seu dashboard principal

Defina suas metas de comissão

Monitore seu progresso mensal

Consulte histórico de vendas

Solicitar Pagamento

Verifique saldo na carteira

Entre em contato com o administrador

Aguarde processamento

Receba via PIX/transferência

🔧 Configurações Avançadas

Variáveis de Ambiente

<h1>Banco de Dados</h1>
DATABASE_URL="mysql://user:pass@localhost:3306/afilium"

<h1>Autenticação</h1>
NEXTAUTH_SECRET="seu-secret-aqui"
NEXTAUTH_URL="http://localhost:3000"

<h1>Email</h1>
EMAIL_SERVER_HOST="smtp.gmail.com"
EMAIL_SERVER_USER="seu-email@gmail.com"
EMAIL_SERVER_PASSWORD="sua-senha-app"

<h1>Empresa</h1>
COMPANY_ID="uuid-da-empresa"

<h1>RabbitMQ</h1>
RABBITMQ_URL="amqp://localhost:5672"

Scripts Disponíveis

<h1>Desenvolvimento</h1>
npm run dev

<h1>Workers RabbitMQ</h1>
npm run wallet:worker
npm run link:sale-worker
npm run link:worker

<h1>Testes</h1>
npm run wallet:test
npm run link:sale-test
npm run link:redirect-test

� Documentação Completa

Documentos Disponíveis

Regras de Negócio - Detalhamento completo das regras do sistema

Guia do Usuário - Manual para administradores e afiliados

Guia de Implantação - Configuração e deploy da aplicação

Visão Técnica - Arquitetura e detalhes técnicos

Sistema de Email - Configuração de emails automáticos

Sistema de Redirecionamento - Como funcionam os links de afiliado

Documentos Técnicos Específicos

RabbitMQ e Filas - Sistema de processamento assíncrono

Configuração Hostinger - Setup específico de email

Guia de Uso dos Links - Como testar redirecionamentos

�📞 Suporte

Para dúvidas sobre o funcionamento do sistema:

Documentação: Consulte os documentos na pasta /docs

Logs do Sistema: Monitore via console ou arquivos de log

Status das Filas: Use npm run rabbitmq:logs

Testes: Execute scripts de teste para validar funcionamento

--- Versão: 0.1.0 Última Atualização: Julho 2025

Regras de Negócio - Afilium

📊 Gestão de Afiliados

Estados dos Afiliados

PENDING (Pendente)

Descrição: Status inicial após cadastro

Ações disponíveis:

Visualizar dados completos

Aprovar → ACTIVE

Rejeitar → INACTIVE

Restrições:

Não pode gerar links

Não recebe comissões

Não pode acessar dashboard completo

ACTIVE (Ativo)

Descrição: Afiliado aprovado e operacional

Ações disponíveis:

Gerar links de afiliação

Receber comissões

Acessar dashboard completo

Solicitar pagamentos

Pode ser alterado para:

INACTIVE (desativação)

INACTIVE (Inativo)

Descrição: Afiliado desativado ou rejeitado

Restrições:

Não pode gerar novos links

Links existentes ainda funcionam

Não pode acessar sistema

Pode ser alterado para:

ACTIVE (reativação)

Critérios de Aprovação

Dados Obrigatórios Validados

✅ Nome completo

✅ CPF/CNPJ válido e único

✅ Email válido e único

✅ Data de nascimento

✅ Telefone/WhatsApp

✅ Endereço completo com CEP

✅ Rede social principal

✅ Dados bancários para pagamento

Perfis de Atuação Aceitos

Influenciador Digital: Criadores com audiência estabelecida

Criador de Conteúdo: Produtores de conteúdo digital

Cliente Divulgador: Clientes satisfeitos que divulgam

Revendedor: Pessoas que revendem produtos

Métodos de Divulgação

Stories em redes sociais

Posts no feed

Lista de contatos (WhatsApp/Email)

Outros métodos específicos

💰 Sistema de Comissões

Cálculo de Comissões

Percentual Base

Padrão: 12% sobre o valor total da venda

Configurável: Administrador pode alterar via CompanyConfigs

Aplicação: Automática em todos os novos pedidos

Status de Pedidos Válidos

Apenas pedidos com os seguintes status geram comissão:

approved - Pagamento aprovado

paid - Pagamento realizado

attended - Pedido atendido

invoiced - Nota fiscal emitida

shipped - Pedido enviado

delivered - Pedido entregue

Exclusões

Pedidos pending, voided, denied, expired, refunded, chargeback NÃO geram comissão

Processamento Automático

Webhook de Vendas

E-commerce (Bagy) envia webhook com dados do pedido

Sistema valida se venda possui afiliado válido

Se payment_status = "approved", processa comissão

Envia para fila RabbitMQ para processamento assíncrono

Worker processa e credita na carteira do afiliado

Rastreamento de Links

URL formato: afilium.com?affid=UUID&linkid=UUID

Registro automático de cliques

Incremento no contador de cliques do link

Associação da venda ao link quando houver conversão

📈 Métricas de Performance

Afiliados Ociosos

Definições

Afiliado Ocioso: Mais de 60 dias sem vendas

Nunca Vendeu: Afiliado que nunca gerou uma venda

Crítico: Afiliado ocioso há mais de 90 dias

Monitoramento

Dashboard exibe lista de afiliados ociosos

Classificação por gravidade (cores)

Relatórios automáticos de inatividade

Alertas visuais para administradores

Metas de Comissão

Funcionalidade

Cada afiliado pode definir meta mensal

Padrão: R$ 1.000,00 por mês

Dashboard mostra progresso em tempo real

Cálculo baseado em pedidos válidos do mês

Cálculo do Progresso

progressPercentage = (comissaoAtual / metaComissao) * 100;
restantePraMeta = metaComissao - comissaoAtual;

🏦 Sistema de Pagamentos

Processo de Pagamento

Etapa 1: Validação

Afiliado deve estar ACTIVE

Deve ter saldo > 0 na carteira

Dados bancários devem estar completos

Etapa 2: Solicitação

Administrador acessa "Pagamentos"

Seleciona afiliados com saldo

Sistema calcula valor total disponível

Etapa 3: Processamento

Débito automático da carteira

Criação de registro UserPayment

Status inicial: PENDING

Etapa 4: Comprovação

Administrador faz transferência/PIX

Upload do comprovante obrigatório

Status alterado para APPROVED

Métodos de Pagamento Aceitos

PIX: Método preferencial

Transferência Bancária: Para valores maiores

Dados obrigatórios: Nome, CPF, banco, chave PIX

🔐 Controle de Acesso

Níveis de Permissão

OWNER (Proprietário)

Gerenciar todos os afiliados

Aprovar/rejeitar cadastros

Processar pagamentos

Configurar sistema

Visualizar todos os relatórios

Gerenciar integrações

AFFILIATE (Afiliado)

Gerar links de afiliação

Visualizar próprias métricas

Configurar meta de comissão

Consultar saldo da carteira

Atualizar dados pessoais

MEMBER (Membro Temporário)

Status pré-aprovação

Acesso muito limitado

Não pode realizar ações principais

Proteções de Segurança

Autenticação obrigatória para todas as ações

Validação de propriedade dos dados

Logs de auditoria para ações críticas

Proteção contra alteração de dados sensíveis

🚫 Regras de Bloqueio

Cadastro de Novos Afiliados

Controle Centralizado

Configuração enableNewAffiliates em CompanyConfigs

Administrador pode pausar novos cadastros

Página de cadastro exibe mensagem quando bloqueado

Casos de Uso

Período de ajustes no programa

Capacidade máxima de afiliados atingida

Revisão de estratégia comercial

Desativação de Afiliados

Motivos Válidos

Violação dos termos de uso

Inatividade prolongada

Práticas inadequadas de divulgação

Solicitação do próprio afiliado

Consequências

Perda de acesso ao sistema

Links existentes ainda funcionam (mantém vendas históricas)

Saldo da carteira preservado

Possibilidade de reativação futura

📧 Comunicações Automáticas

Emails Transacionais

Novo Cadastro

Para afiliado: Email de boas-vindas

Para admin: Notificação de novo cadastro pendente

Aprovação

Para afiliado: Email de aprovação com instruções de acesso

Conteúdo: Link de login e primeiros passos

Rejeição

Para afiliado: Email informando rejeição

Conteúdo: Motivo (se especificado) e possibilidade de novo cadastro

Suspensão

Para afiliado: Email informando suspensão temporária

Conteúdo: Motivo e instruções para regularização

Sistema de Convites

Afiliados podem convidar outros

Email personalizado com mensagem do afiliado

Link direto para cadastro com referência

--- Importante: Todas estas regras são implementadas no código e devem ser respeitadas durante o uso da plataforma.

Guia do Usuário - Afilium

👨‍💼 Para Administradores

🏠 Dashboard Principal

Visão Geral

O dashboard do administrador oferece uma visão completa da performance do programa de afiliados:

Métricas Principais: Total de afiliados, vendas, comissões pagas

Gráficos de Performance: Vendas por período, top afiliados

Alertas: Afiliados ociosos, pendências de aprovação

Ações Rápidas: Aprovar afiliados, processar pagamentos

👥 Gestão de Afiliados

Visualizar Afiliados

Menu: Navegue para "Afiliados"

Filtros: Use as abas para filtrar por status:

Ativos: Afiliados operacionais

Ociosos: Sem vendas há mais de 60 dias

Inativos: Desativados ou rejeitados

Pendentes: Aguardando aprovação

Aprovar Novo Afiliado

Acesse: Aba "Pendentes" em Afiliados

Selecione: Clique no afiliado para ver detalhes

Analise: Revise todas as informações:

Dados pessoais completos

Experiência como afiliado

Métodos de divulgação

Dados bancários para pagamento

Decisão: Clique em "Aprovar Afiliado" ou "Rejeitar"

Confirmação: Sistema envia email automático

Gerenciar Afiliado Ativo

Localizar: Encontre o afiliado na lista de ativos

Detalhes: Clique para ver informações completas

Ações disponíveis:

Desativar: Suspende acesso temporariamente

Conferir Vendas: Visualiza histórico de vendas

Ver Performance: Métricas detalhadas

💳 Processamento de Pagamentos

Visualizar Afiliados com Saldo

Menu: Acesse "Pagamentos"

Lista: Veja afiliados com saldo disponível

Filtros: Use checkbox "Apenas com saldo" para facilitar

Processar Pagamento Individual

Selecionar: Marque o afiliado desejado

Criar Pagamento: Clique em "Criar Pagamento"

Confirmar: Revise dados bancários do afiliado

Efetuar: Faça a transferência/PIX

Comprovar: Faça upload do comprovante

Finalizar: Status muda para "Aprovado"

Pagamento em Lote

Seleção Múltipla: Marque vários afiliados

Ou use: "Selecionar todos com saldo"

Processar: Clique em "Criar Pagamentos"

Individual: Cada pagamento deve ser comprovado separadamente

⚙️ Configurações do Sistema

Ajustar Comissões

Menu: Acesse "Configurações"

Comissão Padrão: Altere o percentual base (ex: 12%)

Aplicação: Afeta apenas novos pedidos

Histórico: Vendas antigas mantêm percentual original

Controlar Novos Cadastros

Configurações: Encontre "Cadastro de Afiliados"

Habilitar/Desabilitar: Toggle para permitir novos cadastros

Efeito: Página de cadastro fica indisponível quando desabilitado

Gerenciar Integrações

Bagy: Verificar status da integração

RabbitMQ: Monitorar filas de processamento

Email: Testar envio de emails

📊 Relatórios e Análises

Dashboard de Métricas

Top Afiliados: Por comissão e vendas

Afiliados Ociosos: Lista com dias de inatividade

Gráficos: Performance temporal do programa

Análise de Performance

Links com Baixa Conversão: Identificar problemas

Tendências: Crescimento ou declínio do programa

ROI: Retorno sobre investimento em afiliados

---

🎯 Para Afiliados

🏠 Dashboard Pessoal

Primeira Visualização

Após aprovação do cadastro, você terá acesso ao seu dashboard com:

Meta de Comissão: Progresso mensal (padrão: R$ 1.000)

Saldo da Carteira: Comissões acumuladas

Gráficos: Suas vendas e comissões por período

Links Ativos: Quantos links você já gerou

🔗 Gerar e Gerenciar Links

Criar Seu Primeiro Link

Menu: Acesse "Links" ou "Gerar Link"

Título: Dê um nome para identificar (ex: "Instagram Stories")

URL Base: Sistema usa automaticamente a URL da empresa

Gerar: Clique para criar seu link único

Copiar: Use o link gerado para divulgação

Formato do Link

Seu link terá o formato:

afilium.com?affid=SEU_ID&linkid=ID_DO_LINK

Acompanhar Performance

Cliques: Quantas pessoas clicaram no link

Vendas: Quantas vendas foram geradas

Taxa de Conversão: Percentual de cliques que viraram vendas

📈 Acompanhar Vendas e Comissões

Dashboard de Vendas

Gráficos: Visualize suas vendas por período

Detalhes: Veja valor, data e comissão de cada venda

Filtros: Por mês, trimestre ou ano

Sistema de Carteira

Saldo Atual: Comissões disponíveis para saque

Histórico: Todas as transações (entradas/saídas)

Previsão: Comissões pendentes de pedidos em processamento

🎯 Configurar Metas

Definir Meta de Comissão

Dashboard: Encontre widget "Meta de Comissão"

Editar: Clique no ícone de edição

Valor: Defina sua meta mensal (ex: R$ 2.000)

Salvar: Confirme a alteração

Acompanhar: Dashboard mostra progresso em tempo real

💰 Solicitar Pagamentos

Quando Solicitar

Tenha saldo mínimo na carteira

Dados bancários atualizados

Status ATIVO na plataforma

Como Solicitar

Contato: Entre em contato com administrador

Via Email: Use email cadastrado na plataforma

Informações: Confirme dados bancários/PIX

Aguardar: Processamento pode levar até 48h úteis

Dados Necessários

Nome completo: Para transferência

CPF: Mesmo do cadastro

Chave PIX: Email, telefone ou CPF

Banco: Se preferir transferência

📱 Estratégias de Divulgação

Redes Sociais

Instagram Stories: Use stickers de "Link" ou "Swipe Up"

Feed Posts: Fotos com produtos e call-to-action

Reels: Vídeos demonstrando produtos

WhatsApp Status: Para contatos próximos

Lista de Contatos

WhatsApp: Envio individual ou listas de transmissão

Email: Newsletter para sua base de contatos

Telegram: Grupos ou canais próprios

Conteúdo Eficaz

Experiência Pessoal: Conte como o produto te ajudou

Demonstração: Mostre o produto em uso

Benefícios: Foque no valor para o cliente

Call-to-Action: Convite claro para clicar

🛡️ Boas Práticas

Transparência

Sempre informe que é um link de afiliado

Seja honesto sobre sua experiência com o produto

Não faça promessas exageradas

Compliance

Respeite os termos de uso da plataforma

Não use métodos de spam ou invasivos

Mantenha seus dados sempre atualizados

Performance

Teste diferentes abordagens e horários

Acompanhe quais tipos de conteúdo convertem mais

Foque em qualidade de tráfego, não apenas quantidade

---

🆘 Suporte e Dúvidas

Para Administradores

Logs do Sistema: Console do navegador + servidor

Documentação Técnica: Pasta /docs do projeto

Monitoramento: RabbitMQ logs para filas

Para Afiliados

Suporte: Entre em contato via email cadastrado

FAQ: Consulte seção de perguntas frequentes

Tutorial: Refira-se a este guia para dúvidas comuns

Problemas Comuns

"Meu link não está funcionando"

Verifique se copiou o link completo

Teste o link em navegador anônimo

Confirme se seu status está ATIVO

"Não recebi comissão por uma venda"

Verifique se o cliente usou seu link

Confirme se o pedido foi aprovado/pago

Comissões podem levar até 24h para aparecer

"Não consigo acessar o sistema"

Confirme se seu cadastro foi aprovado

Verifique email e senha

Tente recuperar senha se necessário

--- Lembre-se: Este guia cobre as principais funcionalidades. Para dúvidas específicas, entre em contato com o suporte.

Configuração e Implantação - Afilium

🚀 Configuração Inicial

📋 Pré-requisitos

Software Necessário

Node.js: Versão 18 ou superior

MySQL: Versão 8.0 ou superior

Docker: Para RabbitMQ (opcional mas recomendado)

Git: Para versionamento do código

Contas e Serviços

Servidor de Email: Gmail, SendGrid, ou similar

Hospedagem: Vercel, Netlify, ou servidor próprio

Banco de Dados: MySQL local ou cloud (PlanetScale, AWS RDS)

⚙️ Configuração do Ambiente

1. Variáveis de Ambiente

Crie arquivo .env.local na raiz do projeto:

<h1>Banco de Dados MySQL</h1>
DATABASE_URL="mysql://usuario:senha@localhost:3306/afilium"

<h1>NextAuth - Autenticação</h1>
NEXTAUTH_SECRET="gere-um-secret-seguro-aqui"
NEXTAUTH_URL="http://localhost:3000"

<h1>Configuração da Empresa</h1>
COMPANY_ID="uuid-da-sua-empresa"

<h1>Email (Gmail App Password recomendado)</h1>
EMAIL_SERVER_HOST="smtp.gmail.com"
EMAIL_SERVER_PORT="587"
EMAIL_SERVER_USER="seu-email@gmail.com"
EMAIL_SERVER_PASSWORD="sua-app-password"
EMAIL_FROM="seu-email@gmail.com"

<h1>RabbitMQ (Docker recomendado)</h1>
RABBITMQ_URL="amqp://localhost:5672"

<h1>Opcional - Para integração Bagy</h1>
BAGY_API_KEY="sua-api-key-bagy"

2. Instalação de Dependências

<h1>Instalar dependências</h1>
npm install

<h1>Gerar Prisma Client</h1>
npx prisma generate

3. Configuração do Banco de Dados

<h1>Executar migrações</h1>
npx prisma migrate deploy

<h1>(Opcional) Seed inicial</h1>
npx prisma db seed

🐳 Docker - RabbitMQ

Inicializar RabbitMQ

<h1>Subir container RabbitMQ</h1>
npm run rabbitmq:up

<h1>Verificar logs</h1>
npm run rabbitmq:logs

<h1>Parar quando necessário</h1>
npm run rabbitmq:down

Interface Web RabbitMQ

URL: http://localhost:15672

Usuário: guest

Senha: guest

📧 Configuração de Email

Gmail (Recomendado)

Ativar 2FA na sua conta Google

Gerar App Password:

Google Account → Security → App passwords

Selecione "Mail" e gere a senha

Usar a senha gerada na variável EMAIL_SERVER_PASSWORD

Outros Provedores

SendGrid: Use API Key como password

Hostinger: Configure SMTP com credenciais da hospedagem

Outlook: Similar ao Gmail com App Password

🏗️ Estrutura de Implantação

📱 Aplicação Principal

Desenvolvimento

<h1>Servidor de desenvolvimento</h1>
npm run dev

<h1>Acesso local</h1>
http://localhost:3000

Produção - Vercel (Recomendado)

Conectar repositório no dashboard Vercel

Configurar variáveis de ambiente no painel

Deploy automático a cada push na branch main

Produção - Servidor Próprio

<h1>Build da aplicação</h1>
npm run build

<h1>Iniciar em produção</h1>
npm run start

🔄 Workers de Background

Configuração dos Workers

Os workers processam filas RabbitMQ em background:

<h1>Worker de carteira (comissões)</h1>
npm run wallet:worker

<h1>Worker de vendas (processamento)</h1>
npm run link:sale-worker

<h1>Worker de cliques (futuro uso)</h1>
npm run link:worker

Supervisão em Produção

Use PM2 para gerenciar workers em produção:

<h1>Instalar PM2 globalmente</h1>
npm install -g pm2

<h1>Configurar ecosystem</h1>
pm2 ecosystem

<h1>Iniciar todos os processos</h1>
pm2 start ecosystem.config.js

<h1>Monitorar</h1>
pm2 monit

Exemplo ecosystem.config.js

module.exports = {
  apps: [
    {
      name: 'afilium-app',
      script: 'npm',
      args: 'start',
      env: {
        NODE_ENV: 'production',
        PORT: 3000,
      },
    },
    {
      name: 'afilium-wallet-worker',
      script: 'scripts/wallet-worker.mjs',
      env: {
        NODE_ENV: 'production',
      },
    },
    {
      name: 'afilium-sale-worker',
      script: 'scripts/link-sale-worker.mjs',
      env: {
        NODE_ENV: 'production',
      },
    },
  ],
};

🔧 Configurações Avançadas

🏢 Configuração da Empresa

Dados Iniciais da Empresa

-- Inserir empresa no banco (MySQL)
INSERT INTO Company (id, name) VALUES ('seu-company-id', 'Nome da Empresa');

-- Configurações padrão
INSERT INTO CompanyConfigs (
  id,
  companyId,
  comissionPercent,
  defaultPercent,
  enableNewAffiliates
) VALUES (
  UUID(),
  'seu-company-id',
  0.12,
  0.12,
  true
);

Primeiro Usuário Administrador

-- Criar usuário admin
INSERT INTO User (
  id,
  email,
  password,
  firstName,
  lastName
) VALUES (
  UUID(),
  'admin@empresa.com',
  '$2b$12$hash-da-senha-aqui',
  'Admin',
  'Sistema'
);

-- Associar à empresa como OWNER
INSERT INTO CompanyAdministrators (
  id,
  userId,
  companyId,
  role
) VALUES (
  UUID(),
  'user-id-acima',
  'seu-company-id',
  'OWNER'
);

🔗 Configuração de Integrações

Integração Bagy

-- Adicionar integração Bagy
INSERT INTO CompanyIntegrations (
  id,
  companyId,
  name,
  origin,
  status,
  apiKey
) VALUES (
  UUID(),
  'seu-company-id',
  'Integração Bagy',
  'BAGY',
  'ACTIVE',
  'sua-api-key-bagy'
);

Webhook Bagy

Configure no painel Bagy:

URL: https://seu-dominio.com/api/webhook/bagy/order-received-by-store

Eventos: Pedidos criados/atualizados

Autenticação: Conforme documentação Bagy

📊 Monitoramento e Logs

Logs da Aplicação

<h1>Logs em desenvolvimento</h1>
npm run dev

<h1>Logs dos workers</h1>
npm run wallet:worker
npm run link:sale-worker

<h1>Logs RabbitMQ</h1>
npm run rabbitmq:logs

Monitoramento em Produção

PM2 Monitoring: pm2 monit

RabbitMQ Management: Interface web para filas

Logs de Sistema: /var/log ou logs da aplicação

🛡️ Segurança

Práticas Recomendadas

HTTPS: Sempre em produção

Firewall: Restringir acesso ao banco e RabbitMQ

Backup: Backup automático do banco de dados

Secrets: Nunca commitar variáveis sensíveis

Configuração HTTPS

Vercel: HTTPS automático

Servidor Próprio: Use Nginx + Let's Encrypt

Cloudflare: SSL gratuito

🔄 Backup e Recuperação

Backup do Banco

<h1>Backup MySQL</h1>
mysqldump -u usuario -p afilium > backup-$(date +%Y%m%d).sql

<h1>Restauração</h1>
mysql -u usuario -p afilium < backup-20250101.sql

Backup de Arquivos

Uploads: Backup da pasta /public/uploads

Configurações: Backup do arquivo .env

Código: Repository Git como backup

📈 Otimização de Performance

🗄️ Banco de Dados

-- Índices importantes já estão no schema.prisma
-- Monitorar queries lentas
SHOW PROCESSLIST;

-- Otimizar tabelas periodicamente
OPTIMIZE TABLE Order, UserAffiliate, GeneratedLink;

🔄 RabbitMQ

Persistent Messages: Mensagens sobrevivem a reinicializações

Dead Letter Queues: Mensagens que falharam múltiplas vezes

Clustering: Para alta disponibilidade

🌐 CDN e Cache

Next.js: Cache automático de páginas estáticas

Cloudflare: CDN para assets estáticos

Vercel: Edge caching automático

🧪 Testes

Testar Configuração

<h1>Testar conexão com banco</h1>
npx prisma db push

<h1>Testar email</h1>
node scripts/test-email-connection.js

<h1>Testar workers</h1>
npm run wallet:test
npm run link:sale-test

<h1>Testar redirecionamento</h1>
npm run link:redirect-test

Validar Integração

Webhook Bagy: Enviar pedido de teste

Email: Cadastrar afiliado teste

RabbitMQ: Verificar processamento de filas

Links: Testar geração e redirecionamento

---

📞 Troubleshooting

Problemas Comuns

"Cannot connect to database"

Verificar DATABASE_URL

Confirmar que MySQL está rodando

Testar conexão: npx prisma db push

"RabbitMQ connection failed"

Verificar se Docker está rodando

Conferir RABBITMQ_URL

Reiniciar container: npm run rabbitmq:down && npm run rabbitmq:up

"Email não está sendo enviado"

Verificar credenciais de email

Confirmar App Password (Gmail)

Testar: node scripts/test-email-connection.js

"Workers não processam filas"

Verificar se workers estão rodando

Conferir logs dos workers

Reiniciar: pm2 restart all

Logs de Debug

<h1>Habilitar logs detalhados</h1>
export DEBUG=*

<h1>Logs específicos do Prisma</h1>
export DEBUG="prisma:query"

<h1>Logs do RabbitMQ</h1>
export DEBUG="amqp*"

--- Importante: Mantenha sempre backup dos dados e teste as configurações em ambiente de desenvolvimento antes de aplicar em produção.

Visão Técnica - Afilium

🏗️ Arquitetura do Sistema

Stack Tecnológico

Frontend

Next.js 14: Framework React com App Router

TypeScript: Tipagem estática para maior robustez

Tailwind CSS: Framework CSS utilitário

Radix UI: Componentes acessíveis e customizáveis

React Hook Form: Gerenciamento de formulários

Zod: Validação de esquemas e dados

Backend

Next.js API Routes: Endpoints REST integrados

Prisma ORM: Object-Relational Mapping para MySQL

NextAuth.js: Autenticação completa

Server Actions: Actions server-side do Next.js

RabbitMQ: Sistema de filas para processamento assíncrono

Infraestrutura

MySQL: Banco de dados principal

Docker: Containerização (RabbitMQ)

Vercel: Plataforma de deploy (recomendada)

Email Service: Gmail SMTP ou similar

🔄 Fluxo de Dados

Cadastro de Afiliado

sequenceDiagram
    participant U as Usuário
    participant F as Frontend
    participant API as API Routes
    participant DB as MySQL
    participant E as Email Service

    U->>F: Preenche formulário
    F->>API: POST /api/affiliate/register
    API->>DB: Valida e cria UserAffiliate
    API->>DB: Cria User (se não existir)
    API->>DB: Cria CompanyAdministrator
    API->>E: Envia email de boas-vindas
    API->>F: Retorna sucesso
    F->>U: Confirma cadastro

Processamento de Venda

sequenceDiagram
    participant Bagy as E-commerce
    participant W as Webhook
    participant RQ as RabbitMQ
    participant Worker as Sale Worker
    participant DB as MySQL
    participant Wallet as Wallet Service

    Bagy->>W: POST /webhook/order-received
    W->>DB: Valida afiliado e link
    W->>RQ: Envia para fila de vendas
    Worker->>RQ: Consome mensagem
    Worker->>DB: Atualiza contadores
    Worker->>Wallet: Credita comissão
    Wallet->>DB: Registra transação

🗄️ Estrutura do Banco de Dados

Entidades Principais

User

Propósito: Usuários do sistema (afiliados e admins)

Chaves: id (UUID), email (unique)

Relacionamentos: 1:1 com UserAffiliate, 1:N com Order

UserAffiliate

Propósito: Dados específicos do afiliado

Status: PENDING → ACTIVE/INACTIVE

Campos críticos: document, paymentPix, comissionGoal

Order

Propósito: Pedidos do e-commerce

Origem: Webhook Bagy

Comissão: Calculada automaticamente

UserWallet

Propósito: Carteira digital do afiliado

Precisão: Decimal(15,2) para valores monetários

Transações: Histórico completo em WalletTransaction

🔐 Relacionamentos e Integridade

Cascade Deletes

User → UserAffiliate (CASCADE)

User → Order (CASCADE)

UserAffiliate → UserPayment (CASCADE)

Índices Estratégicos

-- Performance crítica
INDEX(userId) ON UserAffiliate
INDEX(affiliateId) ON Order
INDEX(transactionId) ON WalletTransaction
INDEX(status) ON UserAffiliate

🔧 Serviços e Camadas

Services Layer

WalletService

Local: /src/services/wallet.service.ts

Responsabilidades:

Creditar/debitar valores

Consultar saldos

Registrar transações

Validar operações

LinkClickService

Local: /src/services/link-click.service.ts

Responsabilidades:

Processar cliques em links

Incrementar contadores

Registrar metadados

LinkSaleService

Local: /src/services/link-sale.service.ts

Responsabilidades:

Processar vendas

Calcular comissões

Atualizar métricas

MailProvider

Local: /src/lib/email.ts

Funcionalidades:

Sistema de fallback

Templates React Email

Retry automático

Actions Layer

Server Actions

Local: /src/actions/

Vantagens:

Execução server-side

Type-safe

Integração com forms

Principais Actions

// Afiliados
createAffiliate();
activateAffiliate();
deactivateAffiliate();

// Pagamentos
createPayment();
uploadPaymentProof();
updatePaymentStatus();

// Charts e relatórios
getCommissionData();
getIdleAffiliates();
getTopAffiliates();

🔄 Sistema de Filas (RabbitMQ)

Configuração das Filas

Queue: link-sales

Propósito: Processar vendas de afiliados

Worker: scripts/link-sale-worker.mjs

Status: Ativo

DLQ: link-sales-dlq (Dead Letter Queue)

Queue: link-clicks

Propósito: Processar cliques em links

Worker: scripts/link-click-worker.mjs

Status: Implementado mas não utilizado

DLQ: link-clicks-dlq

Queue: wallet-operations

Propósito: Operações da carteira

Worker: scripts/wallet-worker.mjs

Status: Ativo

DLQ: wallet-operations-dlq

Configuração Robusta

// Durabilidade
durable: true,
persistent: true,

// Retry
deadLetterExchange: 'dlx',
messageTtl: 60000,
maxRetries: 3,

// Acknowledgment
noAck: false,
prefetch: 1

🔒 Autenticação e Autorização

NextAuth.js Setup

Providers

Credentials: Email/senha

Database: Prisma adapter

Session: JWT strategy

Session Structure

interface Session {
  user: {
    id: string;
    email: string;
    name: string;
    role: UserRoles;
    companyId: string;
  };
}

Middleware de Proteção

// /src/middleware.ts
export function middleware(request: NextRequest) {
  // Protege rotas baseado em role
  // Redireciona não-autenticados
  // Valida permissões por página
}

Hooks de Autenticação

// useUser hook
const { user, isLoading, role } = useUser()

// Verificação de permissão
if (role !== 'OWNER') {
  return <Unauthorized />
}

📊 Sistema de Métricas

Queries Otimizadas

Dashboard Afiliado

// Comissão mensal com performance
const orders = await prisma.order.findMany({
  where: {
    affiliateId: userId,
    createdAt: { gte: startOfMonth, lte: endOfMonth },
    status: { in: VALID_STATUSES },
  },
  select: { comission: true }, // Apenas campos necessários
});

Top Afiliados

// Aggregation eficiente
const topAffiliates = await prisma.order.groupBy({
  by: ['affiliateId'],
  _sum: { comission: true },
  orderBy: { _sum: { comission: 'desc' } },
  take: 5,
});

Caching Strategy

Next.js: Automatic static caching

Database: Query result caching

API: Response caching headers

🧪 Testes e Qualidade

Scripts de Teste

<h1>Teste completo do sistema</h1>
npm run test:all

<h1>Testes específicos</h1>
npm run wallet:test
npm run link:sale-test
npm run link:redirect-test

Validação de Dados

// Zod schemas para validação
const affiliateSchema = z.object({
  fullname: z.string().min(2),
  email: z.string().email(),
  document: z.string().min(11),
  // ... outros campos
});

// Validação server-side
const validatedData = affiliateSchema.parse(formData);

Error Handling

// Padrão de resposta
interface ApiResponse<T> {
  success: boolean;
  data: T | null;
  error?: string;
}

// Try-catch consistente
try {
  const result = await operation();
  return { success: true, data: result };
} catch (error) {
  return { success: false, error: error.message, data: null };
}

🚀 Performance e Otimização

Database Optimization

Índices estratégicos em campos de busca frequente

Pagination para listas grandes

Select específico para reduzir payload

Connection pooling via Prisma

Frontend Optimization

Code splitting automático Next.js

Image optimization next/image

Lazy loading de componentes pesados

Memoization de cálculos complexos

API Optimization

Server Actions para reduzir round-trips

Streaming para dados grandes

Caching de responses frequentes

Debouncing em busca/filtros

🔧 Desenvolvimento e Debug

Environment Setup

<h1>Desenvolvimento local</h1>
npm run dev          # Aplicação
npm run wallet:worker # Worker carteira
npm run link:sale-worker # Worker vendas
npm run rabbitmq:up  # RabbitMQ container

Debug Tools

Prisma Studio: npx prisma studio

RabbitMQ Management: http://localhost:15672

Next.js DevTools: Browser extension

Console logs: Structured logging

Hot Reload

Frontend: Automático com Next.js

Workers: Reinicialização manual necessária

Database: Migrate + generate

📈 Monitoramento em Produção

Métricas Importantes

Response time das APIs

Queue length do RabbitMQ

Database connections ativas

Memory usage dos workers

Error rate por endpoint

Alertas Recomendados

Fila RabbitMQ muito cheia (>1000 msgs)

Taxa de erro alta (>5%)

Worker offline por >5 minutos

Banco de dados inacessível

Logs Estruturados

// Formato consistente
console.log('🔄 Processing sale:', {
  orderId,
  affiliateId,
  commission: comission.toNumber(),
  timestamp: new Date().toISOString(),
});

--- Importante: Esta documentação técnica deve ser atualizada conforme o sistema evolui. Mantenha sempre sincronizada com o código atual.

Sistema de Envio de Emails - Afilium

Este documento descreve como usar o sistema de envio de emails implementado no projeto Afilium.

📁 Estrutura dos Arquivos

Arquivos Criados:

src/app/api/test/send-mail/route.ts - Rota API para teste de envio de emails

src/components/mail/test-email.tsx - Componente React para template de email

public/test-email.html - Interface web para testar o envio de emails

🚀 Como Usar

1. Configuração do Ambiente

Certifique-se de que as seguintes variáveis de ambiente estão configuradas no seu arquivo .env:

EMAIL_SERVER_HOST=smtp.gmail.com
EMAIL_SERVER_PORT=587
EMAIL_SERVER_USER=seu-email@gmail.com
EMAIL_SERVER_PASSWORD=sua-senha-de-app
EMAIL_FROM=seu-email@gmail.com

2. Testando via Interface Web

Inicie o servidor de desenvolvimento:

   npm run dev
   

Acesse: http://localhost:3000/test-email.html

Preencha o formulário e clique em "Enviar Email de Teste"

3. Testando via API

Requisição POST:

curl -X POST http://localhost:3000/api/test/send-mail \
  -H "Content-Type: application/json" \
  -d '{
    "to": "destinatario@email.com",
    "name": "Nome do Usuário",
    "subject": "Assunto do Email"
  }'

Requisição GET (informações da API):

curl http://localhost:3000/api/test/send-mail

🎨 Criando Novos Templates de Email

1. Criar um novo componente React

Crie um arquivo em src/components/mail/ usando o padrão:

import {
  Body,
  Button,
  Container,
  Head,
  Html,
  Img,
  Text,
  Section,
} from '@react-email/components';
import * as React from 'react';

interface MeuEmailProps {
  nome?: string;
  // outras props...
}

export const MeuEmail = ({ nome = 'Usuário' }: MeuEmailProps) => (
  <Html>
    <Head />
    <Body>
      <Container>
        <Section>
          <Text>Olá {nome}!</Text>
          {/<em> Seu conteúdo aqui </em>/}
        </Section>
      </Container>
    </Body>
  </Html>
);

export default MeuEmail;

2. Usar o template no código

import { render } from '@react-email/render';
import { MailProvider } from '@/lib/email';
import MeuEmail from '@/components/mail/meu-email';

// Renderizar o template
const emailHtml = render(
  MeuEmail({
    nome: 'João Silva',
    // outras props...
  }),
);

// Enviar o email
await MailProvider.sendMail(
  'destinatario@email.com',
  'Assunto do Email',
  emailHtml,
);

📚 Bibliotecas Utilizadas

@react-email/components - Componentes React para criação de emails

@react-email/render - Renderização de componentes React para HTML

nodemailer - Envio de emails

🔍 Estrutura da Resposta da API

Sucesso (200):

{
  "message": "Email enviado com sucesso!",
  "messageId": "unique-message-id"
}

Erro (400):

{
  "error": "Email de destino é obrigatório"
}

Erro (500):

{
  "error": "Erro interno do servidor ao enviar email"
}

🛠️ Troubleshooting

Erro de Autenticação SMTP

Verifique se está usando uma "Senha de App" para Gmail

Confirme se a autenticação de 2 fatores está ativada

Teste as credenciais com outro cliente de email

Email não é recebido

Verifique a pasta de spam/lixo eletrônico

Confirme se o domínio do remetente não está bloqueado

Teste com diferentes provedores de email

Sistema de Redirecionamento Afilium

Visão Geral

O sistema de redirecionamento do Afilium permite que links afiliados sejam rastreados automaticamente. Quando um usuário acessa afilium.com com parâmetros específicos, o sistema registra o clique e redireciona para o site de destino.

Como Funciona

1. URL de Entrada

afilium.com?affid=uuid&linkid=uuid

Parâmetros:

affid: ID do afiliado (UUID)

linkid: ID do link gerado (UUID)

2. Redirecionamento

O sistema redireciona automaticamente para:

https://www.itwigs.com.br/?affid=123456&linkid=987654321

3. Registro de Clique

Antes do redirecionamento, o sistema:

Registra o clique na fila RabbitMQ

Atualiza o contador de cliques na tabela GeneratedLink

Armazena metadados como IP, User-Agent e timestamp

Arquivos Modificados

/src/app/page.tsx

Página principal que captura os parâmetros

Realiza o redirecionamento automático

Chama a API para registrar o clique

/src/app/api/link-click/route.ts

API endpoint para registrar cliques

Valida parâmetros e chama o serviço de cliques

Retorna status da operação

/src/middleware.ts

Atualizado para permitir acesso à página raiz com parâmetros

Mantém redirecionamento padrão para usuários autenticados

Serviços Utilizados

LinkClickService

O serviço já existente processa os cliques de forma assíncrona:

Envia mensagens para a fila RabbitMQ

Atualiza contador de cliques na base de dados

Garante consistência através de transações

RabbitMQ

Sistema de filas para processamento assíncrono:

Fila: LINK_CLICK_QUEUES.LINK_CLICKS

Garante que todos os cliques sejam processados

Implementa retry em caso de falhas

Exemplo de Uso

Link Original: https://www.itwigs.com.br/produto/123

Link Gerado: Armazenado na tabela GeneratedLink com ID único

Link de Afiliado: afilium.com?affid=uuid-afiliado&linkid=uuid-link

Acesso: Usuário clica no link de afiliado

Processamento: Sistema registra clique e redireciona

Resultado: Usuário é redirecionado para https://www.itwigs.com.br/?affid=uuid-afiliado&linkid=uuid-link

Monitoramento

Logs

Cliques são logados com detalhes completos

Erros são capturados e enviados para Dead Letter Queue

Métricas disponíveis através do linkClickService.getLinkStats()

Base de Dados

Tabela GeneratedLink mantém contador de cliques

Campo clicks é incrementado a cada clique válido

Timestamps são atualizados para rastreamento

Considerações de Performance

Redirecionamento é imediato (client-side)

Registro de clique é assíncrono

Sistema suporta alta concorrência através de filas

Transações garantem consistência dos dados

Segurança

Validação de parâmetros UUID

Rate limiting pode ser implementado no middleware

Logs completos para auditoria

Metadados incluem IP e User-Agent para tracking

Sistema de Links com RabbitMQ (Cliques e Vendas)

Este documento explica como funciona o sistema de processamento assíncrono de cliques e vendas em links usando RabbitMQ.

Visão Geral

O sistema foi implementado para garantir que todos os cliques e vendas em links de afiliados sejam processados corretamente, mesmo em caso de alta carga ou falhas temporárias. Utilizamos RabbitMQ para processar os eventos de forma assíncrona e confiável. Status atual:

✅ Sistema de Vendas: Ativo - processa vendas quando payment_status = "approved"

🔄 Sistema de Cliques: Implementado mas comentado no código (pronto para uso futuro)

Arquitetura

Componentes

Webhook API (/api/webhook/bagy/order-received-by-store/route.ts)

Recebe eventos de pedidos

Envia vendas para a fila RabbitMQ quando pagamento aprovado

Sistema de cliques comentado (pronto para ativação)

Não bloqueia o processamento do pedido

Link Sale Service (/src/services/link-sale.service.ts) - ATIVO

Gerencia as operações de venda

Processa mensagens da fila de vendas

Atualiza contadores de vendas no banco de dados

Link Click Service (/src/services/link-click.service.ts) - STANDBY

Sistema pronto mas não utilizado no momento

Pode ser ativado removendo comentários do webhook

Worker Processes

/scripts/link-sale-worker.mjs - ATIVO - processa vendas

/scripts/link-click-worker.mjs - STANDBY - pronto para cliques

RabbitMQ Configuration (/src/lib/rabbitmq.ts)

Configuração das filas para cliques e vendas

Dead Letter Queues para mensagens falhadas

Retry automático

Fluxo de Processamento

Sistema de Vendas (Ativo)

graph TD
    A[Webhook Recebe Pedido] --> B[Verifica Status Pagamento]
    B --> C{Status = 'approved'?}
    C -->|Sim| D[Identifica Link]
    C -->|Não| E[Log: Venda não processada]
    D --> F[Envia para Fila de Vendas]
    F --> G[Worker Processa Venda]
    G --> H[Incrementa sales no DB]
    H --> I[Confirma Processamento]

    G --> J[Falha no Processamento]
    J --> K[Retry Automático]
    K --> L[Dead Letter Queue]

Sistema de Cliques (Standby)

graph TD
    A[Webhook Recebe Pedido] --> B[Identifica Link]
    B --> C[Envia para Fila de Cliques]
    C --> D[Worker Processa Clique]
    D --> E[Incrementa clicks no DB]
    E --> F[Confirma Processamento]

    D --> G[Falha no Processamento]
    G --> H[Retry Automático]
    H --> I[Dead Letter Queue]

Comandos Disponíveis

Inicializar RabbitMQ

npm run wallet:init

Configura todas as filas necessárias (wallet + link clicks + link sales).

Workers Disponíveis

Sistema de Vendas (Ativo)

npm run link:sale-worker  # Executa worker de vendas
npm run link:sale-test    # Testa sistema de vendas

Sistema de Cliques (Standby)

npm run link:worker       # Executa worker de cliques
npm run link:test         # Testa sistema de cliques

Sistema de Carteira

npm run wallet:worker     # Executa worker de carteira
npm run wallet:test       # Testa sistema de carteira

Gerenciar RabbitMQ

npm run rabbitmq:up    # Inicia RabbitMQ
npm run rabbitmq:down  # Para RabbitMQ
npm run rabbitmq:logs  # Visualiza logs

Vantagens do Sistema

1. Confiabilidade

Mensagens são persistidas no RabbitMQ

Retry automático em caso de falha

Dead Letter Queue para análise de problemas

2. Performance

Processamento assíncrono não bloqueia webhook

Scaling horizontal com múltiplos workers

Controle de throughput com prefetch

3. Observabilidade

Logs detalhados de processamento

Métricas de fila no RabbitMQ Management

Transações únicas para auditoria

4. Consistência

Transações de banco para operações atômicas

Exactly-once processing com acknowledgment

Ordenação de mensagens garantida

Configuração de Produção

Environment Variables

RABBITMQ_URL=amqp://user:pass@rabbitmq:5672

Docker Compose

O RabbitMQ já está configurado no docker-compose.yml com:

Management UI na porta 15672

Persistência de dados

Configuração de usuário/senha

Deployment

Executar npm run wallet:init após deploy

Manter workers rodando como serviços:

Obrigatório: npm run link:sale-worker (sistema de vendas)

Opcional: npm run link:worker (sistema de cliques)

Opcional: npm run wallet:worker (sistema de carteira)

Monitorar filas via Management UI

Configurar alertas para DLQ

Status dos Sistemas

✅ Sistema de Vendas (Ativo)

Trigger: payment_status === 'approved'

Ação: Incrementa sales no generatedLink

Worker: link:sale-worker

Fila: link.sales

🔄 Sistema de Cliques (Standby)

Trigger: Comentado no webhook

Ação: Incrementaria clicks no generatedLink

Worker: link:worker

Fila: link.clicks

Para Ativar: Descomentar bloco no webhook

Troubleshooting

Ver Status das Filas

Acesse: http://localhost:15672

Usuário: user

Senha: pass

Reprocessar Mensagens Falhadas

// Exemplo de reprocessamento via código
import { rabbitMQService } from './src/lib/rabbitmq.js';

await rabbitMQService.reprocessFromDLQ('link.sales.dlq', 'link.sales');
// ou
await rabbitMQService.reprocessFromDLQ('link.clicks.dlq', 'link.clicks');

Logs Importantes

Worker logs: Processamento de cada mensagem

Webhook logs: Envio para fila

RabbitMQ logs: Status das filas

Monitoring

Métricas Importantes

Taxa de processamento de mensagens

Tamanho das filas

Mensagens na DLQ

Tempo de processamento

Health Checks

Worker deve logar status a cada 5 minutos

Verificar conexão RabbitMQ

Monitorar uso de memória dos workers

Migração do Sistema Anterior

Sistema de Vendas (Implementado)

Antes (síncrono):

// Sistema anterior não tinha controle de vendas por link

Depois (assíncrono com RabbitMQ):

// Novo sistema processa vendas quando pagamento aprovado
if (order_details.payment_status === 'approved') {
  await linkSaleService.processLinkSale({
    linkId: generatedLink.id,
    metadata: { orderId, affiliateId, paymentStatus, ... }
  });
}

Sistema de Cliques (Preparado)

Antes (síncrono):

await prisma.generatedLink.update({
  where: { id: generatedLink.id },
  data: { clicks: { increment: 1 } },
});

Depois (assíncrono com RabbitMQ - comentado):

await linkClickService.processLinkClick({
  linkId: generatedLink.id,
  metadata: { orderId, affiliateId, ... }
});

Como Ativar Sistema de Cliques

Para ativar o sistema de cliques, descomente o bloco no webhook:

Abrir src/app/api/webhook/bagy/order-received-by-store/route.ts

Descomentar o bloco de cliques (linhas ~82-98)

Executar o worker: npm run link:worker

Isso garantirá que tanto vendas quanto cliques sejam processados de forma assíncrona e confiável.

Configuração de Email - Hostinger

🔧 Configurações Recomendadas para Hostinger

Variáveis de Ambiente (.env)

EMAIL_SERVER_HOST="smtp.hostinger.com"
EMAIL_SERVER_PORT=465
EMAIL_SERVER_USER="suporte@seudominio.com"
EMAIL_SERVER_PASSWORD="sua-senha-do-email"
EMAIL_FROM="suporte@seudominio.com"

Configurações Alternativas

Se a porta 465 não funcionar, tente a porta 587:

EMAIL_SERVER_HOST="smtp.hostinger.com"
EMAIL_SERVER_PORT=587
EMAIL_SERVER_USER="suporte@seudominio.com"
EMAIL_SERVER_PASSWORD="sua-senha-do-email"
EMAIL_FROM="suporte@seudominio.com"

📋 Checklist de Configuração

1. Verificar o Email na Hostinger

[ ] Email foi criado no painel da Hostinger

[ ] Email está ativo e funcionando

[ ] Você consegue fazer login no webmail

2. Configurações de DNS

Certifique-se de que os registros MX estão corretos:

Tipo: MX
Nome: @
Valor: mx1.hostinger.com
Prioridade: 5
TTL: 14400

Tipo: MX
Nome: @
Valor: mx2.hostinger.com
Prioridade: 10
TTL: 14400

3. Configurações de Segurança

[ ] Senha do email está correta

[ ] Não há bloqueio de IP no servidor

[ ] Firewall não está bloqueando a conexão

🧪 Testes de Conectividade

Teste Rápido via API

curl http://localhost:3000/api/test/email-connection

Teste com Script Node.js

node test-email-connection.js

Teste via Interface Web

Acesse: http://localhost:3000/test-email.html

Preencha seu email nos campos

Clique em "Enviar Email de Teste"

🔍 Resolução de Problemas

Erro: "Authentication failed"

Verifique se o email e senha estão corretos

Confirme se o email está ativo na Hostinger

Teste o login no webmail da Hostinger

Erro: "Connection timeout"

Verifique se o host está correto: smtp.hostinger.com

Teste com porta 587 se 465 não funcionar

Verifique se o firewall não está bloqueando

Erro: "Certificate error"

A configuração rejectUnauthorized: false deve resolver

Certifique-se de que está usando SSL (secure: true) para porta 465

Erro: "Mail command failed"

Verifique se o domínio do EMAIL_FROM está correto

Confirme se o domínio está ativo e verificado

📞 Suporte Hostinger

Se os problemas persistirem:

Chat/Ticket Hostinger: Pergunte sobre:

Configurações SMTP específicas

Bloqueios de IP

Limites de envio

Verificações Adicionais:

Teste o email via cliente de email (Outlook, Thunderbird)

Verifique logs do servidor da Hostinger

Confirme se não há limite de envio atingido

🚀 Próximos Passos

Após configurar corretamente:

Execute o teste de conectividade

Envie um email de teste

Verifique se o email chegou (incluindo spam)

Configure templates personalizados

Implemente sistema de filas se necessário

📊 Limites da Hostinger

Verifique os limites do seu plano:

Emails por hora

Emails por dia

Tamanho máximo de anexos

Número de destinatários simultâneos

Sistema de Redirecionamento - Guia de Uso

Como Funciona

O sistema de redirecionamento foi implementado para automaticamente:

Capturar cliques em links afiliados

Registrar estatísticas na base de dados

Redirecionar para o site de destino

URLs de Teste

Formato da URL

afilium.com?affid=<UUID_DO_AFILIADO>&linkid=<UUID_DO_LINK>

Exemplo

http://localhost:3000?affid=123e4567-e89b-12d3-a456-426614174000&linkid=987fcdeb-51a2-43d1-b123-426614174001

Como Testar

1. Executar o Servidor

npm run dev

2. Testar com Script Automatizado

npm run link:redirect-test

3. Teste Manual

Acesse o link com parâmetros válidos

Observe o redirecionamento para itwigs.com.br

Verifique os logs no console

Confirme o incremento de cliques na base de dados

Monitoramento

Logs do Servidor

Cliques registrados aparecem no console

Erros são logados com detalhes completos

Transaction IDs permitem rastreamento

Base de Dados

-- Verificar cliques de um link específico
SELECT id, title, clicks, updatedAt
FROM GeneratedLink
WHERE id = 'seu-link-id';

-- Ver links mais clicados
SELECT id, title, clicks, updatedAt
FROM GeneratedLink
ORDER BY clicks DESC
LIMIT 10;

RabbitMQ

Filas processam cliques de forma assíncrona

Dead Letter Queue captura falhas

Retry automático para errors temporários

Fluxo Técnico

Middleware: Verifica se há parâmetros affid e linkid

Página Principal: Captura parâmetros e inicia processamento

API de Clique: Registra clique na fila RabbitMQ

Worker Assíncrono: Processa fila e atualiza base de dados

Redirecionamento: Cliente é redirecionado para destino final

Possíveis Problemas

Link Não Encontrado

Erro 400: linkId é obrigatório

Verificar se o link existe na tabela GeneratedLink

RabbitMQ Indisponível

Erro 500: Falha ao processar clique

Verificar se RabbitMQ está rodando: npm run rabbitmq:up

Worker Não Processando

Verificar se worker está ativo: npm run link:worker

Monitorar logs para erros de processamento

Scripts Úteis

<h1>Subir RabbitMQ</h1>
npm run rabbitmq:up

<h1>Inicializar filas</h1>
npm run wallet:init

<h1>Executar worker de cliques</h1>
npm run link:worker

<h1>Testar sistema completo</h1>
npm run link:redirect-test

<h1>Ver logs do RabbitMQ</h1>
npm run rabbitmq:logs

Estrutura de Arquivos Criados/Modificados

src/app/page.tsx - Página de redirecionamento

src/app/api/link-click/route.ts - API para registrar cliques

src/middleware.ts - Permite acesso com parâmetros

scripts/test-redirect-system.mjs - Script de teste

docs/redirect-system.md - Documentação técnica