# ProspectOS
### Prospecção de leads no piloto automático: do Google Maps e Instagram direto pro seu CRM
Encontre pequenos negócios locais **sem site ou com site ruim**, receba a estratégia
de abordagem e a mensagem prontas por IA, gere um diagnóstico em PDF e acompanhe tudo
num CRM visual — do primeiro contato ao fechamento.
[](https://github.com/nando0x/ProspectOS)
---
## 📋 Índice
- [O que é](#-o-que-é)
- [⚠️ Antes de usar](#️-antes-de-usar)
- [Features](#-features)
- [Quickstart](#-quickstart)
- [Uso no dia a dia](#-uso-no-dia-a-dia)
- [Stack](#-stack)
- [Estrutura do projeto](#-estrutura-do-projeto)
- [Filosofia do projeto](#-filosofia-do-projeto)
- [Perguntas comuns](#-perguntas-comuns)
- [Contribuindo](#-contribuindo)
- [Licença](#-licença)
- [Agradecimentos](#-agradecimentos)
---
## 🎯 O que é
**ProspectOS** é uma ferramenta de prospecção de leads para quem vende sites, landing pages ou serviços digitais para pequenos negócios locais.
Ela resolve um problema específico de ponta a ponta: encontrar empresas que **precisam de um site** e transformá-las em conversas de venda. O ProspectOS varre o **Google Maps** (por nicho + cidade, ou por pino e raio num mapa) e os **comentários de posts do Instagram**, **analisa o site de cada empresa** para separar quem não tem site de quem tem um site ruim/lento/inseguro, prioriza por um score, e para cada lead entrega a **estratégia de abordagem**, a **mensagem pronta por IA** e um **diagnóstico em PDF** para mandar no WhatsApp — tudo num CRM visual com funil, follow-up e analytics.
**Para quem é:**
- Freelancers e agências de web design/landing pages que fazem a própria prospecção
- Devs e estudantes que querem estudar scraping, integração com IA e um CRM full-stack na prática
- Qualquer pessoa curiosa sobre como automatizar geração de leads locais
**Por que foi criado:** nasceu como ferramenta pessoal para simplificar um processo manual e repetitivo (abrir o Maps, checar site por site, anotar em planilha) e cresceu até virar uma ferramenta de prospecção completa. É uma base de código real e funcional, aberta para você aprender, adaptar e usar por sua conta.
> 💡 Continua sendo software que você roda localmente, na sua máquina, por sua conta e risco — não um SaaS pronto. Leia os avisos abaixo antes de usar.
---
## ⚠️ Antes de usar
Leia isto com atenção antes de rodar qualquer coisa:
- 🕷️ **Isto é uma ferramenta de scraping.** Raspar o Google Maps e o Instagram pode violar os Termos de Uso dessas plataformas. Use por sua conta e risco.
- 📸 **O módulo do Instagram usa sua conta pessoal** (via [instagrapi](https://github.com/subzeroid/instagrapi)) para logar e consultar dados. Isso pode resultar em **checkpoint de segurança ou banimento temporário/permanente da conta**. Recomendado: use uma conta secundária, rode com moderação, e nunca compartilhe o arquivo de sessão gerado.
- 💬 **O cockpit de conversa lê a janela do WhatsApp Web do app.** A leitura é **passiva** (só observa o chat que *você* abriu, nunca navega nem varre conversas) e **nenhuma mensagem é enviada automaticamente** — você revisa e envia sempre. Ainda assim, automatizar o WhatsApp Web contra os Termos de Uso da Meta traz **risco de bloqueio do seu número**. Não existe implementação "indetectável": quem promete isso está mentindo. Se preferir risco zero, o cockpit funciona 100% no modo manual (você cola as mensagens) — inclusive no navegador, sem o app de desktop.
- 🔧 **Sem garantia de funcionamento contínuo.** Instagram e Google mudam suas proteções com frequência. Se algo parar de funcionar, é provavelmente por isso.
- 🚫 **Sem afiliação** com Google, Meta/Instagram, nem com os projetos de terceiros usados (`gosom/google-maps-scraper`, `instagrapi`).
- 📄 Fornecido **"como está"**, sem garantias. Veja [`LICENSE`](LICENSE) (MIT).
- 🪟 **Windows apenas.** Os scripts de conveniência (`.bat`) e o binário do scraper de Maps são específicos para Windows.
---
## ✨ Features
| Área | O que faz |
|---|---|
| 🗺️ **Canal Google Maps** | Busca por nicho + cidade **ou por pino e raio num mapa** (estilo segmentação do Facebook Ads), com catálogo de 170+ nichos clicáveis |
| 🔎 **Análise de site real** | Abre o site de cada empresa e detecta **sem site, site fora do ar, sem HTTPS, SSL inválido, não-mobile, lento ou feito em construtor pronto** (Wix, Canva...) — site ruim também é lead |
| 🩻 **Raio-X do site** | Extrai do HTML o que o site **tem e o que falta** (WhatsApp, telefone, e-mail, mapa, fotos, meta description, favicon) — dado real, não chute |
| 📄 **Diagnóstico em PDF** | Relatório de uma página pronto pra mandar no WhatsApp: reputação, problemas em linguagem leiga, raio-X e **nota oficial do Google PageSpeed** |
| 📸 **Canal Instagram** | Extrai comentários de um post, enriquece o perfil de cada autor e classifica prioridade com IA, com retomada de análises interrompidas |
| 🧠 **Mensagens com IA** | Copy de abordagem e follow-up **na sua voz** (perfil do vendedor), citando detalhes reais do site, com fallback entre 3 provedores gratuitos (Gemini, Groq, NVIDIA) |
| 🎯 **Estratégia por lead** | Cada lead vem com cenário detectado, ângulo de venda, ganchos concretos e objeções com respostas prontas |
| 🔥 **Score de priorização** | Nota + volume de avaliações + situação do site num score 0-100 para ordenar a fila de abordagem |
| ⚡ **Sessão de prospecção** | Modo foco: um lead por vez do mais quente ao mais frio (follow-ups primeiro), abordagem em um clique com atalhos de teclado |
| 📋 **Tarefas de hoje** | Follow-ups vencidos + leads quentes, cada um com o WhatsApp já preenchido |
| 📊 **CRM visual + Kanban** | Funil de status com histórico, drag-and-drop, tags, observações e follow-up com cadência crescente (+3/+5/+7 dias) |
| 📈 **Analytics** | Funil de conversão e desempenho por nicho, para os dois canais separados e combinados |
| 🧰 **Produtividade** | Filtros (inclusive por situação do site), histórico de buscas, busca global (Ctrl+K), exportação CSV, ações em lote, tema claro/escuro |
| 🔐 **Segurança** | Chaves de API guardadas no cofre de credenciais do sistema (Windows/DPAPI), nunca em texto puro |
---
## 🚀 Quickstart
### Pré-requisitos
- [Python 3.11+](https://www.python.org/downloads/)
- [Node.js 20+](https://nodejs.org/)
- Windows (scripts `.bat` e o scraper de Maps são específicos da plataforma)
### 1. Clone o repositório
```powershell
git clone https://github.com/nando0x/ProspectOS.git
cd ProspectOS
```
### 2. Configure o backend
```powershell
cd backend
py -m pip install -r requirements.txt
copy .env.example .env
```
Você vai precisar de **ao menos uma** chave de IA gratuita (usada para gerar as mensagens de abordagem e classificar leads do Instagram):
| Provedor | Onde pegar a chave |
|---|---|
| Gemini | https://aistudio.google.com/apikey |
| Groq | https://console.groq.com/keys |
| NVIDIA Build | https://build.nvidia.com |
Tem duas formas de configurar, escolha a que for mais fácil pra você:
- **Pela interface do sistema (mais fácil):** depois de rodar o projeto (veja o passo 6), acesse **Configurações** no menu e cole a chave direto lá. Fica guardada com segurança no cofre de credenciais do sistema (nunca em texto puro), sem precisar mexer em nenhum arquivo nem reiniciar o servidor.
- **Editando o `.env` manualmente:** abra o arquivo `backend/.env` num editor de texto e preencha o valor da chave correspondente (`GEMINI_API_KEY`, `GROQ_API_KEY` ou `NVIDIA_API_KEY`).
> Se você configurar dos dois jeitos, o que estiver salvo pela interface tem prioridade sobre o `.env`.
> 💡 **Opcional — Google PageSpeed:** para incluir a nota oficial de desempenho do Google no diagnóstico em PDF, adicione uma chave do [PageSpeed Insights](https://developers.google.com/speed/docs/insights/v5/get-started) em Configurações. É gratuita e funciona sem chave para uso leve.
> 💡 **Recomendado — Seu perfil:** ainda em Configurações, preencha "Seu perfil" (nome e o que você faz). As mensagens geradas por IA saem assinadas e na sua voz, em vez de genéricas.
### 3. Baixe a dependência externa do scraper
O `google-maps-scraper.exe` **não vem no repositório** (é um binário de terceiros, ~60MB, de outro projeto open source, então não faz sentido versionar binário compilado dentro de um repo git). Passo a passo completo, sem pular nada:
1. Acesse **[a página de releases mais recente](https://github.com/gosom/google-maps-scraper/releases/latest)**.
2. Role até a seção **"Assets"** (fica perto do final da página, às vezes precisa clicar para expandir).
3. Procure o arquivo para **Windows**. O nome muda a cada versão nova, mas segue sempre o padrão `google_maps_scraper-