Skip to main content

Integração Plataforma SaaS & CRM Core

Camada: Arquitetura — Define a relação e divisão de escopo entre a infraestrutura administrativa global da plataforma e os tenants transacionais. Referências Cruzadas: dominio/tenant.md · regras-negocio/02_tenant.md

1. Visão Geral da Arquitetura​

O sistema é estruturado sob o modelo de SaaS Multi-Tenant (Software as a Service). Para manter o isolamento de dados e facilitar a manutenção, o ecossistema é dividido em duas grandes fronteiras operacionais:

  1. SaaS Admin (Painel de Administração Global): Sistema de controle de propriedade da nossa empresa (a dona do software). É utilizado pelos Super Admins para cadastrar Tenants, monitorar faturas de contratação da plataforma e controlar limites de infraestrutura.
  2. CRM Core (Instância do Tenant): A aplicação transacional de CRM de Proteção Veicular que os operadores das associações utilizam em seu dia a dia comercial.

2. O Papel do plano_contratado​

O atributo plano_contratado (salvo na entidade Tenant) é a chave de ligação de regras entre os dois ambientes. Ele atua como uma referência lógica para as variáveis limitadoras configuradas de forma centralizada na plataforma.

Plano ConfiguradoLimite de Usuários AtivosArmazenamento Máximo (S3)Módulos Liberados no CRM
BRONZEAté 5 usuários5 GBLeads, Veículos, Propostas
PRATAAté 15 usuários20 GBLeads, Veículos, Propostas, Vistorias
OUROAté 50 usuários100 GBTodos os módulos + Integração ERP
ENTERPRISECustomizadoCustomizadoAcesso total e Portal do Cliente

3. Mecanismo de Validação de Limites (CRM Core)​

O CRM Core valida os limites do plano de forma ativa e impeditiva nas seguintes operações transacionais:

3.1 Limite de Usuários Ativos​

Toda vez que o Admin do Tenant tenta convidar ou reativar um usuário (usuario.md), o backend do CRM executa:

SELECT COUNT(id) FROM usuarios 
WHERE tenant_id = :tenant_id AND status = 'ATIVO';

Se o resultado for igual ou superior ao limite mapeado para o plano_contratado do Tenant, a API do CRM recusa o cadastro retornando código de erro 403 Forbidden e a mensagem: "Limite de usuários excedido para o seu plano contratado".

3.2 Cota de Armazenamento (Storage)​

Ao realizar o upload de documentos de vistoria, fotos ou contratos, o sistema verifica o volume acumulado consumido pelo Tenant no Storage:

  • O CRM Core não calcula o tamanho do disco a cada requisição. Em vez disso, mantém um contador de bytes agregados na tabela Tenant_Config ou utiliza metadados do Cloud Storage.
  • Caso o limite de GB do plano seja atingido, o upload é bloqueado no backend.

3.3 Habilitação de Módulos Dinâmicos​

As rotas do API Gateway do CRM e os itens do menu do frontend leem a lista de módulos liberados para o plano_contratado:

  • Se o módulo PORTAL_CLIENTE ou INTEGRACAO_ERP não estiver no escopo do plano, as APIs públicas correspondentes retornam 404 Not Found de forma imediata, impedindo bypass através de chamadas diretas via HTTP.

4. Fluxo de Sincronização e Ciclo de Vida do Tenant​

As alterações de plano e status de pagamento que ocorrem no SaaS Admin ou no Gateway de Faturamento (Stripe, Asaas, Iugu) propagam-se para o CRM Core de maneira assíncrona:

  • Suspensão por Inadimplência do SaaS: Se o Tenant atrasar o pagamento da fatura do CRM, o SaaS Admin altera o status do Tenant para SUSPENSO. O CRM bloqueia o acesso a todas as rotas operacionais do tenant em tempo de execução, exibindo apenas a tela de cobrança pendente.
  • Cancelamento Definitivo: Altera o status para CANCELADO. O CRM agenda a exclusão lógica dos dados (soft delete) e a expiração das chaves de integração do Tenant.