Visão Geral#
A entidade Proposta 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 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#
Negociação: Vinculada a uma negociação específica.
Empresa: Vinculada à empresa do usuário (via Deal).
Característica da Proposta: Itens adicionais associados à proposta.
Produtos Customizados da Proposta: 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.1.
O usuário fornece dados da proposta, incluindo logo do cliente e produtos personalizados.
2.
O sistema gera um PDF com informações do cliente, produtos, itens adicionais e imagens.
3.
O PDF é armazenado no S3, e a proposta é registrada no banco.
4.
Itens adicionais e produtos personalizados são associados à proposta.
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: Característica da Proposta#
Visão Geral#
A entidade Característica da Proposta 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#
Proposta: 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#
Cenário: Um usuário deseja incluir taxas de entrega e descontos em uma proposta.1.
Durante a criação da proposta, o usuário adiciona itens como "Frete" e "Desconto Promocional".
2.
Os itens são registrados com tipo, descrição e valor (se aplicável).
3.
Os valores são usados no cálculo final do PDF gerado.
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: Produtos Customizados da Proposta#
Visão Geral#
A entidade Produtos Customizados da Proposta 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#
Proposta: 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.1.
Durante a criação da proposta, o usuário adiciona produtos personalizados com título, descrição e imagens.
2.
As imagens são movidas para um destino final no S3.
3.
Os produtos são registrados e associados à proposta.
4.
As imagens aparecem no PDF gerado.
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.
Modificado em 2025-06-16 16:56:26
