Entidade: Proposal

Visão Geral

A entidade Proposal representa propostas comerciais geradas para negociações, contendo informações detalhadas sobre produtos, itens adicionais e personalizações. As propostas são vinculadas a uma negociação (Deal) e geram um documento PDF armazenado em um serviço de armazenamento (S3).

Estrutura da Entidade

Campos Principais

Campo	Tipo	Descrição	Obrigatório
id	number	Identificador único da proposta	✅ (auto)
title	string	Título descritivo da proposta	✅
dealId	number	ID da negociação associada	✅
pdfUrl	string	URL do arquivo PDF gerado	✅ (auto)
customerLogo	string	URL do logo do cliente (opcional)	❌
status	enum	Status da proposta (pending, approved, rejected)	✅
createdAt	DateTime	Data/hora de criação	✅ (auto)
updatedAt	DateTime	Data/hora da última atualização	✅ (auto)

Relacionamentos

Deal: Vinculada a uma negociação específica.

Company: Vinculada à empresa do usuário (via Deal).

ProposalCharacteristic: Itens adicionais associados à proposta.

CustomProductProposal: Produtos personalizados associados à proposta.

Status Disponíveis

Status	Descrição
pending	Proposta aguardando aprovação
approved	Proposta aprovada
rejected	Proposta rejeitada

Casos de Uso Detalhados

1. Geração de Proposta Comercial

Cenário: Um usuário deseja criar uma proposta comercial para uma negociação, incluindo produtos e itens adicionais.

Fluxo:

O usuário fornece dados da proposta, incluindo logo do cliente e produtos personalizados.

O sistema gera um PDF com informações do cliente, produtos, itens adicionais e imagens.

O PDF é armazenado no S3, e a proposta é registrada no banco.

Itens adicionais e produtos personalizados são associados à proposta.

Benefícios: Automação na criação de documentos profissionais e centralização de informações.

Regras de Negócio

Criação de Propostas

Vinculação automática à negociação e à empresa do usuário autenticado.

Status inicial definido como pending.

Arquivos (logos, imagens de produtos) são movidos para um destino final no S3.

O PDF é gerado com base em um modelo dinâmico, incluindo imagens e cálculos financeiros.

Controle de Acesso

Usuários só podem gerenciar propostas de negociações de sua empresa.

Usuários comuns só acessam propostas de negociações que possuem.

Isolamento por empresa (multi-tenancy).

Segurança

Validação de arquivos para garantir existência e formato correto.

Normalização de nomes de arquivos para evitar caracteres inválidos.

Integração segura com o serviço de armazenamento S3.

Operações Disponíveis

Operação	Descrição	Método HTTP
Listar	Recupera propostas com paginação	GET
Criar	Cria uma nova proposta e gera PDF	POST
Visualizar	Exibe detalhes de uma proposta específica	GET
Atualizar	Modifica os dados da proposta	PUT/PATCH

Fluxo de Uso

Segurança e Boas Práticas

Para Desenvolvedores

Validar URLs de arquivos e formatos de imagem antes do processamento.

Usar transações para garantir consistência ao criar propostas e associações.

Garantir que nomes de arquivos sejam sanitizados para evitar erros.

Para Usuários

Fornecer imagens de alta qualidade para logos e produtos.

Revisar itens adicionais antes de gerar a proposta.

Verificar o PDF gerado para garantir que todas as informações estão corretas.

Limitações e Restrições

Propostas são específicas por negociação e empresa.

Geração de PDF depende de integração com serviço S3.

Imagens devem estar em formatos suportados (PNG, JPEG, WebP).

Entidade: ProposalCharacteristic

Visão Geral

A entidade ProposalCharacteristic representa itens adicionais associados a uma proposta, como taxas de entrega, descontos ou observações, permitindo personalização financeira e descritiva.

Estrutura da Entidade

Campos Principais

