silas.brito/leadradar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dfa5315dec03312eaa68748680968a703763643f
leadradar/specs.md
T

11 KiB
Raw Blame History

LeadRadar - Especificação Técnica e Funcional de Arquitetura (specs.md)

1. Visão Geral do Produto

O LeadRadar é uma plataforma de automação para prospecção ativa de clientes (B2B/B2C) e gestão de funil comercial (Mini-CRM). A aplicação automatiza a busca de estabelecimentos comerciais no Google Maps a partir da triangulação de CEP e ramo de atividade, enriquecendo e organizando leads em um pipeline de vendas interativo.

O sistema é construído sobre uma arquitetura híbrida e desacoplada:

  • Backend API & Core Engine: Python / Flask (REST API, persistência, controle de acesso e regras de negócio).
  • Frontend & Dashboard Operacional: Streamlit com componentes customizados em CSS/HTML para proporcionar uma interface responsiva, com identidade visual sóbria, moderna (dark slate / deep tech) e de usabilidade fluida.
  • Integração Externa: Endpoints e Webhooks preparados para orquestração assíncrona via n8n (para futuros fluxos de envio e recepção de mensagens).
  • Containerização: Docker & Docker Compose com isolamento de rede e persistência por volumes.

2. Arquitetura do Sistema e Stack Tecnológica

2.1 Componentes Principais

 ┌─────────────────────────────────────────────────────────────┐
 │                      LeadRadar UI                           │
 │        (Streamlit - Frontend Moderno / Responsivo)          │
 └──────────────────────────────┬──────────────────────────────┘
                                │ HTTP / REST (JWT Bearer)
 ┌──────────────────────────────▼──────────────────────────────┐
 │                      LeadRadar Core                         │
 │              (Flask Application Service)                    │
 │  ┌─────────────────┬───────────────────┬─────────────────┐  │
 │  │ Auth & RBAC     │ Maps Scraper      │ Webhook API     │  │
 │  │ (Flask-JWT-Ext) │ (Playwright Core) │ (Para n8n)      │  │
 │  └────────┬────────┴─────────┬─────────┴────────┬────────┘  │
 └───────────┼──────────────────┼──────────────────┼───────────┘
             │                  │                  │
    ┌────────▼────────┐ ┌───────▼────────┐ ┌───────▼────────┐
    │  SQLite / PG    │ │  ViaCEP &      │ │  Fluxo n8n     │
    │  (SQLAlchemy)   │ │  OSM Nominatim │ │  (Mensageria)  │
    └─────────────────┘ └────────────────┘ └────────────────┘

2.2 Tecnologias Utilizadas

  • Linguagem: Python 3.11+
  • Backend Framework: Flask 3.x, Flask-SQLAlchemy, Flask-Bcrypt, Flask-JWT-Extended, Pydantic (validação).
  • Frontend Framework: Streamlit 1.35+ (com st_shadcn_ui / CSS Injection para tema dark tech sóbrio).
  • Scraping & Geocoding: Playwright (Chromium headless), httpx / requests, APIs de geocodificação (ViaCEP + OpenStreetMap Nominatim).
  • Banco de Dados: PostgreSQL 16 (produção em Docker) / SQLite com WAL mode (desenvolvimento/testes).
  • Testes & Qualidade: Pytest, Pytest-Flask, Pytest-Playwright, Coverage, Black, Flake8, Bandit (SAST).
  • Containerização: Docker (Multi-stage build) & Docker Compose.

3. Controle de Acesso e Autenticação (RBAC)

3.1 Perfis de Acesso

Funcionalidade / Permissão Perfil admin Perfil user
Executar busca de leads no Maps (CEP + Ramo) Sim Sim
Visualizar e movimentar leads no Kanban Sim Sim
Editar notas, etiquetas e contatos de leads Sim Sim
Exportar leads em CSV / JSON Sim Sim
Alterar a própria senha Sim Sim
Criar novos usuários Sim Não
Excluir ou bloquear usuários Sim Não
Resetar senha de terceiros Sim Não
Limpeza / Expurgar banco de dados e logs Sim Não
Configurar webhooks e credenciais de integração Sim Não

3.2 Segurança de Autenticação

  • Armazenamento de senhas utilizando hash seguro via Bcrypt com fator de custo (rounds) \ge 12.
  • Sessões autenticadas via JWT (JSON Web Tokens) trafegados no cabeçalho Authorization: Bearer <token> ou cookies HTTP-Only seguros com tempo de expiração (access_token: 8 horas, refresh_token: 7 dias).

4. Modelagem de Dados

4.1 Entidade users

  • id (UUID / Integer PK)
  • nome (VARCHAR(120), Not Null)
  • email (VARCHAR(180), Unique, Indexed, Not Null)
  • password_hash (VARCHAR(255), Not Null)
  • role (ENUM: 'admin', 'user', Default: 'user')
  • ativo (BOOLEAN, Default: True)
  • criado_em (DATETIME, Default: UTC Now)
  • atualizado_em (DATETIME, On Update: UTC Now)

