LeadScraper — Leia-me

Motor de busca e prospecção de leads via automação de navegador (Google Maps), com backend em Java, frontend próprio, banco de dados PostgreSQL e execução em Docker.

Este documento é o ponto de entrada do projeto. Leia-o antes de começar qualquer etapa.

1. Estrutura do projeto

leadscraper/
├── LEIA-ME.md                  ← este arquivo
├── ARQUITETURA-SCHEMA.md       ← schema completo do banco + stack tecnológica + módulos
├── PROGRESSO.md                ← tracker de progresso, atualizado a cada etapa concluída
└── etapas/
    ├── 01-setup-projeto-docker-flyway.md
    ├── 02-modelagem-entidades-jpa.md
    ├── 03-motor-scraper-playwright.md
    ├── 04-normalizador-padronizacao.md
    ├── 05-pool-proxies-anti-bloqueio.md
    ├── 06-api-rest-backend.md
    ├── 07-frontend-setup-dashboard.md
    ├── 08-frontend-integracao-api.md
    ├── 09-docker-compose-deploy.md
    └── 10-testes-validacao-final.md

2. Como este projeto deve ser executado

Leia ARQUITETURA-SCHEMA.md por completo antes de iniciar qualquer etapa — ele é a fonte de verdade sobre schema de banco, tecnologias e módulos. Nenhuma etapa deve divergir do que está lá sem atualizar o documento primeiro.
Siga as etapas em etapas/ na ordem numérica. Cada arquivo é autocontido: traz objetivo, contexto necessário e critérios de aceite. Não pule etapas — cada uma assume que a anterior foi concluída.
Antes de iniciar uma etapa, abra PROGRESSO.md e confira se a etapa anterior está marcada como concluída. Se não estiver, resolva pendências antes de avançar.
Ao concluir uma etapa, atualize PROGRESSO.md imediatamente — marque status, data e qualquer observação relevante (ex: decisão técnica tomada, desvio do plano original).
Se durante a execução de uma etapa for necessário mudar algo do schema ou da arquitetura definida em ARQUITETURA-SCHEMA.md, atualize o documento primeiro (versionando, ex: v1.0 → v1.1) e só depois prossiga — nunca deixe o código divergir silenciosamente do documento de arquitetura.
Novas funcionalidades que surgirem depois do projeto em produção (ex: exportação avançada, novo canal de contato) devem virar novos arquivos de etapa numerados (11, 12...) ou migrations incrementais — nunca reescrever o schema base do zero.

3. Pré-requisitos de ambiente

Java 21 (JDK)
Docker + Docker Compose
Node.js 20+ (apenas para build do frontend)
Maven (ou o wrapper mvnw incluso no projeto backend)

4. Visão geral rápida do sistema

Backend (Java/Spring Boot): expõe API REST, roda o motor de scraping (Playwright), aplica as regras de padronização e persiste os leads.
Frontend (React/Vite): dashboard para disparar novas buscas, acompanhar status, listar/filtrar/exportar leads.
Banco (PostgreSQL): armazena leads, ramos, buscas, proxies e histórico de contato.
Docker Compose: orquestra os três serviços acima para subir o ambiente completo com um único comando.

Detalhes completos de cada peça estão em ARQUITETURA-SCHEMA.md.

5. Subida completa com Docker Compose

Crie um .env a partir do exemplo:

cp .env.example .env

Edite o .env antes de usar em produção:

DB_PASSWORD: use uma senha forte.
JWT_SECRET: use uma chave longa, com pelo menos 32 caracteres.
API_URL: mantenha /api quando o frontend Nginx fizer proxy para o backend no mesmo compose. Para publicar backend e frontend em domínios separados, use a URL pública do backend, por exemplo https://api.seudominio.com.
FRONTEND_PORT, BACKEND_PORT, SERVER_PORT e DB_PORT: ajuste se as portas 8081, 8082 ou 5433 já estiverem ocupadas.
BUSCA_WORKER_ENABLED: use false se quiser subir o ambiente sem processar buscas automaticamente.

Suba o ambiente completo:

docker compose up --build

O Compose sobe PostgreSQL, backend e frontend. O backend espera o healthcheck do banco, aplica as migrations do Flyway no startup e expõe a API em http://localhost:8082 por padrão. O frontend fica em http://localhost:8081 por padrão e encaminha chamadas /api/* para o backend interno.

Se você alterar DB_PASSWORD depois que o volume postgres_data já foi criado, o Postgres continuará usando a senha definida na primeira inicialização. Para trocar a senha em ambiente local descartável, recrie o volume; em produção, faça a rotação de senha pelo próprio banco antes de atualizar o .env.

6. Deploy em produção

O deploy oficial usa escavador.seconectai.com.br, Caddy para HTTPS automático e docker-compose.prod.yml.

Para instalar os comandos globais no servidor:

curl -fsSL https://producao-gitea.0jo7zj.easypanel.host/tiago/Prospeccao_SeConectai/raw/branch/main/scripts/bootstrap-commands.sh | sudo bash

Primeira instalação:

seconectaiescavador.install

Atualização depois de novos commits:

seconectaiescavador.update

Veja detalhes em DEPLOY.md.

Credenciais iniciais de desenvolvimento:

Email: tiago27.dossantos@gmail.com
Senha: 10031992

7. Ordem de leitura recomendada para quem for executar

LEIA-ME.md (este arquivo)
ARQUITETURA-SCHEMA.md
PROGRESSO.md (ver o que já foi feito, se houver histórico)
etapas/01-...md em diante, sequencialmente

5.4 KiB Raw Permalink Blame History