Entidade: Contrato

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

Regras de comportamento: ver Regras de Negócio/Módulo 11: Contratos & Assinaturas e Domínio/Mapeamento

---

1. Definição

Um Contrato é o acordo jurídico firmado entre o Cliente e o Tenant, referente à proteção de um Veículo específico. O fluxo é totalmente flexível: o cliente pode assinar o contrato antes ou depois de realizar a Vistoria do veículo. No entanto, a ativação da cobertura operacional e a validação do cadastro ativo do cliente ficam estritamente condicionadas à conclusão de ambos os requisitos: contrato assinado E vistoria aprovada (quando o plano a exigir).

---

2. Atributos Principais

Campo	Tipo	Obrigatório	Notas
id	UUID	Sim	Gerado pelo sistema
tenant_id	UUID	Sim	FK → Tenant
proposta_id	UUID	Sim	FK → Proposta que originou o contrato
cliente_id	UUID	Sim	FK → Cliente
veiculo_id	UUID	Sim	FK → Veículo protegido
plano_id	UUID	Sim	FK → Plano contratado
consultor_id	UUID	Sim	FK → Consultor responsável pela venda
numero	string	Sim	Número legível e único por tenant (ex: 2024-00123)
status	enum	Sim	GERADO, AGUARDANDO_ASSINATURA, AGUARDANDO_VISTORIA, ATIVO, CANCELADO, EM_RENOVACAO, ENCERRADO. Ver Ciclo de Vida
vigencia_inicio	date	Sim	Data de início da cobertura
vigencia_fim	date	Sim	Data de término (pode ser renovado)
valor_mensal_bruto	decimal	Sim	Valor base do plano sem adicionais ou descontos
valor_opcionais_total	decimal	Sim	Soma dos valores mensais de todos os opcionais contratados
desconto_concedido_pct	decimal	Sim	% de desconto aplicado na mensalidade
valor_mensalidade	decimal	Sim	Valor mensal final cobrado: (bruto + opcionais) × (1 - desconto)
valor_adesao	decimal	Sim	Valor final cobrado pela taxa de adesão (pode ser 0.00)
template_contrato_id	UUID	Sim	FK → Template de contrato do plano
assinatura_provedor	string	Não	ID do documento no provedor de e-Signature (envelope_id)
documento_rascunho_url	string	Não	URL do PDF gerado a partir do template (storage interno)
documento_assinado_url	string	Não	URL do PDF assinado com o certificado (storage interno)
enviado_em	timestamp	Não	Preenchido quando enviado para assinatura
assinado_at	timestamp	Não	Preenchido ao receber confirmação final da assinatura
created_at	timestamp	Sim	Imutável após criação

---

3. Agregado: Signatário do Contrato

O Contrato possui um ou mais signatários responsáveis por formalizar o documento digitalmente.

Campo	Tipo	Obrigatório	Notas
id	UUID	Sim	Gerado pelo sistema
contrato_id	UUID	Sim	FK → Contrato
nome	string	Sim	Nome completo do assinante
email	string	Sim	E-mail de envio
telefone	string	Não	Formato E.164. Usado para SMS Token se ativado
papel	enum	Sim	CONTRATANTE, TESTEMUNHA, REPRESENTANTE
status_assinatura	enum	Sim	PENDENTE, VISUALIZADO, ASSINADO
data_assinatura	timestamp	Não	Momento do clique de assinatura
ip_assinatura	string	Não	IP registrado pelo provedor de assinatura

---

3. Agregado: Opcionais do Contrato

Relação N:M entre o Contrato e os Serviços Opcionais/Adicionais contratados, congelando os nomes e valores cobrados no momento em que o Contrato é gerado para fins de auditoria histórica e cobrança exata.

Campo	Tipo	Notas
contrato_id	UUID	FK → Contrato
opcional_id	UUID	FK → Serviço
snap_nome_opcional	string	Nome do opcional contratado
snap_valor_mensal	decimal	Valor cobrado pelo opcional neste contrato

---

4. Entidade Relacionada: Proposta

A Proposta foi promovida a entidade com documento próprio. Ver: dominio/proposta.md · regras-negocio/09_propostas.md

A proposta é o estágio anterior ao contrato. Um contrato só é gerado a partir de uma proposta no status ACEITA (e com vistoria aprovada, quando o plano exige).

Proposta (ACEITA) → Contrato (GERADO)

---

5. Estados do Ciclo de Vida (Contrato)

---

6. Relacionamentos

Contrato ──── originado de ──── Proposta   (1:1)
Contrato ──── protege ─────────  Veículo   (N:1)
Contrato ──── pertence a ───────  Cliente  (N:1)
Contrato ──── usa ───────────────  Plano   (N:1)
Contrato ──── vendido por ───────  Consultor (N:1 → Usuário)
Contrato ──── inclui ──────────── Opcionais (N:M → Contrato_Opcional)
Contrato ──── registra ──────────  Eventos na Timeline (1:N)

Legenda de Cardinalidade:

• 1:1 (Um para Um): Relação exclusiva e de correspondência única (ex: um contrato é originado de exatamente uma proposta).
• N:1 (Muitos para Um): Múltiplos registros deste domínio apontam para um mesmo registro de destino (ex: vários contratos de um mesmo cliente).
• 1:N (Um para Muitos): Um único registro deste domínio pode possuir vários registros filhos (ex: um contrato registra múltiplos eventos na timeline).
• N:M (Muitos para Muitos): Relação de múltiplos para múltiplos intermediada por uma tabela agregada (Contrato_Opcional) para congelar valores históricos dos opcionais contratados.

---

7. Invariantes (Restrições Absolutas)

• Um contrato aponta para exatamente um veículo. Frotas geram múltiplos contratos.
• Ao aceitar uma proposta, todas as outras propostas abertas para o mesmo veículo são automaticamente marcadas como SUBSTITUIDA.
• A assinatura do contrato e a realização da vistoria podem ocorrer em qualquer ordem. No entanto, se o plano contratado exigir vistoria, a ativação operacional (cobertura) e o status do cliente ativo dependem de ambas estarem concluídas e aprovadas.
• Caso o contrato seja assinado, mas as fotos da vistoria não sejam enviadas pelo cliente dentro do prazo limite parametrizado pelo tenant (ex: vistoria_prazo_envio_dias), o contrato é cancelado automaticamente pelo sistema por decurso de prazo.
• Se a vistoria realizada for reprovada definitivamente na auditoria, o contrato correspondente torna-se inválido e é automaticamente cancelado pelo sistema.
• O PDF do contrato é gerado pelo sistema a partir do template do plano com substituição de variáveis — o texto jurídico não pode ser editado diretamente no contrato.
• Um contrato ATIVO só pode ser cancelado mediante registro de motivo e aprovação do ADMIN ou GESTOR.