Entidade: Vistoria

Camada: Domínio — Define o que o objeto é, seus atributos e relacionamentos.

Regras de comportamento: ver Regras de Negócio/Módulo 10: Vistoria (Microserviço)

---

1. Definição

A Vistoria é a inspeção do veículo que precede a geração do contrato de proteção (quando exigida pelo plano). Ela é executada por um Microserviço Externo Independente — o CRM apenas solicita a vistoria, armazena o resultado mínimo necessário e reage ao desfecho.

Princípio arquitetural: O CRM não processa imagens, não armazena fotos em disco e não executa lógica antifraude ou de IA. Toda essa complexidade pertence ao Microserviço de Vistoria. O CRM armazena apenas URLs, status e metadados.

CRM Core (solicita) → Microserviço de Vistoria (processa, analisa)
                     ← Webhook com resultado (APROVADA / REPROVADA)
CRM Core (reage e avança o fluxo)

---

2. Atributos da Entidade Vistoria (armazenada no CRM)

Campo	Tipo	Obrigatório	Notas
id	UUID	Sim	Gerado pelo CRM
tenant_id	UUID	Sim	FK → Tenant
tipo_contexto	enum	Sim	ENTRADA (vistoria inicial para proposta) ou REATIVACAO (revistoria de reativação operacional)
proposta_id	UUID	Não	FK → Proposta comercial. Obrigatório se tipo_contexto = ENTRADA
plano_contratado_id	UUID	Não	FK → Plano Contratado. Obrigatório se tipo_contexto = REATIVACAO
vistoria_externa_id	string	Sim	ID gerado pelo Microserviço (referência cruzada)
modalidade	enum	Sim	SELF_SERVICE_LINK, INTERNA, TERCEIRIZADA
status	enum	Sim	PENDENTE, EM_ANDAMENTO, EM_ANALISE, APROVADA, APROVADA_COM_RESSALVAS, REPROVADA. Ver Ciclo de Vida
link_acesso	string	Sim	URL gerada pelo Microserviço para o executor da vistoria
laudo_pdf_url	string	Não	URL do laudo em PDF, hospedado no Microserviço
data_solicitacao	timestamp	Sim	Momento em que o CRM solicitou a vistoria
data_conclusao	timestamp	Não	Preenchida ao receber o webhook de conclusão
motivo_reprovacao	string	Não	Preenchido quando status = REPROVADA

O CRM não armazena imagens — apenas laudo_pdf_url e as URLs das fotos de evidência das ressalvas (hospedadas no Microserviço/storage externo).

---

3. Agregado: Vistoria_Ressalva

Avarias identificadas durante a vistoria são armazenadas no CRM para impressão obrigatória no Contrato ou Termo Aditivo.

Campo	Tipo	Obrigatório	Notas
id	UUID	Sim	Gerado pelo CRM
vistoria_id	UUID	Sim	FK → Vistoria
peca_afetada	string	Sim	Nome do componente afetado (ex: "Parachoque Dianteiro")
descricao_dano	string	Sim	Detalhamento da avaria detectada (ex: "Arranhão leve")
url_foto_evidencia	string	Sim	URL da foto hospedada no Microserviço/Storage externo

As ressalvas devem ser impressas obrigatoriamente no anexo do Contrato para garantir segurança jurídica — danos pré-existentes não têm cobertura do plano.

---

4. Agregado: Vistoria_Interacao (Histórico de Auditoria e Validação)

Registra todas as interações e pareceres humanos executados pelos auditores ou gestores de vistoria no CRM.

Campo	Tipo	Obrigatório	Notas
id	UUID	Sim	Gerado pelo CRM
vistoria_id	UUID	Sim	FK → Vistoria
auditor_id	UUID	Sim	FK → Usuário (Auditor/Gestor que realizou a ação)
acao	enum	Sim	APROVAR, APROVAR_COM_RESSALVAS, REPROVAR, SOLICITAR_SEGUNDA_OPINIAO, DELEGAR_GESTOR, REGISTRAR_OBSERVACAO
motivo_detalhado	string	Não	Justificativa técnica (obrigatório se acao = REPROVAR)
segunda_opiniao_auditor_id	UUID	Não	FK → Usuário (Auditor selecionado para segunda análise)
created_at	timestamp	Sim	Registra o momento da ação de auditoria

---

5. Estados do Ciclo de Vida

O ciclo de vida pertence ao Microserviço, mas é espelhado no CRM via webhook:

Referência canônica: Regras de Negócio/Módulo 10: Vistoria (Microserviço)

---

6. Relacionamentos

Vistoria ──── pertence a ────── Tenant            (N:1)
Vistoria ──── possui ─────────── Ressalvas        (1:N → Vistoria_Ressalva)
Vistoria ──── executada via ──── Microserviço     (integração externa)
Vistoria ──── originada de ──── Proposta          (0..1 — se tipo_contexto = ENTRADA)
Vistoria ──── originada de ──── Plano Contratado  (0..1 — se tipo_contexto = REATIVACAO)
Vistoria ──── resulta em ────── Contrato          (0..1 — se tipo_contexto = ENTRADA e aprovada)
Vistoria ──── resulta em ────── Termo Aditivo     (0..1 — se tipo_contexto = REATIVACAO e aprovada)
Vistoria ──── possui histórico ── Interações      (1:N → Vistoria_Interacao)

Legenda de Cardinalidade:

• N:1 (Muitos para Um): Múltiplos registros deste domínio apontam para um mesmo registro de destino (ex: várias vistorias pertencem ao mesmo tenant).
• 1:N (Um para Muitos): Um único registro deste domínio possui múltiplos registros filhos associados (ex: uma vistoria pode registrar várias ressalvas ou interações de auditoria).
• 0..1 (Zero ou Um): Relação opcional e de correspondência única (ex: uma vistoria pode ou não estar vinculada a uma proposta/plano e gerar ou não um contrato/termo aditivo).

---

7. Invariantes (Restrições Absolutas)

• O CRM nunca armazena fotos em blob ou base64 — apenas URLs externas do Microserviço.
• O CRM nunca executa lógica de validação de imagem — se o Microserviço diz APROVADA, o CRM acata o resultado.
• Toda vistoria com status APROVADA_COM_RESSALVAS obriga o registro detalhado de suas ressalvas na entidade Vistoria_Ressalva antes de avançar para a confecção do Contrato (se ENTRADA) ou do Termo Aditivo (se REATIVACAO).
• O vistoria_externa_id é a chave de rastreabilidade cruzada entre o CRM e o Microserviço — deve ser armazenado imediatamente na criação.
• Desfecho de Vistoria REPROVADA:
  • Se tipo_contexto = ENTRADA: Cancela a Proposta associada e bloqueia a emissão do Contrato.
  • Se tipo_contexto = REATIVACAO: Mantém o Plano Contratado no status SUSPENSO, impedindo a vigência de cobertura operacional até que uma nova revistoria seja solicitada e aprovada.
• Diferenciação Visual de Interface: O CRM lista as vistorias de ENTRADA no fluxo comercial (telas de Propostas e Cotações), enquanto as vistorias de REATIVACAO são expostas exclusivamente no histórico de timeline do Veículo e do Cliente, evitando a poluição visual de propostas antigas.