Campo	Tipo	Descrição	Obrigatório
id	number	Identificador único do item adicional	✅ (auto)
type	enum	Tipo do item (delivery_charges, additional_charges, discount, observation)	✅
description	string	Descrição do item (opcional)	❌
value	number	Valor monetário do item (opcional)	❌
proposalId	number	ID da proposta associada	✅
createdAt	DateTime	Data/hora de criação	✅ (auto)
updatedAt	DateTime	Data/hora da última atualização	✅ (auto)

Relacionamentos

Proposal: Vinculada a uma proposta específica.

Tipos Disponíveis

Tipo	Descrição
delivery_charges	Taxas de entrega
additional_charges	Taxas adicionais
discount	Descontos aplicados
observation	Observações descritivas

Casos de Uso Detalhados

1. Adição de Custos Extras

Cenário: Um usuário deseja incluir taxas de entrega e descontos em uma proposta.

Fluxo:

Durante a criação da proposta, o usuário adiciona itens como "Frete" e "Desconto Promocional".

Os itens são registrados com tipo, descrição e valor (se aplicável).

Os valores são usados no cálculo final do PDF gerado.

Benefícios: Flexibilidade para personalizar custos e observações na proposta.

Regras de Negócio

Criação de Itens

Itens são criados automaticamente ao gerar uma proposta com itens adicionais.

Tipo e descrição são obrigatórios para itens do tipo observation.

Valores são obrigatórios para itens do tipo delivery_charges, additional_charges e discount.

Controle de Acesso

Itens são gerenciados indiretamente via propostas.

Isolamento por empresa (via Proposal).

Segurança

Validação de tipos de itens para garantir consistência.

Exclusão de itens ocorre automaticamente com a exclusão da proposta.

Operações Disponíveis

Operação	Descrição	Método HTTP
Criar	Cria itens adicionais durante a proposta	POST (auto)
Visualizar	Exibe itens via proposta	GET (via Proposal)

Fluxo de Uso

Segurança e Boas Práticas

Para Desenvolvedores

Validar tipos e valores dos itens para evitar cálculos incorretos.

Usar transações para criar itens junto com a proposta.

Para Usuários

Fornecer descrições claras para itens.

Revisar valores de descontos e taxas antes de incluir.

Usar observações apenas para informações não financeiras.

Limitações e Restrições

Itens são específicos por proposta.

Não podem ser criados ou editados diretamente, apenas via proposta.

Entidade: CustomProductProposal

Visão Geral

A entidade CustomProductProposal representa produtos personalizados associados a uma proposta, permitindo a inclusão de itens não cadastrados no sistema, com títulos, descrições e imagens.

Estrutura da Entidade

Campos Principais

Campo	Tipo	Descrição	Obrigatório
id	number	Identificador único do produto personalizado	✅ (auto)
productTitle	string	Título do produto personalizado	✅
productDescription	string	Descrição do produto (opcional)	❌
productUrlFiles	string	URL de arquivo de imagem do produto (opcional)	❌
proposalId	number	ID da proposta associada	✅
createdAt	DateTime	Data/hora de criação	✅ (auto)
updatedAt	DateTime	Data/hora da última atualização	✅ (auto)

Relacionamentos

Proposal: Vinculada a uma proposta específica.

Casos de Uso Detalhados

1. Inclusão de Produtos Personalizados

Cenário: Um usuário deseja adicionar produtos únicos a uma proposta, com imagens específicas.

Fluxo:

Durante a criação da proposta, o usuário adiciona produtos personalizados com título, descrição e imagens.

As imagens são movidas para um destino final no S3.

Os produtos são registrados e associados à proposta.

As imagens aparecem no PDF gerado.

Benefícios: Flexibilidade para incluir itens fora do catálogo padrão.

Regras de Negócio

Criação de Produtos Personalizados

Produtos são criados automaticamente ao gerar uma proposta com produtos personalizados.

Pelo menos uma imagem é obrigatória por produto.

