Arquitetura Geral do Módulo comercial
01Renderizando diagrama Mermaid...
CRM moldado para a empresa Clubinho Corações Preciosos visando integrar equipe comercial, SDR com IA em um CRM sob medida para a operação
CRM comercial orientado a eventos que orquestra a Bia (WhatsApp), closers e pagamentos AppMax em um funil de 8 etapas
O Clubinho Corações Preciosos vende assinaturas de livros infantis cristãos para famílias. O negócio não escala com planilhas e WhatsApp manual: cada abandono de checkout exige timing certo (áudio, conversa, link, follow-up humano), cada assinante anual precisa ser contactado antes do vencimento, e cada cobrança Pix recorrente precisa de lembrete sem misturar com a esteira de vendas.
O desafio era construir uma operação comercial integrada — não um CRM genérico — que orquestre pessoas, automação e IA em três frentes distintas, sem que um lead de prospecção receba mensagem de renovação, sem que a Bia venda para quem já é cliente, e sem que pagamento confirmado se perca entre webhooks reenviados.
A solução é uma plataforma orientada a eventos: cada ação externa (abandono, resposta no WhatsApp, link enviado, pagamento AppMax, vencimento de ciclo, Pix a vencer) entra como evento, é processada com idempotência e move o lead na máquina de estados correta. O time opera em filas e kanbans; a Bia conduz a fase automática; closers assumem quando a automação esgota o prazo.
Problema: leads abandonam o checkout e esfriam em minutos. Sem cadência e sem handoff claro, o time perde conversões recuperáveis.
O que faz: recuperação de carrinho abandonado em oito etapas (F1-01 Capturado → F1-08 Convertido). A jornada combina automação (Reportana, Bia) e trabalho humano (closers na Fila do Dia).
Fluxo em linhas gerais:
F1-01.F1-02.F1-03.F1-04.F1-05 (a Bia para de vender).F1-06.F1-07.F1-08.Telas: Dashboard executivo, Fila do Dia, Kanban do Funil 1, Leads, Performance comercial, Inteligência de conversas (objeções detectadas por IA), Cadência, Templates, Integrações.
Diferencial: a Bia consulta o CRM antes de cada turno (can_sell: false para clientes ativos). A cadência tem quatro trilhas (silencioso, inatividade na conversa, pós-link, handoff humano), cada uma ancorada na etapa em que o lead está.
Problema: assinantes anuais precisam renovar antes do vencimento. Sem esteira dedicada, renovação compete com prospecção, números comerciais ficam poluídos e o closer não sabe quem priorizar.
O que faz: esteira isolada para clientes ativos com ciclo em subscription_cycles (data de vencimento, número de renovação, plano). Leads do F3 não aparecem na busca global nem no dashboard comercial do F1; vendas de renovação usam is_renovacao = true.
Etapas: F3-01 Vencimento próximo → F3-02 Oferta 1 (valor cheio) → F3-03 Oferta 2 (cupom RENOVA10) → F3-04 Oferta 3 (pagamento inteligente) → F3-05 Renovado, F3-06 Perdido ou F3-07 Bloqueado.
Régua operacional (relativa ao vencimento):
F3-06 Perdido.Entrada na esteira: varredura diária a D-30, importação CSV da base de renovação, ou entrada manual. O CRM avança a etapa conforme o calendário; os toques são manuais na Fila Renovação (prioridade para vencidas e toques pendentes).
Telas: Fila Renovação, Kanban Funil 3, Dashboard Renovação, Importar base.
Problema: assinantes no Pix recorrente precisam de lembrete antes e depois do vencimento, sem misturar com leads em prospecção ou renovação anual.
O que faz: pipeline totalmente separado na tabela crm.cobrancas, sem funil de vendas — kanban próprio C-01 / C-02 / C-03.
Fluxo:
Registros de telefones ainda no funil de vendas são removidos do pipeline; pagos antigos saem do kanban operacional.
Tela: Cobranças (kanban + realtime).
O CRM não é “formulário que guarda status”. É um motor de eventos onde a etapa do lead é consequência do que aconteceu — nunca atualizada manualmente por integrações externas.
| Princípio | O que garante na prática |
|---|---|
| Idempotência | Webhook reenviado não duplica lead nem venda (idempotency_key única). |
| Imutabilidade | eventos_lead não aceita edição; correção = novo evento. |
| Baixa atômica | Pagamento confirma cliente, cancela cadências, registra venda e muda etapa em uma transação. |
| Máquina de estados | Webhooks não sobrescrevem etapa; só RPCs validadas transicionam. |
| Esteiras isoladas | F1, F3 e Cobranças coexistem sem colisão de telefone ou métricas. |
Renderizando diagrama Mermaid...
webhook_events (idempotente) e chama a RPC (ingest_*).eventos_lead documenta o que ocorreu.admin, gestor, closer, viewer).O agente Bia (workflow n8n) é a interface conversacional do módulo comercial — não o cérebro do CRM:
pode_bia_enviar).webhook-bia).agendar-pagamento).O domínio crítico (etapas, cadência, vendas, conflitos multi-funil) permanece no PostgreSQL — a IA conversa; o banco governa.
Renderizando diagrama Mermaid...
funnel_conflicts com precedência definida.| Camada | Tecnologia | Por quê |
|---|---|---|
| Frontend | React, Vite, TypeScript, Tailwind | SPA operacional com Realtime e RLS |
| API / ingestão | Supabase Edge Functions (Deno) | Webhooks na borda, perto do banco |
| Domínio | PostgreSQL (crm schema) | Transações, máquina de estados, jobs |
| Jobs | pg_cron + pg_net | Cadência, 24h, temperatura, cobrança C-02, varredura renovação |
| Orquestração | n8n | Bia, disparos WhatsApp, normalização de fontes |
| Z-API | Entrada e saída de mensagens | |
| IA conversacional | xAI Grok + OpenAI | Bia: raciocínio, STT, formatação de saída |
| Pagamentos | AppMax | Confirmação e baixa atômica |
| Memória / buffer | Postgres + Redis | Histórico Bia + debounce de mensagens |
O time comercial passa a operar com visibilidade em tempo real: fila priorizada, kanban por etapa, performance por closer, objeções detectadas nas conversas com a Bia. A renovação anual tem esteira própria com régua clara de prevenção e resgate. Cobranças Pix não poluem o funil de vendas. E a arquitetura orientada a eventos garante que, mesmo com webhooks duplicados ou integrações instáveis, o estado do lead reflita o que de fato aconteceu — com rastro auditável em cada transição.
Pipeline
