# 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 ` 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.