Skip to main content

Decisões Técnicas e Arquiteturais

Escopo: Documento de engenharia e produto que registra as escolhas de arquitetura, limites técnicos e estratégia de infraestrutura.

1. Multi-Tenant com DNS Personalizado​

Decisão: O sistema será white-label, onde cada empresa (tenant) opera em um ambiente isolado. Implementação:

  • Cada empresa tem seu próprio subdomínio: minhaempresa.crm.com.
  • Isolamento de dados: schema por tenant no banco (PostgreSQL com search_path) ou banco dedicado por tenant para empresas maiores.
  • O roteamento por DNS identifica o tenant antes de qualquer autenticação.
  • Configurações globais (planos, integrações, KB) são por tenant — sem contaminação cruzada.

2. Microserviço de Vistoria​

Decisão: A captação e processamento de vistorias serão um serviço à parte do core comercial do CRM. Por que separar:

  • Ciclo de vida independente (foto, geo, timestamp, IA futura) não deve engessar o CRM.
  • Pode escalar separadamente (pico de vistorias não impacta o banco do CRM).
  • Permite evoluir com IA (análise automática de fotos, detecção de danos) futuramente. Integração: Comunicação via API REST (CRM solicita) e Webhooks (Vistoria devolve o laudo).

Dupla Via

Decisão: O CRM deve validar os veículos garantindo alta disponibilidade, mesmo que APIs externas caiam. Implementação:

  • API externa: cobre Placa → dados do veículo, CPF/CNPJ → dados do proprietário (uso em tempo real).
  • CSV mensal: importado no dia 1 de cada mês como fallback (cache interno).
  • O sistema consulta primeiro o cache; se não achar, vai para a API externa.

4. Integrações Plugáveis (Event-Driven)​

Decisão: O CRM orquestra, mas não executa tarefas fim-a-fim de serviços terceiros (WhatsApp, Assinatura, ERP). Implementação:

  • O CRM define "Interfaces" genéricas (Contratos de API/Webhooks).
  • A empresa cadastra qual provedor ela usa (ex: Docusign vs ClickSign).
  • Os eventos do CRM disparam webhooks padronizados para o serviço responsável pela entrega.

5. Limite de Alcance na Hierarquia (N1-N)​

Decisão: Evitar problemas de performance no cálculo de comissionamento piramidal infinito. Implementação: A subida de vendas em níveis gerenciais (N1-N) é configurável pelo Admin (ex: max 3 níveis). Isso será guardado no schema do Tenant para otimizar queries no banco relacional. Caso não configurado, o sistema aplicará uma profundidade dinâmica e ilimitada baseada na estrutura de times cadastrada.

6. Timeline Universal (Append-Only Log)​

Decisão: Centralizar todas as interações do usuário e do sistema em um histórico imutável. Implementação:

  • Uso de um padrão Append-Only Log (ou Event Sourcing simplificado) gravando cada ação (ligação, WhatsApp, mudança de status) na tabela eventos.
  • A interface consulta essa tabela para montar o histórico estilo HubSpot, unificando a jornada do Lead.

7. Motor de Automação (Rule Engine)​

Decisão: Criar flexibilidade para que administradores desenhem fluxos (Gatilho → Ação) sem deploy de código. Implementação:

  • O sistema intercepta eventos gerados na Timeline (Gatilhos: status_mudou, proposta_aprovada).
  • Avalia contra regras dinâmicas (se lead sem contato > 5 dias).
  • Enfileira jobs assíncronos (Ações: enviar email, criar tarefa, mudar status) usando um Message Broker (BullMQ ou NATS).

8. Motor de Comissionamento (Cálculo em Cascata)​

Decisão: O cálculo de comissões será atrelado à hierarquia em tempo de assinatura e processado assincronamente. Implementação:

  • Ao assinar um contrato, uma snapshot da hierarquia do Consultor (vendedor) é capturada.
  • Um worker em background aplica as regras de comissão (percentual por cargo e plano) de baixo para cima na árvore N1-N (limitado pelo alcance configurado).
  • Resultados consolidados vão para uma tabela de extrato financeiro do vendedor junto com informações como Adesões, Mensalidades.