Skip to content

PROXIMOS_PASSOS_CPF_CNPJ.md

Latest commit

 

History

History
366 lines (282 loc) · 10.7 KB

PROXIMOS_PASSOS_CPF_CNPJ.md

File metadata and controls

366 lines (282 loc) · 10.7 KB

Próximos Passos - Funcionalidade CPF → CNPJ

✅ Implementação Concluída

Todas as funcionalidades da aba CPF → CNPJ foram implementadas:

  • ✅ Tabela cpf_clients criada no banco de dados
  • ✅ Script de dados mockados (25 registros)
  • ✅ APIs backend (listar, calcular potencial, enriquecer)
  • ✅ Serviço frontend CPFClientService
  • ✅ Componente CPFToCNPJTab com tabela, filtros e gráficos
  • ✅ Componente CPFClientDetail com abas detalhadas
  • ✅ Integração com tabs no ProspectingDashboard
  • ✅ Rotas adicionadas no App.jsx

🚀 Passos Imediatos

1. Executar Scripts SQL no Supabase

Ordem de execução:

  1. Execute create_cpf_clients_table.sql no SQL Editor do Supabase

    • Cria a tabela cpf_clients com todos os campos
    • Configura índices para performance
    • Cria políticas RLS (Row Level Security)
    • Cria trigger para updated_at

  2. Execute create_mock_cpf_clients_data.sql

    • Insere 25 clientes CPF mockados
    • Diferentes perfis (alto, médio, baixo potencial)
    • Mix de status (identified, contacted, converted, rejected)

Verificação:

-- Verificar se a tabela foi criada
SELECT table_name 
FROM information_schema.tables 
WHERE table_schema = 'public' 
AND table_name = 'cpf_clients';

-- Verificar se os dados foram inseridos
SELECT COUNT(*) as total, 
       COUNT(*) FILTER (WHERE status = 'identified') as identified,
       COUNT(*) FILTER (WHERE status = 'converted') as converted,
       COUNT(*) FILTER (WHERE conversion_potential_score >= 70) as high_potential
FROM public.cpf_clients;

-- Verificar alguns registros
SELECT name, cpf, conversion_potential_score, status, priority
FROM public.cpf_clients
ORDER BY conversion_potential_score DESC
LIMIT 10;

2. Testar a Funcionalidade

A. Acessar a Aba CPF → CNPJ

  1. Acesse o Dashboard de Prospecção

    • URL: /prospecting
    • Ou clique em "Prospecção" no menu lateral

  2. Clique na aba "CPF → CNPJ"

    • Você deve ver os cards de métricas (Total CPFs, Alto Potencial, Convertidos, Taxa de Conversão)
    • Gráfico de distribuição de scores
    • Tabela com os clientes CPF

B. Testar Filtros e Busca

  • Testar busca por nome, CPF ou email
  • Testar filtro por status (Identificado, Contatado, Convertido, Rejeitado)
  • Testar filtro por score (Alto ≥70, Médio 50-69, Baixo <50)
  • Testar filtro por prioridade (Alta ≥7, Média 4-6, Baixa <4)
  • Verificar se os filtros funcionam em conjunto

C. Testar Gráficos

  • Alternar entre gráfico de barras, linha e pizza
  • Verificar se a distribuição de scores está correta
  • Validar que os dados do gráfico correspondem aos dados da tabela

D. Testar Ações na Tabela

  • Ver Detalhes: Clicar em uma linha ou no ícone de olho

    • Deve navegar para /prospecting/cpf/:id
    • Verificar se todos os dados são exibidos corretamente

  • Marcar como Contatado: Clicar no ícone de check

    • Verificar se o status muda para "contacted"
    • Verificar se a tabela atualiza

  • Converter para Prospect: Clicar no ícone de target

    • Confirmar a conversão
    • Verificar se o prospect é criado na tabela prospects
    • Verificar se o status do cliente CPF muda para "converted"
    • Verificar se aparece na aba "Prospecção CNPJ"

  • Rejeitar: Clicar no ícone de X

    • Confirmar a rejeição
    • Verificar se o status muda para "rejected"

  • Analisar Selecionados: Selecionar múltiplos clientes e clicar em "Analisar Selecionados"

    • Verificar se os scores são recalculados
    • Verificar se a tabela atualiza

