Entidade: Tarefa

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

Regras de comportamento: ver Regras de Negócio/Módulo 14: Tarefas & Follow-up

---

1. Definição

Uma Tarefa é uma unidade de atividade agendada associada a um operador (consultor ou gestor) com o objetivo de dar andamento a um processo comercial ou operacional no CRM.

As tarefas podem ser cadastradas voluntariamente (Manuais) ou proativamente disparadas por regras do sistema (Automáticas/Gatilhos) para evitar a estagnação de negociações, vistorias e contratos.

---

2. Atributos Principais

Campo	Tipo	Obrigatório	Notas
id	UUID	Sim	Gerado pelo sistema
tenant_id	UUID	Sim	FK → Tenant
responsavel_id	UUID	Sim	FK → Usuário (dono atual da tarefa)
criador_id	UUID	Sim	FK → Usuário (ou ID do sistema para tarefas automáticas)
tipo	enum	Sim	LIGACAO, WHATSAPP, EMAIL, REUNIAO, LEMBRETE, SISTEMA. Ver Tipos de Tarefa
titulo	string	Sim	Resumo descritivo da ação
descricao	text	Não	Detalhes adicionais e instruções
data_prevista	timestamp	Sim	Prazo estipulado para a realização da tarefa
status	enum	Sim	PENDENTE, CONCLUIDA, CANCELADA
vinculo_tipo	enum	Não	Mapeamento Polimórfico: `LEAD
vinculo_id	UUID	Não	ID da entidade relacionada conforme vinculo_tipo
gerada_pelo_sistema	boolean	Sim	Define se a tarefa foi fruto de gatilho do sistema
data_conclusao	timestamp	Não	Preenchido quando o status muda para CONCLUIDA
created_at	timestamp	Sim	Registra o momento de criação da tarefa
updated_at	timestamp	Sim	Registra o momento da última modificação dos dados da tarefa

---

3. Tipos de Tarefa (tipo)

• LIGACAO: Lembrete de ligação telefônica agendada com o cliente.
• WHATSAPP: Envio de mensagem pelo WhatsApp.
• EMAIL: Envio de mensagem de correio eletrônico.
• REUNIAO: Compromisso presencial ou videoconferência.
• LEMBRETE: Anotação geral ou tarefa sem canal específico.
• SISTEMA: Tarefa de acompanhamento automático criada por gatilho do CRM (ex: cobrança de documentos).

---

4. Relacionamentos

Tarefa ──── pertence a ────── Tenant                   (N:1)
Tarefa ──── atribuída a ───── Usuário (Responsável)     (N:1)
Tarefa ──── criada por ────── Usuário (Criador/Sistema) (N:1)
Tarefa ──── aponta para ───── Entidades Polimórficas   (N:1 — via vinculo_tipo e vinculo_id)

Legenda de Cardinalidade:

• N:1 (Muitos para Um): Múltiplos registros deste domínio apontam para um mesmo registro de destino (ex: várias tarefas atribuídas ao mesmo usuário, ou apontando para a mesma entidade relacionada).

---

5. Invariantes (Restrições Absolutas)

• A data_prevista não deve aceitar datas do passado no momento de sua criação manual.
• O mapeamento polimórfico exige que, caso vinculo_tipo esteja preenchido, vinculo_id deve ser obrigatoriamente preenchido com uma FK válida do tipo especificado.
• A conclusão de uma tarefa (status = CONCLUIDA) exige obrigatoriamente o preenchimento de data_conclusao com o timestamp corrente.
• Se uma entidade que possui tarefas pendentes (ex: um Lead) for redistribuída ou transferida de usuário no CRM, o responsavel_id de todas as suas tarefas com status PENDENTE deve ser atualizado automaticamente para o ID do novo proprietário.