Entidade: Annotation

Visão Geral

A entidade Annotation representa comentários, observações ou alterações registrados por usuários dentro do contexto de uma negociação (deal) ou atividade (activity). 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

User: Usuário que criou a anotação

Deal: Negociação relacionada (opcional)

Activity: Atividade relacionada (opcional)

Files: 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.

Fluxo:

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

Benefícios:

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.

Fluxo:

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

Benefícios:

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)

Vinculação com Arquivos

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

Annotation

Entidade: Annotation#

Visão Geral#

Estrutura da Entidade#

Campos Principais#

Relacionamentos#

Tipos Disponíveis#

Casos de Uso Detalhados#

1. Comentário Interno Durante Negociação#

2. Registro de Alteração em Processo#

Regras de Negócio#

Criação de Anotações#

Edição e Exclusão#

Vinculação com Arquivos#

Validações#

Operações Disponíveis#

Fluxo de Uso#

Segurança e Boas Práticas#

Para Desenvolvedores#

Para Usuários#

Limitações e Restrições#