E. Testar Página de Detalhes (/prospecting/cpf/:id)

  • Aba Visão Geral

    • Verificar informações pessoais (nome, CPF, email, telefone, endereço)
    • Verificar resumo financeiro (volume, frequência, receita estimada)
    • Verificar perfil de crédito (score, histórico, produtos bancários)

  • Aba Transações

    • Verificar dados transacionais
    • Verificar perfil de consumo

  • Aba Atividade Empresarial

    • Verificar indicadores de atividade empresarial
    • Verificar sinais de mercado

  • Aba Scoring Detalhado

    • Verificar breakdown do score por fator
    • Testar botão "Recalcular Score"
    • Verificar se os valores são atualizados

  • Ações na Página de Detalhes

    • Testar "Marcar como Contatado"
    • Testar "Converter para Prospect"
    • Testar "Rejeitar"

F. Testar API de Cálculo de Potencial

# Testar cálculo de potencial para um cliente
curl -X POST http://localhost:3000/api/cpf-clients/calculate-potential \
  -H "Content-Type: application/json" \
  -d '{
    "client": {
      "transaction_volume": 50000,
      "transaction_frequency": 30,
      "has_business_indicators": true,
      "business_activity_score": 85,
      "credit_score": 750,
      "digital_presence_score": 80,
      "social_media_activity": 50,
      "banking_products": ["conta_corrente", "cartao_credito", "investimentos"]
    }
  }'

G. Testar API de Enriquecimento

# Testar enriquecimento de clientes CPF
curl -X POST http://localhost:3000/api/cpf-clients/enrich \
  -H "Content-Type: application/json" \
  -d '{
    "clientIds": ["client-id-1", "client-id-2"],
    "sourceConfigs": [{
      "sourceType": "external_api",
      "sourceId": "serasa"
    }]
  }'

3. Validar Integração com Prospecção CNPJ

  • Converter um cliente CPF para prospect
  • Verificar se o prospect aparece na aba "Prospecção CNPJ"
  • Verificar se os dados foram transferidos corretamente
  • Verificar se o score foi preservado
  • Verificar se o histórico de conversão está disponível

4. Testar Integração com Avatar

  • Navegar para a aba "CPF → CNPJ"
  • Fazer uma pergunta ao avatar sobre clientes CPF
  • Verificar se o avatar responde com contexto relevante
  • Testar perguntas como:
    • "Quantos clientes CPF temos com alto potencial?"
    • "Qual o score médio dos clientes CPF?"
    • "Quais clientes CPF devo contatar primeiro?"

5. Verificar Dados Mockados

Execute no Supabase SQL Editor:

-- Verificar distribuição de scores
SELECT 
  CASE 
    WHEN conversion_potential_score >= 80 THEN 'Alto (80-100)'
    WHEN conversion_potential_score >= 60 THEN 'Médio-Alto (60-79)'
    WHEN conversion_potential_score >= 40 THEN 'Médio (40-59)'
    ELSE 'Baixo (<40)'
  END as faixa_score,
  COUNT(*) as quantidade
FROM public.cpf_clients
GROUP BY faixa_score
ORDER BY faixa_score DESC;

-- Verificar distribuição por status
SELECT status, COUNT(*) as quantidade
FROM public.cpf_clients
GROUP BY status
ORDER BY quantidade DESC;

-- Verificar top 10 por potencial
SELECT name, cpf, conversion_potential_score, priority, status, recommended_action
FROM public.cpf_clients
ORDER BY conversion_potential_score DESC, priority DESC
LIMIT 10;

🔍 Checklist de Validação

