Skip to main content

Módulo 15: Portal do Cliente

Status: Documentado

Domínio: ver Domínio/Entidade: Cliente e Domínio/Entidade: Plano Contratado

ATA de Referência: (Ainda não aprovada)

1. Visão Geral da Arquitetura​

O Portal do Cliente é o ambiente de autoatendimento exclusivo do associado final. Para garantir isolamento de contexto de rede, segurança cibernética e robustez de carga, ele é construído sob uma arquitetura desacoplada:

  • Frontend Isolado: Desenvolvido como PWA (Progressive Web App) ou Web App independente, sem compartilhar código ou sessões administrativas com o painel do CRM.
  • Integração via API Gateway: O portal consome as APIs públicas seguras do CRM (para dados cadastrais, veículos, sinistros e vistorias) e faz consultas diretas ou em cache à API do ERP (para dados de boletos, cobrança e Pix).

2. White-label e Identidade Visual Dinâmica​

O Portal do Cliente é inteiramente white-label, adaptando-se visualmente a cada Associação/Tenant:

  1. Subdomínio Dedicado: Cada tenant possui um subdomínio de acesso próprio (ex: cliente.associacaox.com.br).
  2. Carregamento de Asset pré-login: Antes da autenticação do cliente, o PWA executa uma requisição de descoberta de tenant com base no subdomínio de origem.
  3. Cores e Logotipo: O backend retorna o arquivo de estilo contendo as variáveis semânticas do tenant (cor_primaria, cor_secundaria, link do logotipo e links de assistência 24h). O portal aplica o tema dinamicamente na interface.

3. Autenticação e Primeiro Acesso​

O cliente final não possui registro na tabela de usuários internos do CRM. A sua autenticação consome os campos de credenciais injetados diretamente na tabela Cliente (Módulo 06):

  • Primeiro Acesso: No momento em que o plano contratado do cliente muda para ATIVO (Módulo 12), o CRM gera um token_recuperacao único com validade de 48 horas e envia um link mágico para o WhatsApp/E-mail do cliente (Módulo 05). O cliente clica, valida seu CPF e define a senha.
  • Fluxo Convencional: Login feito mediante o preenchimento de CPF/CNPJ e a Senha cadastrada.
  • Segunda Via (Esqueci Senha / OTP): O cliente pode solicitar redefinição. O sistema gera um código OTP de 6 dígitos de uso único enviado ao WhatsApp do cliente cadastrado para validar o acesso e redefinir a senha.

4. Funcionalidades e Autoatendimento​

4.1 Frota e Coberturas (Meus Veículos)​

  • Exibição de todos os veículos cadastrados do cliente.
  • Exibição do Cartão Virtual de Cobertura em formato PDF (gerado dinamicamente com dados da vigência e limite de guincho/coberturas).
  • Status operacional do veículo bem visível (ATIVO, INADIMPLENTE, SUSPENSO).

4.2 Financeiro (Proxy ERP)​

  • Listagem de cobranças pendentes e quitadas da assinatura.
  • Geração de linha digitável, QR Code Pix ou download do PDF do boleto gerados na API do ERP Hinova.
  • Resiliência a quedas (Offline-first): Caso a API do ERP esteja instável ou offline, o portal exibe as informações básicas do veículo e assistência normalmente, mas isola o faturamento com um aviso informativo amigável: "Sistema financeiro temporariamente indisponível. Tente novamente mais tarde".

4.3 Revistoria Automatizada​

  • Se o veículo do cliente passar de Y dias no status SUSPENSO e o faturamento for liquidado, o portal bloqueia a emissão do cartão virtual e exibe um banner orientando o cliente a realizar uma nova vistoria.
  • O botão "Iniciar Vistoria" invoca diretamente o fluxo de Vistoria Self-Service (Módulo 10) no navegador do celular do cliente.

4.4 Abertura de Sinistro (Aviso de Evento)​

  • Formulário simplificado para o cliente relatar acidentes, furtos ou colisões.
  • Envio de descrição do evento, data/hora, geolocalização e upload do Boletim de Ocorrência (B.O.).
  • O envio do formulário dispara um Ticket urgente e agenda uma tarefa (Módulo 14) na fila de prioridades do backoffice do CRM.

5. Regras Inegociáveis​

[!IMPORTANT] Isolamento de Token (Row-Level Security). A API pública de autoatendimento deve validar rigorosamente em todas as requisições que o cliente_id contido no payload decodificado do JWT do cliente final corresponde exatamente ao registro que está sendo acessado.

[!WARNING] Fallback de falha do ERP. A instabilidade ou indisponibilidade da API do ERP parceiro de cobrança nunca deve indisponibilizar a visualização das coberturas e o botão de emergência da Assistência 24h.