Entidade: Proposta

Tipos e formatos: ver Domínio/Tipos e Formatos Comuns

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

Regras de comportamento: ver Regras de Negócio/Módulo 09: Propostas / Cotações

---

1. Definição

Uma Proposta (ou Cotação) é a materialização da oferta comercial. Une o Cliente (quem contrata), o Veículo (o bem protegido) e o Plano (regras de cobertura e precificação).

A proposta é um documento intermediário: após aceita pelo cliente e com vistoria aprovada (quando exigida pelo plano), ela se converte em um Contrato.

Cliente + Veículo + Plano
         ↓  criação
      Proposta (RASCUNHO)
         ↓  envio/aceite
      Proposta (ENVIADA)
         ↓  aceite comercial (pelo Cliente via link OU pelo Consultor via painel do CRM)
      Proposta (ACEITA)
         ↓  geração do contrato
      Contrato (GERADO)

---

2. Atributos Principais

Campo	Tipo	Obrigatório	Notas
id	UUID	Sim	Gerado pelo sistema
tenant_id	UUID	Sim	FK → Tenant
consultor_id	UUID	Sim	FK → Usuário responsável
cliente_id	UUID	Sim	FK → Cliente
veiculo_id	UUID	Sim	FK → Veículo — uma proposta aponta para um único veículo
plano_id	UUID	Sim	FK → Plano de referência
status	enum	Sim	RASCUNHO, ENVIADA, ACEITA, PERDIDA, CANCELADA, CONVERTIDA, SUBSTITUIDA. Ver Ciclo de Vida
hash_publico	string	Sim	Token único que identifica o link público da proposta
data_validade	date	Sim	Data de expiração da oferta (configurada pelo tenant)
data_aceite	timestamp	Não	Preenchido quando o cliente aceita
created_at	timestamp	Sim	Imutável após criação
updated_at	timestamp	Sim	Registra o momento da última modificação dos dados

2.1 Campos Financeiros

Campo	Tipo	Notas
valor_mensal_bruto	decimal	Valor base do plano calculado (antes de opcionais e desconto)
valor_opcionais_total	decimal	Soma de todos os opcionais selecionados
desconto_concedido_pct	decimal	% de desconto aplicado pelo consultor
valor_mensal_liquido	decimal	Valor final mensal: (bruto + opcionais) × (1 - desconto)
taxa_adesao_base	decimal	Valor base de adesão definido na política do Plano para guiar o consultor
taxa_adesao_acrescido	decimal	Valor extra adicionado pelo Consultor Externo (comissão direta). Permitido apenas se canal_vendas = EXTERNO
taxa_adesao_desconto	decimal	Desconto sobre o valor de adesão concedido pelo Consultor Externo
taxa_adesao_negociada	decimal	Taxa de entrada final cobrada: Max(0, base + acrescido - desconto). Exibida de forma consolidada no link e contrato, sem menção aos acréscimos

2.2 Campos de Snapshot (Congelados no Envio)

Gravados no momento em que a proposta passa para ENVIADA. Nunca atualizados após este ponto.

Campo	Tipo	Notas
snap_fipe_mes_ref	string	Mês de referência da tabela FIPE usada (YYYY-MM)
snap_valor_fipe	decimal	Valor FIPE do veículo no momento do envio
snap_nome_plano	string	Nome do plano no momento do envio

Os snapshots garantem que uma proposta gerada em janeiro mantenha os valores corretos mesmo após a atualização da FIPE em fevereiro.

---

3. Agregado: Proposta_Opcional

Relação N:M entre a Proposta e os Serviços Opcionais selecionados. Os valores também são congelados no snapshot.

Campo	Tipo	Notas
proposta_id	UUID	FK → Proposta
opcional_id	UUID	FK → Serviço
snap_nome_opcional	string	Nome do opcional no momento do envio
snap_valor_mensal	decimal	Valor do opcional no momento do envio

---

4. Estados do Ciclo de Vida

Referência canônica de status: Regras de Negócio/Módulo 09: Propostas / Cotações

---

5. Relacionamentos

Proposta ──── pertence a ──── Tenant          (N:1)
Proposta ──── criada por ──── Consultor       (N:1 → Usuário)
Proposta ──── oferta para ─── Cliente         (N:1)
Proposta ──── referencia ──── Veículo         (N:1) — 1 proposta : 1 veículo
Proposta ──── usa ─────────── Plano           (N:1)
Proposta ──── inclui ──────── Opcionais       (N:M → Proposta_Opcional)
Proposta ──── origina ──────── Contrato       (1:0..1)
Proposta ──── pode gerar ──── Vistoria        (1:0..1)

Legenda de Cardinalidade:

• N:1 (Muitos para Um): Múltiplas propostas podem estar associadas ao mesmo registro (ex: várias propostas para o mesmo cliente), mas cada proposta pertence a apenas um registro.
• N:M (Muitos para Muitos): Uma proposta pode conter vários opcionais, e o mesmo opcional pode estar em várias propostas. Exige uma tabela intermediária de ligação (Proposta_Opcional) para congelar os valores daquele vínculo.
• 1:0..1 (Um para Zero ou Um): Uma relação opcional e exclusiva. Uma proposta pode existir sem ter gerado um Contrato (zero), mas se gerar, gerará no máximo um único Contrato (um).

---

6. Invariantes (Restrições Absolutas)

• Uma proposta aponta para exatamente um veículo — frotas geram múltiplas propostas.
• Ao passar para ENVIADA, todos os valores financeiros e de referência são congelados via snapshot e nunca mais alterados.
• O aceite pelo link público (ACEITA) não tem validade jurídica — é apenas aceite comercial. A assinatura jurídica ocorre no Contrato.
• Ao marcar uma proposta como CONVERTIDA, todas as demais propostas ENVIADA do mesmo veículo são automaticamente marcadas como SUBSTITUIDA (ver Domínio/Entidade: Veículo).
• O hash_publico é gerado pelo sistema, único e imutável — nunca reutilizado entre propostas.
• Controle Comercial da Adesão:
  • Consultores de canal INTERNO estão proibidos de alterar o valor da adesão; o sistema força taxa_adesao_acrescido = 0 e taxa_adesao_desconto = 0.
  • Consultores de canal EXTERNO possuem permissão para flexibilizar a adesão: podem conceder descontos (taxa_adesao_desconto) e adicionar acréscimos de comissão direta (taxa_adesao_acrescido).
  • O valor exposto no link da proposta e no PDF do Contrato é estritamente a taxa_adesao_negociada consolidada, garantindo que o cliente final nunca veja o valor do acréscimo de comissão de forma discriminada.
• Um consultor só pode conceder desconto até o limite configurado no tenant (desconto_maximo_consultor_pct). Descontos acima desse limite requerem aprovação do gestor antes do envio.