Funcionalidades Críticas

  • Tabela cpf_clients criada e populada
  • Aba "CPF → CNPJ" aparece no dashboard
  • Cards de métricas exibem dados corretos
  • Tabela lista todos os clientes CPF
  • Filtros funcionam corretamente
  • Gráficos exibem dados corretos
  • Navegação para detalhes funciona
  • Conversão para prospect funciona
  • Atualização de status funciona
  • Cálculo de potencial funciona

Integrações

  • API /api/cpf-clients responde corretamente
  • API /api/cpf-clients/calculate-potential calcula scores
  • API /api/cpf-clients/enrich enriquece dados
  • Conversão cria prospect corretamente
  • Integração com avatar funciona

UI/UX

  • Página carrega sem erros
  • Navegação entre tabs funciona
  • Filtros são intuitivos
  • Ações têm feedback visual
  • Mensagens de erro são claras
  • Loading states aparecem durante operações

📝 Notas Importantes

  1. Dados Mockados: Os 25 clientes CPF são apenas para desenvolvimento. Em produção, os dados virão de:

    • Uploads de planilhas
    • Conexões com bancos de dados externos
    • Integrações com sistemas do banco

  2. Algoritmo de Scoring: O algoritmo atual usa pesos fixos. Em produção, considere:

    • Ajustar pesos baseado em dados históricos
    • Usar machine learning para otimizar
    • Personalizar por segmento de mercado

  3. Conversão para Prospect: Quando um cliente CPF é convertido:

    • Um novo prospect é criado na tabela prospects
    • O status do cliente CPF muda para "converted"
    • O histórico de conversão é preservado

  4. Enriquecimento: O enriquecimento pode ser feito com:

    • APIs externas (Receita Federal, Serasa, etc.)
    • Dados de uploads
    • Dados de conexões de banco de dados

🎯 Próximas Melhorias Sugeridas

  1. Importação em Lote

    • Upload de planilha com múltiplos CPFs
    • Processamento assíncrono
    • Validação de dados

  2. Análise Preditiva

    • Modelo ML para prever probabilidade de conversão
    • Recomendações personalizadas de abordagem
    • Timeline estimada de conversão

  3. Campanhas Automatizadas

    • Campanhas baseadas em score
    • Segmentação automática
    • Acompanhamento de resultados

  4. Dashboard Executivo

    • Métricas agregadas
    • Tendências ao longo do tempo
    • Comparação com benchmarks

🆘 Solução de Problemas

Erro: "Tabela cpf_clients não existe"

  • Execute create_cpf_clients_table.sql primeiro

Erro: "Nenhum dado encontrado"

  • Execute create_mock_cpf_clients_data.sql
  • Verifique se há usuário criado no Supabase

Erro: "Aba não aparece"

  • Verifique se o componente CPFToCNPJTab está importado
  • Verifique se as rotas estão configuradas
  • Recarregue a página

Erro: "Conversão não funciona"

  • Verifique se a API /api/prospects está funcionando
  • Verifique logs do console do navegador
  • Verifique se o usuário está autenticado

✅ Pronto para Produção?

Antes de considerar pronto para produção, verifique:

  • Todos os testes acima foram executados
  • Não há erros no console do navegador
  • Dados são exibidos corretamente
  • Ações funcionam como esperado
  • Performance é aceitável
  • Segurança (RLS) está configurada
  • Documentação está atualizada

🚀 Deploy

Quando estiver pronto:

  1. Commit e Push

    git add .
git commit -m "feat: Implementar aba CPF → CNPJ com mapeamento de clientes"
git push origin develop
git checkout main
git merge develop
git push origin main

  2. Verificar Deploy no Vercel

    • Aguardar deploy automático
    • Testar em produção
    • Verificar logs de erro

  3. Executar Scripts SQL em Produção

    • Executar create_cpf_clients_table.sql no Supabase de produção
    • Executar create_mock_cpf_clients_data.sql (ou importar dados reais)

Boa sorte com os testes! 🎉