# 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

1. **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.
2. **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.
3. **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.
4. **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).
5. 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.
6. 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

1. Crie um `.env` a partir do exemplo:

```bash
cp .env.example .env
```

2. 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.

3. Suba o ambiente completo:

```bash
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:

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

Primeira instalação:

```bash
seconectaiescavador.install
```

Atualização depois de novos commits:

```bash
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

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