Regras do Produto

Regras de negócio que o sistema impõe. Toda regra listada aqui tem
implementação em algum Service.

1. Autenticação e conta

• Confirmação obrigatória. O usuário só loga após confirmar o e-mail.
• Reenvio automático. Tentar logar com e-mail não confirmado dispara novo token.
• Reset de senha reenvia confirmação. Se o e-mail ainda não foi validado,
  a recuperação reenvia a confirmação em vez de gerar token de reset.
• Tokens de uso único. Cada token só pode ser consumido uma vez.
• Expiração padrão: 24h (TOKEN_EXPIRATION_HOURS).
• Política de senha: mínimo 10 caracteres, bloqueio de senhas comuns e de
  senhas que contenham nome/e-mail do usuário.
• 2FA opcional. Uma vez ativado, todo login exige código TOTP ou backup code.
• Backup codes: 8 por ativação, cada um só funciona uma vez.
• Rate limiting: login, cadastro, reset e desafio 2FA.

2. Isolamento por usuário

• Toda operação é escopada por usuario_id.
• Um usuário nunca vê, edita ou exclui dados de outro.
• Webhooks resolvem o usuario_id a partir do cliente_id do payload.

3. Clientes

• Nome único por usuário (case-insensitive).
• Excluir um cliente remove em cascata campanhas, leads e relatórios.
• Status possíveis: ativo, inativo.

4. Campanhas

• Nome único por usuário.
• Canal obrigatório.
• Cliente obrigatório (do mesmo usuário).
• Orçamento ≥ 0 e ≤ 1.000.000.
• Data de fim ≥ data de início.
• Status: planejada, ativa, pausada, encerrada.
• Objetivo: leads, vendas, trafego, reconhecimento.

5. Diagnóstico

• No máximo um diagnóstico em andamento por campanha.
• Todas as perguntas ativas precisam ser respondidas antes de concluir.
• Score 0–100 calculado a partir dos pesos e pontos.
• Classificação:
  • saudavel: score ≥ 80
  • atencao: 60 ≤ score < 80
  • risco: 40 ≤ score < 60
  • critico: score < 40
• Problema principal: prioridade alta primeiro; empate pela maior perda absoluta.
• Recomendações agrupadas por prioridade (alta, media, baixa).

6. Plano de execução

• Gerado a partir de um diagnóstico concluído ou manualmente.
• Ao gerar a partir do diagnóstico, cria ~14 itens em 6 categorias:
  Estrutura, Palavras-chave, Criativos, Landing page, Rastreamento,
  Lançamento, Otimização.
• Cada item tem categoria, prioridade (alta, media, baixa) e ordem.
• Progresso = itens_concluidos / itens_total * 100.
• Excluir o plano remove os itens em cascata.

7. Métricas

• Um lançamento por campanha/dia (UNIQUE (campanha_id, data)).
• Reenviar o mesmo dia sobrescreve (upsert).
• Não permitir data futura.
• Coerência obrigatória:
  • cliques ≤ impressões (quando impressões > 0)
  • leads ≤ cliques (quando cliques > 0)
  • vendas ≤ leads (quando leads > 0)
• Valores negativos não são permitidos.
• Cálculos derivados: CTR, CPL, CPA, ROAS, taxa de conversão (arredondados a 2 casas).
• Importação CSV:
  • Máximo 5 MB e 10.000 linhas.
  • A primeira linha deve ter cabeçalhos.
  • Campanha identificada pelo nome exato.
  • Datas aceitas em Y-m-d, d/m/Y, m/d/Y, Y/m/d, d-m-Y.
  • Upsert idempotente por (campanha_id, data).

8. Relatórios

• Período máximo de 1 ano.
• periodo_de ≤ periodo_ate.
• Snapshot imutável gravado na geração.
• Recarregar recalcula o snapshot (ação explícita do usuário).
• Próximos passos são gerados dinamicamente conforme os dados.

9. Leads (CRM)

• Cliente obrigatório; campanha opcional.
• Estágios: novo, contatado, proposta, convertido, perdido.
• Mover para convertido limpa perdido_em e motivo_perda.
• Mover para perdido limpa convertido_em e aceita motivo.
• Cada movimentação registra interação automática.
• Interação exige descrição não vazia.
• Valor potencial ≥ 0.

10. Webhooks

• Assinatura HMAC obrigatória em produção.
• Deduplicação por (origem, id_externo) quando já processado/processando.
• Payload deve ser JSON válido.
• Origem deve estar em config/webhooks.php.
• Fila com retry exponencial: 30s, 60s, 120s, 240s, 480s (máx 5 tentativas).
• Meta Ads: verificação inicial via hub.challenge + hub.verify_token.

11. Fila

• Filas: default, webhooks, emails.
• Retry exponencial configurável.
• Job com falha definitiva fica em falhou_em (não retenta).
• Reserva expira após reserve_timeout segundos.

12. Auditoria

• Habilitada por repositório ($auditable = true).
• Campos sensíveis mascarados com ***: senha, senha_hash, password,
  token, token_hash, secret, backup_codes, remember_token.
• Só registra o que mudou (update).
• Nunca quebra a operação se falhar (try/catch silencioso).

13. Alertas

• Deduplicação por chave dentro de dedup_horas (padrão 6h).
• Chaves canônicas: erro.500, disco.baixo, backup.falhou,
  erros.500.lote, teste.manual.
• Silenciosos em APP_DEBUG=true ou APP_ENV=testing.
• Sempre enviados para ADMIN_EMAILS.

14. Admin

• Acesso restrito a usuários com perfil = 'admin' ou listados em ADMIN_USER_IDS.
• Painel mostra: uso, saúde, alertas, fila, webhooks.
• Nunca altera dados de clientes diretamente (é somente leitura).

15. Cache

• TTLs curtos: dashboard 60s, métricas 90s, listagens 120s.
• Invalidação por namespace após qualquer escrita relacionada.
• Desabilitado em testes (CACHE_ENABLED=false).

16. Importação e exportação

• Exportação CSV: separador ;, BOM UTF-8, floats em pt-BR.
• Importação CSV: detecta separador, remove BOM, converte ISO-8859-1 → UTF-8.
• Nomes de campanha comparados após normalização (lowercase, sem acentos).