Skip to main content

Módulo 10: Vistoria (Microserviço)

Status: Documentado

Domínio: ver Domínio/Entidade: Vistoria

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

1. Decisão Arquitetural: Microserviço Independente​

A Vistoria Veicular não faz parte do monolito/core do CRM. É tratada como um Microserviço Externo Independente.

Por quê? As responsabilidades da vistoria envolvem complexidade técnica incompatível com o CRM comercial:

  • Upload de dezenas de fotos em alta resolução
  • Processamento e análise de imagem (IA antifraude)
  • Fluxos mobile offline-first para vistoriadores em campo
  • Gestão de laudos jurídicos e conformidade por tipo de veículo

Contrato de comportamento:

  • O CRM solicita a vistoria e ouve o resultado — nunca processa imagens.
  • O CRM armazena apenas URLs, status e metadados retornados pelo Microserviço.
  • Se o Microserviço disser APROVADA, o CRM acata e avança o fluxo. A lógica de validação é externa.

2. Modalidades de Vistoria​

Configuradas por tenant via modalidades_vistoria_habilitadas (ver dominio/tenant.md):

ModalidadeDescriçãoExecutor
SELF_SERVICE_LINKLink web enviado ao cliente via WhatsApp. O próprio cliente fotografa o veículo seguindo o guia na tela.Cliente final
INTERNAMicroserviço delega para um funcionário da empresa via App Mobile.Vistoriador interno
TERCEIRIZADAMicroserviço delega para empresa parceira (ex: Dekra, Supervisão).Empresa terceira

3. Ciclo de Vida da Vistoria​

StatusDescriçãoDono do estado
PENDENTESolicitada pelo CRM, link ainda não acessado / vistoriador não despachadoMicroserviço
EM_ANDAMENTOFotos sendo coletadasMicroserviço
EM_ANALISEColeta concluída, aguardando parecer humano ou IAMicroserviço
APROVADAVeículo apto para proteção — CRM avança para ContratoMicroserviço → CRM via webhook
APROVADA_COM_RESSALVASVeículo apto, mas com avarias pré-existentes registradas — CRM avança para Contrato com ressalvas no anexoMicroserviço → CRM via webhook
REPROVADAVeículo inapto (adulteração, perda total prévia, etc.) — CRM bloqueia o fluxoMicroserviço → CRM via webhook

4. Ressalvas e Implicações Jurídicas​

  • Se o Microserviço detectar avarias durante a vistoria (ex: farol quebrado, arranhão no parachoque):
    • O vistoriador/IA marca a peça e gera uma Ressalva com foto de evidência.
    • O CRM recebe as ressalvas no webhook e as armazena em Vistoria_Ressalva.
  • As ressalvas devem ser impressas obrigatoriamente no anexo do Contrato (Módulo 11), garantindo segurança jurídica de que danos pré-existentes não têm cobertura do plano.
  • Uma vistoria APROVADA_COM_RESSALVAS não bloqueia o avanço para Contrato — apenas exige que as ressalvas estejam registradas e visíveis no documento.

5. Aprovação: Manual vs. Automática (Auditoria Interna de Vistoria)​

Controlada pela configuração do tenant aprovacao_laudo_obrigatoria e regras de contingência:

ConfiguraçãoComportamento
aprovacao_laudo_obrigatoria = trueToda vistoria concluída pelo microserviço entra no status EM_ANALISE no CRM, gerando uma entrada na Fila de Auditoria Interna.
aprovacao_laudo_obrigatoria = falseA IA do Microserviço emite o parecer final automaticamente. Transita direto para APROVADA ou REPROVADA (contingência: pareceres de IA inconclusivos entram em EM_ANALISE para auditoria manual).

5.1 Alçadas de Acesso e Governança de Auditoria​

  • Proibição Comercial: Consultores de Vendas (CONSULTOR) e Gestores de Vendas (GESTOR) possuem acesso estritamente de leitura aos laudos e ressalvas. Eles jamais visualizam botões de parecer (aprovar/reprovar) para garantir a independência e blindagem técnica contra fraudes.
  • Setor Técnico: Apenas usuários com papel AUDITOR_VISTORIA, GESTOR_VISTORIA ou ADMIN do tenant podem realizar interações de aprovação/reprovação.

5.2 Ações da Fila de Auditoria Humana (Logado em Vistoria_Interacao)​

  1. Aprovar: Auditor valida as imagens e o laudo, marcando a vistoria como APROVADA e liberando o fluxo do veículo.
  2. Aprovar com Ressalvas: Auditor aceita a vistoria, mas registra/insere manualmente avarias adicionais em Vistoria_Ressalva, transitando o status para APROVADA_COM_RESSALVAS.
  3. Reprovar: Auditor recusa o veículo, marcando como REPROVADA. O preenchimento do campo motivo_detalhado (ex: "Chassi adulterado", "Borrachões ocultando ferrugem grave") é obrigatório.
  4. Solicitar Segunda Opinião: O auditor atual pode delegar a vistoria temporariamente para outro auditor (AUDITOR_VISTORIA) revisar as fotos e emitir um parecer colaborativo. O status da vistoria permanece em EM_ANALISE.
  5. Delegar ao Gestor de Vistorias: Transfere a alçada de decisão para o GESTOR_VISTORIA. Usado em disputas comerciais (ex: consultor recorrendo de uma reprovação técnica direta). A decisão do Gestor de Vistoria é soberana e final.