4.2 Entidade leads

  • id (UUID / Integer PK)
  • nome_empresa (VARCHAR(255), Indexed, Not Null)
  • ramo_atividade (VARCHAR(100), Indexed, Not Null)
  • cep_busca (VARCHAR(10), Indexed, Not Null)
  • logradouro (VARCHAR(255))
  • bairro (VARCHAR(100))
  • cidade (VARCHAR(100), Indexed)
  • uf (VARCHAR(2))
  • telefone (VARCHAR(50))
  • telefone_sanitizado (VARCHAR(30), Indexed) # Formato E.164 (ex: 5511999999999)
  • whatsapp_valido (BOOLEAN, Nullable)
  • website (VARCHAR(255))
  • google_rating (FLOAT, Default: 0.0)
  • total_avaliacoes (INTEGER, Default: 0)
  • google_maps_url (TEXT)
  • status_funil (ENUM: 'novo', 'contatado', 'respondeu', 'negociacao', 'ganho', 'perdido')
  • tags (JSON / Array de tags customizadas)
  • notas (TEXT)
  • usuario_responsavel_id (FK -> users.id, Nullable)
  • criado_em (DATETIME, Default: UTC Now)
  • atualizado_em (DATETIME, On Update: UTC Now)

4.3 Entidade lead_interacoes (Histórico & Auditoria)

  • id (UUID / Integer PK)
  • lead_id (FK -> leads.id, On Delete Cascade)
  • usuario_id (FK -> users.id, Nullable)
  • tipo (ENUM: 'status_change', 'nota_adicionada', 'mensagem_enviada', 'webhook_n8n')
  • descricao (TEXT)
  • metadados (JSONB / TEXT)
  • timestamp (DATETIME, Default: UTC Now)

5. Módulo de Automação & Busca de Leads

5.1 Fluxo de Triangulação de CEP

  1. Usuário informa o CEP (ex: 01310-100) e o Ramo de Atuação (ex: Clínica Odontológica, Padaria, Restaurante).
  2. O sistema consome a API do ViaCEP (https://viacep.com.br/ws/{cep}/json/) para obter bairro, município e UF.
  3. Se necessário, resolve a latitude/longitude via Nominatim OpenStreetMap ou monta a string de busca contextualizada: "{ramo} em {bairro}, {municipio} - {uf}".
  4. O scraper do Google Maps (Playwright) abre a busca com rolagem dinâmica e extrai os metadados dos estabelecimentos.

5.2 Regras de Deduplicação

  • Deduplicação automática baseada na combinação de (nome_empresa, telefone_sanitizado, cidade).
  • Se o lead já existir na base, atualiza apenas dados cadastrais se houver novos campos (sem resetar o status_funil).

6. Interface Visual e Experiência do Usuário (UI/UX)

6.1 Diretrizes de Design

  • Paleta de Cores: Fundo escuro grafite/ardósia (#0D1117, #161B22), bordas sutis (#30363D), tipografia com alto contraste e legibilidade (#E6EDF3, #8B949E), e acentos em azul tecnológico (#1F6FEB, #58A6FF).
  • Navegação Modular:
    • Radar de Busca: Formulário limpo com validação de CEP, seleção de ramo e indicador visual de progresso da varredura.
    • Funil CRM (Kanban): Colunas interativas com cards compactos, tags coloridas por ramo, nota do Google e atalho rápido para WhatsApp/edição de status.
    • Tabela Analítica / Exportação: Visualização tabular com filtros avançados, ordenação e exportação em CSV/XLSX.
    • Administração: Painel exclusivo para administradores com criação/exclusão de operadores, logs de auditoria e configurações.
    • Perfil / Segurança: Modal ou tela para alteração segura de senha pelo próprio usuário logado.

7. Conformidade com a LGPD e Segurança da Informação

  1. Princípio da Finalidade e Necessidade (Art. 6º, I e III):
    • Coleta restrita a dados comerciais publicamente disponibilizados pelos próprios estabelecimentos comerciais no Google Maps para fins legítimos de prospecção B2B (Art. 7º, IX - Legítimo Interesse).
  2. Direito de Eliminação / Opt-Out (Art. 18, VI):
    • Mecanismo integrado para marcar leads como "Não Contatar / Excluído", garantindo que novos disparos ou re-importações não reativem o contato.
  3. Auditoria e Rastreabilidade:
    • Log de todas as ações sensíveis (exportações, exclusões de leads, cadastros de usuários) com timestamp e ID do usuário executor.
  4. Segurança de Dados em Trânsito e Repouso:
    • Comunicação interna e externa sob TLS/HTTPS em ambiente de produção; senhas com salt/hashing irreversível.

8. Arquitetura Docker & Deployment

A aplicação deve conter:

  • Dockerfile.backend: Multi-stage build otimizado para a API Flask + Playwright (instalando dependências do Chromium headless).
  • Dockerfile.frontend: Imagem leve para o Streamlit.
  • docker-compose.yml: Orquestração contendo os serviços:
    • leadradar-db (PostgreSQL 16 com volume persistente).
    • leadradar-api (Flask Backend).
    • leadradar-ui (Streamlit Frontend).
  • Arquivo .env.example estruturado com segredos (JWT_SECRET_KEY, POSTGRES_PASSWORD, FLASK_ENV).

9. Plano de Testes e Garantia de Qualidade

  1. Testes Unitários:
    • Validação de funções de formatação/sanitização de telefone e CEP.
    • Hashing e validação de senhas com Bcrypt.
    • Verificação de políticas RBAC (permissões de Admin vs User).
  2. Testes de Integração:
    • Endpoints de autenticação (/api/v1/auth/login, /api/v1/auth/change-password).
    • CRUD de usuários (garantindo que user receba 403 Forbidden ao tentar criar/deletar).
    • Inserção e atualização de leads e interações.
  3. Testes End-to-End (E2E):
    • Mock e execução do crawler de busca geolocalizada via Playwright.
    • Fluxo completo de busca -> salvamento no banco -> movimentação no Kanban.
Reference in New Issue View Git Blame Copy Permalink