Initial commit

Schema/LEIA-ME.md

@@ -0,0 +1,114 @@
+# 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