185 lines
11 KiB
Markdown
185 lines
11 KiB
Markdown
# 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.
|