Modelo de Domínio

Entidades, relacionamentos, invariantes e agregados do Gestão de Tráfego.

1. Visão de entidades

Usuario
  │
  ├──< Cliente ──< Relatorio ── (snapshot JSON)
  │        │
  │        ├──< Campanha ──< Diagnostico ──< RespostaDiagnostico
  │        │        │             │
  │        │        │             └──< PlanoCampanha ──< ItemPlano
  │        │        ├──< Metrica
  │        │        └──< Lead ──< InteracaoLead
  │        │
  │        └──< Lead
  │
  ├──< Feedback
  ├──< EventoUso
  ├──< AuditLog
  ├──< TokenEmail
  ├──< Usuario2FA
  ├──< WebhookEvento
  └──< FilaJob

2. Entidades

Usuario

• Invariantes: e-mail único, senha_hash sempre presente.
• Ciclo: criado com email_confirmado_em = null; só loga depois de confirmar.
• Perfis: usuario (default) e admin.
• Relacionamentos: dono de tudo o que é isolado por usuario_id.

TokenEmail

• Tipos: confirmacao_email, reset_senha.
• Invariantes: token_hash único, expira_em futuro, usado_em único por token.
• Uso único: após usado_em, não é reutilizável.

Usuario2FA

• Um por usuário (UNIQUE usuario_id).
• Invariantes: secret presente; confirmado_em define se está ativo.
• Backup codes: armazenados como hash; cada código só funciona uma vez.

Cliente

• Dono: um Usuario (usuario_id obrigatório).
• Invariantes: nome único por usuário (case-insensitive).
• Status: ativo / inativo.
• Relacionamentos: campanhas, relatórios, leads.

Canal

• Catálogo global (não pertence a usuário).
• Invariantes: slug único.
• Seed: Google Ads, Meta Ads, TikTok Ads, Instagram, Outro.
• Uso: FK em campanhas.

Campanha

• Dono: um Usuario + um Cliente.
• Canal: obrigatório (canal_id).
• Status: planejada, ativa, pausada, encerrada.
• Objetivo: leads, vendas, trafego, reconhecimento.
• Invariantes: nome único por usuário.
• Relacionamentos: diagnósticos, planos, métricas, leads.

PerguntaDiagnostico

• Catálogo global.
• Invariantes: slug único, opcoes (JSON) com pelo menos 2 opções.
• Peso: inteiro ≥ 1.
• Seed: 8 perguntas base (objetivo, público, localização, orçamento,
  keywords, anúncios, landing, rastreamento).

Diagnostico

• Dono: um Usuario + uma Campanha.
• Status: em_andamento, concluido.
• Score: inteiro 0–100.
• Classificação: saudavel (≥80), atencao (60–79), risco (40–59), critico (<40).
• Invariantes: no máximo um em_andamento por campanha.
• Ao concluir: calcula problema_principal (maior perda priorizando alta prioridade).

RespostaDiagnostico

• Pertence a: um Diagnostico + uma PerguntaDiagnostico.
• Invariantes: UNIQUE (diagnostico_id, pergunta_id).
• Campos: valor, pontos, recomendacao, prioridade.

PlanoCampanha

• Dono: um Usuario + uma Campanha + opcionalmente um Diagnostico.
• Status: em_andamento, concluido, arquivado.
• Relacionamentos: ItemPlano.
• Geração: a partir de um diagnóstico concluído (via PlanoCampanhaService) ou manual.

ItemPlano

• Pertence a: um PlanoCampanha.
• Categoria: texto livre (Estrutura, Criativos, Rastreamento, …).
• Prioridade: alta, media, baixa.
• Concluído: booleano + concluido_em.

Metrica

• Dono: um Usuario + uma Campanha.
• Invariantes: UNIQUE (campanha_id, data) — um lançamento por dia.
• Campos: investimento, impressões, cliques, leads, vendas, receita.
• Derivados: CTR, CPL, CPA, ROAS, taxa de conversão (calculados em runtime).

Relatorio

• Dono: um Usuario + um Cliente.
• Período: periodo_de ≤ periodo_ate, máximo 1 ano.
• Snapshot: JSON imutável com métricas, diagnósticos e planos no momento da geração.
• Status: gerado.
• Recarregar: recalcula snapshot, mantém período.

Lead

• Dono: um Usuario + um Cliente + opcionalmente uma Campanha.
• Estágio: novo, contatado, proposta, convertido, perdido.
• Origem: google_ads, meta_ads, tiktok_ads, instagram, organico,
  indicacao, outro.
• Timestamps: ultimo_contato_em, convertido_em, perdido_em.
• Invariantes: ao mover para convertido, limpa perdido_em; ao mover
  para perdido, limpa convertido_em e registra motivo_perda.

InteracaoLead

• Pertence a: um Lead.
• Tipos: nota, ligacao, email, whatsapp, reuniao, proposta.
• Invariantes: descrição não vazia.

Feedback

• Dono: um Usuario.
• Tipos: bug, sugestao, duvida, elogio.
• Status: novo, em_analise, resolvido, descartado.
• Contexto: JSON com url, user-agent, IP, viewport.

EventoUso

• Dono: um Usuario (pode ser null para anônimo).
• Eventos canônicos: lista fechada em EventoUsoService::EVENTOS.
• Outros: prefixados com outros. para auditoria.

AuditLog

• Dono: um Usuario (SET NULL ao excluir).
• Entidade + ID: identifica o registro alterado.
• Ação: create, update, delete.
• Diff: JSON com o que mudou; campos sensíveis mascarados com ***.

WebhookEvento

• Origem: google_ads, meta_ads.
• Invariantes: deduplicação por (origem, id_externo) quando processado/processando.
• Status: recebido, processando, processado, erro.
• Payload: JSON bruto; headers sanitizados.

FilaJob

• Fila: default, webhooks, emails.
• Job: classe do handler.
• Retry: tentativas / max_tentativas; backoff exponencial.
• Reserva: reservado_em + reservado_por (worker ID).
• Estados terminais: concluido_em ou falhou_em.

AlertaEnviado

• Chave: identifica o tipo (erro.500, disco.baixo, …).
• Dedup: emCooldown() consulta o último envio da chave.

3. Agregados

4. Regras transversais

1. Isolamento por usuário em todas as operações de leitura e escrita.
2. Upsert idempotente em métricas e fila.
3. Deduplicação em webhooks por ID externo.
4. Timestamps de ciclo de vida em lead (ultimo_contato_em, convertido_em, perdido_em).
5. Snapshot imutável em relatórios; recarregar só quando explicitamente pedido.
6. Não delete físico em usuários (usa ativo = 0).