Arquivos de imagem são movidos para um destino final no S3.

Controle de Acesso

Produtos são gerenciados indiretamente via propostas.

Isolamento por empresa (via Proposal).

Segurança

Validação de URLs de arquivos para garantir existência.

Exclusão de produtos ocorre automaticamente com a exclusão da proposta.

Operações Disponíveis

Operação	Descrição	Método HTTP
Criar	Cria produtos personalizados durante a proposta	POST (auto)
Visualizar	Exibe produtos via proposta	GET (via Proposal)

Fluxo de Uso

Segurança e Boas Práticas

Para Desenvolvedores

Validar URLs de imagens e garantir formatos suportados.

Usar transações para criar produtos junto com a proposta.

Garantir que arquivos sejam movidos corretamente no S3.

Para Usuários

Fornecer títulos descritivos para produtos.

Usar imagens de alta qualidade para melhor apresentação no PDF.

Verificar se todas as imagens foram carregadas corretamente.

Limitações e Restrições

Produtos são específicos por proposta.

Não podem ser criados ou editados diretamente, apenas via proposta.

Requer pelo menos uma imagem por produto.

Proposal

Entidade: Proposal#

Visão Geral#

Estrutura da Entidade#

Campos Principais#

Relacionamentos#

Status Disponíveis#

Casos de Uso Detalhados#

1. Geração de Proposta Comercial#

Regras de Negócio#

Criação de Propostas#

Controle de Acesso#

Segurança#

Operações Disponíveis#

Fluxo de Uso#

Segurança e Boas Práticas#

Para Desenvolvedores#

Para Usuários#

Limitações e Restrições#

Entidade: ProposalCharacteristic#

Visão Geral#

Estrutura da Entidade#

Campos Principais#

Relacionamentos#

Tipos Disponíveis#

Casos de Uso Detalhados#

1. Adição de Custos Extras#

Regras de Negócio#

Criação de Itens#

Controle de Acesso#

Segurança#

Operações Disponíveis#

Fluxo de Uso#

Segurança e Boas Práticas#

Para Desenvolvedores#

Para Usuários#

Limitações e Restrições#

Entidade: CustomProductProposal#

Visão Geral#

Estrutura da Entidade#

Campos Principais#

Relacionamentos#

Casos de Uso Detalhados#

1. Inclusão de Produtos Personalizados#

Regras de Negócio#

Criação de Produtos Personalizados#

Controle de Acesso#

Segurança#

Operações Disponíveis#

Fluxo de Uso#

Segurança e Boas Práticas#

Para Desenvolvedores#

Para Usuários#

Limitações e Restrições#

Entidade: Proposal

Visão Geral

Estrutura da Entidade

Campos Principais

Relacionamentos

Status Disponíveis

Casos de Uso Detalhados

1. Geração de Proposta Comercial

Regras de Negócio

Criação de Propostas

Controle de Acesso

Segurança

Operações Disponíveis

Fluxo de Uso

Segurança e Boas Práticas

Para Desenvolvedores

Para Usuários

Limitações e Restrições

Entidade: ProposalCharacteristic

Visão Geral

Estrutura da Entidade

Campos Principais

Relacionamentos

Tipos Disponíveis

Casos de Uso Detalhados

1. Adição de Custos Extras

Regras de Negócio

Criação de Itens

Controle de Acesso

Segurança

Operações Disponíveis

Fluxo de Uso

Segurança e Boas Práticas

Para Desenvolvedores

Para Usuários

Limitações e Restrições

Entidade: CustomProductProposal

Visão Geral

Estrutura da Entidade

Campos Principais

Relacionamentos

Casos de Uso Detalhados

1. Inclusão de Produtos Personalizados

Regras de Negócio

Criação de Produtos Personalizados

Controle de Acesso

Segurança

Operações Disponíveis

Fluxo de Uso

Segurança e Boas Práticas

Para Desenvolvedores

Para Usuários

Limitações e Restrições