feat: implementacao inicial do sistema LeadRadar

README.md

@@ -0,0 +1,94 @@
+# 📡 LeadRadar - Automação de Prospecção Ativa & Funil CRM B2B
+
+Plataforma inteligente para prospecção ativa de clientes B2B/B2C no Google Maps a partir da triangulação de CEP e ramo de atividade, enriquecimento de contatos e gestão de funil comercial (Mini-CRM) em quadro Kanban.
+
+---
+
+## 🚀 Arquitetura & Stack Tecnológica
+
+- **Backend API Core:** Python 3.11, Flask 3.x, Flask-SQLAlchemy, Flask-Bcrypt, Flask-JWT-Extended.
+- **Scraper Engine:** Playwright (Chromium Headless) & Geocodificação ViaCEP.
+- **Frontend Dashboard:** Streamlit com componentes customizados em CSS (*Dark Tech Slate*).
+- **Banco de Dados:** PostgreSQL 16 (produção em Docker) / SQLite WAL (desenvolvimento e testes).
+- **Segurança & RBAC:** Autenticação JWT com controle estrito de permissões (Perfil `admin` vs `user`).
+- **Containerização:** Docker & Docker Compose.
+- **Qualidade & Testes:** Pytest (suíte automatizada com 100% de aprovação).
+
+---
+
+## 🛠️ Como Executar o Projeto
+
+### 1. Execução via Docker Compose (Recomendado)
+
+Certifique-se de ter o **Docker** e o **Docker Compose** instalados na sua máquina.
+
+```bash
+# Clone o repositório e acesse a pasta raiz
+cd LeadRadar
+
+# Suba a infraestrutura completa (PostgreSQL + Flask API + Streamlit UI)
+docker-compose up --build -d
+```
+
+Acesse a aplicação no navegador:
+- **Frontend Streamlit UI:** [http://localhost:8501](http://localhost:8501)
+- **Backend API Flask:** [http://localhost:5000/health](http://localhost:5000/health)
+
+---
+
+### 2. Execução Local sem Docker (Desenvolvimento)
+
+#### Backend (Flask API)
+```bash
+cd backend
+python -m venv venv
+# No Windows:
+venv\Scripts\activate
+# No Linux/macOS:
+source venv/bin/activate
+
+pip install -r requirements.txt
+
+# Inicializar o banco de dados e criar o usuário admin padrão
+flask seed-db
+
+# Iniciar o servidor da API
+python -m flask --app app:create_app run --port=5000
+```
+
+#### Frontend (Streamlit UI)
+Em um novo terminal:
+```bash
+cd frontend
+pip install -r requirements.txt
+streamlit run app.py
+```
+
+---
+
+## 🔑 Credenciais Padrão de Acesso Inicial
+
+Ao executar a aplicação ou o comando `flask seed-db`, o seguinte usuário Administrador é criado automaticamente:
+
+- **E-mail:** `admin@leadradar.com`
+- **Senha:** `Admin@123456`
+
+---
+
+## 🧪 Execução da Suíte de Testes Automatizados
+
+A aplicação possui cobertura completa com testes de unidade, integração e regras de segurança RBAC.
+
+```bash
+cd backend
+python -m pytest -v
+```
+
+---
+
+## 🛡️ Segurança, RBAC & Conformidade LGPD
+
+- **Hashing de Senha:** Bcrypt com salt irreversível.
+- **RBAC Decorators:** Permissões restritas ao perfil `admin` para criação/exclusão de operadores e limpeza em lote do banco.
+- **LGPD Opt-Out:** Botão dedicado para marcar leads como "Opt-Out (Excluído)", impedindo re-importação ou novos contatos involuntários.
+- **Logs de Auditoria:** Tabela `lead_interacoes` registrando cada transição de status, alteração de notas e webhooks recebidos.