6. Fluxo Alternativo: Vistoria Pós-Assinatura​

[!WARNING] Em alguns tenants, por estratégia de funil de vendas, a ordem é invertida: o cliente assina o contrato primeiro e faz a vistoria depois. Se reprovar, o contrato é cancelado retroativamente. Controlado pela flag vistoria_pos_assinatura_invalida_contrato no tenant (dominio/tenant.md). O fluxo padrão documentado aqui segue a sequência Vistoria → Contrato.

7. Ações do CRM ao Receber o Webhook​

  1. Validar a assinatura de segurança (X-Vistoria-Signature) — rejeitar webhooks sem assinatura válida.
  2. Atualizar a entidade Vistoria correspondente com status_final, data_conclusao, laudo_pdf_url e ressalvas[].
  3. Fluxo Comercial (se tipo_contexto = ENTRADA):
    • Se APROVADA ou APROVADA_COM_RESSALVAS:
      • Liberar o botão "Gerar Contrato" no painel do consultor.
      • Enviar notificação de sucesso ao consultor responsável.
    • Se REPROVADA:
      • Marcar a Proposta correspondente como CANCELADA (motivo: "Vistoria Reprovada").
      • Alertar o consultor e registrar evento na timeline da proposta.
  4. Fluxo Operacional (se tipo_contexto = REATIVACAO):
    • Se APROVADA:
      • O plano de proteção veicular associado transita imediatamente para ATIVO e notifica o ERP de que a cobertura está ativa.
      • Registra evento de reativação de cobertura na timeline do Cliente/Veículo.
    • Se APROVADA_COM_RESSALVAS:
      • As novas avarias são salvas na tabela Vistoria_Ressalva.
      • O CRM gera um Termo Aditivo de Reativação e Ressalvas e o envia ao cliente via WhatsApp/link para assinatura digital.
      • O plano de proteção permanece no estado SUSPENSO até que o Termo Aditivo seja assinado. Assim que assinado, o plano transita para ATIVO e notifica o ERP.
    • Se REPROVADA:
      • O plano de proteção veicular associado é mantido no status SUSPENSO no CRM (bloqueando qualquer cobertura em sinistros).
      • O sistema notifica o consultor e o gestor por tarefa para contato comercial (reparo de avarias ou rescisão contratual).
  • Links de Self-Service têm validade configurável no Microserviço (ex: 48 horas).
  • Se o Microserviço notificar expiração via webhook, o CRM alerta o executor:
    • No fluxo de ENTRADA: Consultor clica em "Reenviar Link" na tela da proposta.
    • No fluxo de REATIVACAO: Link é enviado de forma automática ou consultor clica em "Reenviar Link de Revistoria" na tela de detalhes do Plano Contratado.
  • O reenvio gera um novo link via nova chamada ao Microserviço — o link anterior é invalidado.

9. Revistoria de Reativação (Operacional)​

A Revistoria é um mecanismo de mitigação de fraude e risco, disparado quando um veículo permanece suspenso de cobertura por um período superior a Y dias (configurado pelo tenant).

9.1 Funcionamento e Simplicidade​

  • Escopo Simplificado: O microserviço é acionado com um template de vistoria reduzido (ex: apenas fotos de evidência dos 4 cantos do veículo + hodômetro + chassi).
  • Sem Vistoria de Entrada = Sem Revistoria: Se o plano original contratado for isento de vistoria na venda (ex: assistência 24h), ele também é isento de revistoria em caso de reativação financeira.
  • Armazenamento e Tráfego: Laudos e assinaturas digitais do Termo Aditivo ficam salvos no storage do CRM. O ERP integrado não recebe a vistoria técnica, recebendo apenas o comando do CRM informando que o plano está ATIVO e liberado financeiramente.

9.2 Tratamento Jurídico de Avarias Pré-Existentes (Termo Aditivo)​

  • Se a revistoria detectar novas avarias (status APROVADA_COM_RESSALVAS), o CRM gera dinamicamente o Termo Aditivo de Reativação e Ressalvas.
  • Esse termo aditivo especifica de forma imutável que as novas avarias identificadas não possuem cobertura securitária, garantindo a proteção jurídica da associação.
  • A cobertura no CRM só entra em vigor (status ATIVO) após a assinatura digital deste termo pelo associado.

9.3 Organização Visual e UX​

  • Para evitar a poluição visual do funil de vendas, as vistorias de REATIVACAO são ocultadas do fluxo de propostas comerciais.
  • Elas são expostas exclusivamente na timeline do cliente, no histórico de laudos do cadastro do veículo e nos detalhes do Plano Contratado.

10. Regras Inegociáveis​

[!IMPORTANT] Desacoplamento rigoroso. O CRM não processa regras de validade de foto, antifraude ou IA de imagem. A responsabilidade de validar a vistoria é exclusiva do Microserviço. O CRM apenas consome o resultado final (APROVADA, APROVADA_COM_RESSALVAS ou REPROVADA).

[!IMPORTANT] Fotos nunca são armazenadas no CRM. O banco de dados do CRM armazena apenas URLs externas. Nenhum blob, base64 ou arquivo de imagem deve ser gravado no banco ou no storage do CRM.

[!IMPORTANT] Garantia Jurídica do Termo Aditivo. Em caso de avarias identificadas na revistoria de reativação, o status do plano nunca deve transitar para ATIVO antes da assinatura eletrônica válida do Termo Aditivo de Ressalvas pelo associado.