Entidade: Anotação#
Visão Geral#
A entidade Anotação representa comentários, observações ou alterações registrados por usuários dentro do contexto de uma negociação ou atividade. Essas anotações são fundamentais para manter um histórico rico de interações, decisões ou mudanças no processo comercial, facilitando a comunicação interna e o acompanhamento de contexto.Estrutura da Entidade#
Campos Principais#
| Campo | Tipo | Descriç ão | Obrigatório |
|---|
id | number | Identificador único da anotação | ✅ (auto) |
text | string | Conteúdo textual da anotação | ✅ |
type | string | Tipo da anotação (observation, alteration) | ✅ |
dealId | number | ID da negociação associada | ❌ |
activityId | number | ID da atividade relacionada | ❌ |
userId | number | ID do usuário que criou a anotação | ✅ (auto) |
createdAt | DateTime | Data/hora de criação da anotação | ✅ (auto) |
updatedAt | DateTime | Data/hora da última atualização | ✅ (auto) |
Relacionamentos#
Usuário: Usuário que criou a anotação
Negociação: Negociação relacionada (opcional)
Atividade: Atividade relacionada (opcional)
Arquivos: Arquivos associados à anotação (anexos)
Tipos Disponíveis#
| Tipo | Descrição |
|---|
observation | Comentário ou observação geral |
alteration | Registro de uma alteração relevante no contexto |
Casos de Uso Detalhados#
1. Comentário Interno Durante Negociação#
Cenário: Um vendedor deseja registrar uma observação após uma reunião com o cliente.O vendedor acessa o CRM e localiza a negociação
Cria uma anotação do tipo observation com o resumo da reunião
A anotação é vinculada automaticamente ao usuário e à negociação
Histórico de conversas acessível
Facilita o entendimento do contexto por outros usuários
2. Registro de Alteração em Processo#
Cenário: Durante uma negociação, uma condição especial foi acordada com o cliente.O usuário cria uma anotação do tipo alteration com os detalhes do acordo
Anexa documentos ou prints relevantes
A anotação pode ser usada como histórico de justificativa
Rastreabilidade de decisões
Melhora a transparência e responsabilidade
Regras de Negócio#
Criação de Anotações#
Associadas automaticamente ao userId autenticado
Permitem associação opcional a dealId ou activityId
type é obrigatório e define o propósito da anotação
Arquivos podem ser vinculados na criação
Edição e Exclusão#
Somente o criador pode editar ou excluir a anotação
Existe um tempo limite para edição (timeEditAnnotation, configurável)
Após esse período, somente administradores podem editar (se permitido)
Anotações podem conter arquivos temporários ou permanentes
Arquivos temporários são movidos para permanentes após criação
Validações#
O campo text deve conter pelo menos 3 caracteres
O tipo deve ser um dos valores permitidos
Apenas uma das associações (dealId ou activityId) pode ser obrigatória conforme o uso
Operações Disponíveis#
| Operação | Descrição | Método HTTP |
|---|
| Listar | Lista todas as anotações (com paginação) | GET |
| Criar | Cria uma nova anotação | POST |
| Visualizar | Recupera uma anotação específica | GET |
| Atualizar | Altera o conteúdo ou tipo da anotação | PUT/PATCH |
| Excluir | Remove uma anotação | DELETE |
Fluxo de Uso#
Segurança e Boas Práticas#
Para Desenvolvedores#
Validar se o userId autenticado é o autor da anotação antes de permitir edição/exclusão
Controlar o tempo limite de edição conforme configuração global
Sanitizar o campo text para evitar injection
Para Usuários#
Use o campo type corretamente para categorizar suas anotações
Não use anotações para armazenar dados sensíveis
Anexe apenas arquivos essenciais e relacionados
Atualize anotações se houver informações incorretas
Limitações e Restrições#
Edição limitada por tempo (configurável)
Usuário comum só acessa anotações da própria empresa
Uma anotação pode estar vinculada a uma negociação ou atividade, mas não a ambas simultaneamente
Não é possível alterar o userId de uma anotação
Modificado em 2025-06-16 13:50:40
