Pedro/improments (#161)

## Resumo

Este PR melhora a experiência de navegação e filtragem das vagas,
tornando a página mais intuitiva, consistente e mais fácil de
compartilhar. Também inclui ajustes para manter o estado da interface
sincronizado com a URL e reforçar a cobertura de testes.

## O que foi alterado

- Melhoria no componente de filtros das vagas para oferecer uma
experiência de busca mais clara e amigável.
- Ajuste na forma como termos de busca e filtros são aplicados,
facilitando a combinação de critérios e a refinagem dos resultados.
- Sincronização do estado de filtros, arquivo selecionado e paginação
com os parâmetros da URL, permitindo compartilhar e restaurar a
visualização mais facilmente.
- Refinamento da tabela de vagas para refletir melhor os filtros ativos,
a página atual e o tamanho da paginação.
- Atualização e expansão dos testes unitários relacionados a filtros,
paginação e renderização da página de vagas.
- Inclusão/atualização de documentação relevante para refletir as
mudanças na experiência e no fluxo de uso da funcionalidade.

## Por que isso é importante

Essas alterações tornam a busca por vagas mais previsível, mais fácil de
usar e mais preparada para cenários com muitos resultados ou vários
filtros aplicados ao mesmo tempo.

## Pontos para revisão

- Comportamento entre o estado da interface e os parâmetros da URL.
- Lógica de filtros ao combinar busca, palavras-chave e seleção de
arquivo.
- Comportamento de paginação e tamanho de página em diferentes cenários.

## Testes

Foram atualizados os testes unitários da interface para cobrir os fluxos
principais de filtragem, paginação e renderização da página.

<img width="1753" height="960" alt="image"
src="https://github.com/user-attachments/assets/cabeaa22-ffa9-4063-a251-95bedb178de1"
/>

Author: hltav

.env.example

@@ -0,0 +1,65 @@
+# Runtime
+NODE_ENV=development
+PORT=3001
+
+# Base URLs
+APP_URL=http://localhost:3001
+FRONTEND_URL=http://localhost:5173
+GO_SCRAPER_URL=http://localhost:8081
+
+# Session
+# Use uma string longa e secreta em ambientes reais.
+SESSION_SECRET=change-me-with-a-long-random-secret
+
+# CORS / frontend access
+CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:5174
+
+# Search filters
+SEARCH_LOCATION=Brasil
+SEARCH_GEO_ID=106057199
+SEARCH_LANGUAGE=pt
+REMOTE_ONLY=true
+JOB_TYPES=C,F
+TIME_FILTER=r604800
+SEARCH_KEYWORDS=UX Designer,UI Designer,Product Manager,Product Owner
+
+# Scraping behavior
+WAIT_BETWEEN_SEARCHES_MS=5000
+PAGE_TIMEOUT_MS=10000
+MAX_PAGES_PER_KEYWORD=5
+
+# Database / cache
+POSTGRES_USER=vagas
+POSTGRES_PASSWORD=vagas
+POSTGRES_DB=vagas
+
+# Use esta URL quando backend/scraper estiverem rodando fora do Docker e o banco estiver exposto no host.
+DATABASE_URL=postgresql://vagas:vagas@localhost:5432/vagas
+VALKEY_URL=redis://localhost:6379/0
+
+# Use estas URLs dentro de containers Docker Compose.
+# DATABASE_URL=postgresql://vagas:vagas@postgres:5432/vagas
+# VALKEY_URL=redis://valkey:6379/0
+
+CACHE_TTL_MS=600000
+REDIS_KEY_PREFIX=vagas-full
+KEYWORDS_REDIS_KEY=vagas-full:keywords
+KEYWORDS_STORAGE_MODE=env
+
+# Legacy flags kept for compatibility
+HEADLESS=false
+VIEWPORT_WIDTH=1280
+VIEWPORT_HEIGHT=800
+
+# Third-party API credentials
+ADZUNA_APP_ID=
+ADZUNA_APP_KEY=
+JOOBLE_API_KEY=
+
+# OAuth credentials
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+LINKEDIN_CLIENT_ID=
+LINKEDIN_CLIENT_SECRET=
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=

.gitignore

@@ -4,6 +4,7 @@ node_modules/
 .env.*
 !.env.example
 .vscode/
+.docker-local/
 dist/
 build/
 output/

README.md

@@ -74,15 +74,88 @@ Objetivo de produto: fornecer uma base robusta para busca, filtragem e gestão d
 
 - Node.js >= 22
 - npm
-- Docker e Docker Compose (opcional, recomendado para ambiente completo)
+- Docker Desktop com Docker Compose
 
-### Instalação
+### Caminho recomendado: stack completa com Docker
+
+Use este fluxo para subir Postgres, Valkey, scraper Go, backend e frontend com a mesma rede Docker.
+
+1. Instale as dependências locais:
+
+```bash
+npm ci
+```
+
+2. Crie o `.env` da raiz a partir do exemplo versionado:
+
+```bash
+cp .env.example .env
+```
+
+No Windows PowerShell:
+
+```powershell
+Copy-Item .env.example .env
+```
+
+3. Crie a rede Docker compartilhada, se ela ainda não existir:
+
+```bash
+docker network create vagas-net
+```
+
+Se a rede já existir, o Docker vai avisar e você pode seguir para o próximo passo.
+
+4. Suba Postgres e Valkey:
+
+```bash
+docker compose -f docker-compose.infra.yml up -d
+```
+
+5. Suba scraper, backend e frontend:
+
+```bash
+docker compose up --build -d
+```
+
+6. Aplique as migrations do backend:
 
 ```bash
-npm install
+docker compose exec backend npm run db:migrate
 ```
 
-### Execução web (frontend + backend)
+7. Acesse os serviços:
+
+- Frontend: http://localhost:5173
+- Backend health: http://localhost:3001/health
+- Scraper health: http://localhost:8081/health
+- Vagas salvas no scraper: http://localhost:8081/admin/jobs/count
+
+### Desenvolvimento com Node local
+
+Use este fluxo quando quiser rodar frontend/backend fora do Docker. Mantenha Postgres e Valkey ativos no Docker e configure URLs locais nos arquivos `.env`.
+
+Arquivos esperados:
+
+- `.env`: usado pela infra/scraper e por comandos auxiliares.
+- `backend/.env`: usado pelo backend local.
+- `frontend/.env`: usado pelo Vite local.
+
+Criação dos arquivos locais:
+
+```bash
+cp backend/.env.example backend/.env
+cp frontend/.env.example frontend/.env
+```
+
+No Windows PowerShell:
+
+```powershell
+Copy-Item backend/.env.example backend/.env
+Copy-Item frontend/.env.example frontend/.env
+```
+
+Comandos:
 
 ```bash
 npm run dev
@@ -174,6 +247,8 @@ Usuários:
 
 Jobs:
 
+- GET /jobs
+- GET /jobs/files
 - GET /jobs/search
 
 Keywords:
@@ -195,47 +270,67 @@ Swagger:
 
 ## Docker (infra + aplicação)
 
-Este projeto separa infraestrutura de aplicação em dois arquivos compose.
+Este projeto separa infraestrutura e aplicação em dois arquivos Compose:
 
-1. Criar rede compartilhada (necessário uma vez):
+- `docker-compose.infra.yml`: Postgres + Valkey.
+- `docker-compose.yml`: scraper Go + backend + frontend.
+
+Subir infraestrutura:
 
 ```bash
-docker network create vagas-net
+docker compose -f docker-compose.infra.yml up -d
 ```
 
-2. Subir infra (Postgres + Valkey):
+Subir aplicação:
 
 ```bash
-docker compose -f docker-compose.infra.yml up -d
+docker compose up --build -d
 ```
 
-3. Subir aplicação (scraper-go + backend + frontend):
+Aplicar migrations:
 
 ```bash
-docker compose up --build -d
+docker compose exec backend npm run db:migrate
 ```
 
-4. Logs:
+Ver logs:
 
 ```bash
 docker compose logs -f backend
 docker compose logs -f frontend
 docker compose logs -f scraper-go
 ```
 
-5. Encerrar:
+Encerrar:
 
 ```bash
 docker compose down
 docker compose -f docker-compose.infra.yml down
 ```
 
+Observação: os volumes Docker preservam os dados do Postgres e do Valkey entre execuções. Se você alterar `POSTGRES_USER`, `POSTGRES_PASSWORD` ou `POSTGRES_DB` depois da primeira inicialização, será necessário recriar o volume do Postgres ou manter os valores antigos.
+
+Dentro dos containers, serviços devem usar os nomes da rede Docker:
+
+- Postgres: `postgres:5432`
+- Valkey: `valkey:6379`
+- Scraper: `scraper-go:8081`
+
+Por isso o `docker-compose.yml` sobrescreve `DATABASE_URL`, `VALKEY_URL`, `GO_SCRAPER_URL` e `SCRAPER_URL` para os valores internos corretos.
+
 Serviços padrão:
 
 - Frontend: http://localhost:5173
 - Backend: http://localhost:3001
 - Scraper Go: http://localhost:8081
 
+Endpoints úteis do scraper:
+
+- Health: http://localhost:8081/health
+- Status da execução: http://localhost:8081/admin/scrape/status
+- Contagem de vagas salvas: http://localhost:8081/admin/jobs/count
+- Lista de vagas salvas: http://localhost:8081/admin/jobs
+
 ## Desktop com Electron
 
 O app desktop empacota frontend + backend e inicia a aplicação com Electron.
@@ -259,13 +354,23 @@ Saída esperada do instalador:
 
 ## Variáveis de ambiente
 
-Arquivo base:
+Arquivos de exemplo:
 
+- .env.example
 - backend/.env.example
+- frontend/.env.example
 
-Arquivo local:
+Arquivos locais ignorados pelo Git:
 
+- .env
 - backend/.env
+- frontend/.env
+
+Uso recomendado:
+
+- Docker Compose: copie `.env.example` para `.env`. O Compose usa esse arquivo para infra, scraper, backend e build do frontend.
+- Backend local via Node: use `backend/.env`.
+- Frontend local via Vite: use `frontend/.env`.
 
 Variáveis centrais de operação:
 

SCRAPER.md

@@ -122,15 +122,19 @@ cd scraper-go
 go run ./cmd/server
 ```
 
-Docker: há um `Dockerfile` em `scraper-go/`.
+Docker: há um `Dockerfile` em `scraper-go/`. No Docker Compose, configure `VALKEY_URL=redis://valkey:6379/0` no `.env` da raiz para que o scraper acesse o Valkey pelo nome do serviço na rede Docker.
 
 ## Endpoints HTTP
 
 O serviço expõe endpoints HTTP (implementação em `cmd/server` e arquivos associados). Principais rotas:
 
 - POST `/scrape` — body JSON com `ScrapeRequest` para disparar uma busca em todas as fontes configuradas. Retorna `ScrapeResponse` com `jobs`, `total`, `cachedAt` e `fromCache`.
+- GET `/health` — verifica se o scraper está online e qual cache está em uso.
 - GET `/api/keywords` — retorna as keywords atualmente carregadas.
 - POST `/api/keywords` — atualiza/persiste as keywords (aceita `keywords: string[]`).
+- GET `/admin/scrape/status` — informa se existe uma execução em andamento.
+- GET `/admin/jobs/count` — retorna a quantidade de vagas persistidas no Valkey.
+- GET `/admin/jobs` — lista as vagas persistidas no Valkey.
 
 Exemplo de `ScrapeRequest` (JSON):
 
@@ -230,7 +234,7 @@ Boas práticas nos adaptadores:
 
 ## Variáveis de ambiente importantes
 
-- `REDIS_URL` / `VALKEY_URL` — conexão Redis/Valkey.
+- `VALKEY_URL` — conexão Redis/Valkey. Em Docker Compose, use `redis://valkey:6379/0`; em execução local fora do Docker, use uma URL acessível pelo host, por exemplo `redis://localhost:6379/0`.
 - `JOOBLE_API_KEY` — Jooble integration.
 - `ADZUNA_APP_ID` / `ADZUNA_APP_KEY` — Adzuna API.
 - Configurações de logging e quota podem ser definidas via `.env`.

backend/.env.example

@@ -1,44 +1,30 @@
 # Runtime
-# Runtime
-NODE_ENV=production
+NODE_ENV=development
 PORT=3001
 
-# Base URL da aplicação
-# Ex: APP_URL=http://localhost:3001/api
-APP_URL=
-
-# Sessão
-# Use uma string longa e secreta em produção
-SESSION_SECRET=
+# Base URLs
+APP_URL=http://localhost:3001
+FRONTEND_URL=http://localhost:5173
 
-# CORS / frontend access (separar por vírgula)
-CORS_ALLOWED_ORIGINS=
+# Session
+# Use uma string longa e secreta em ambientes reais.
+SESSION_SECRET=change-me-with-a-long-random-secret
 
-# URL do frontend (usada para redirect pos-OAuth)
-FRONTEND_URL=http://localhost:5173
+# CORS / frontend access
+CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:5174
 
-# LinkedIn search filters (defaults)
+# Search filters
 SEARCH_LOCATION=Brasil
 SEARCH_GEO_ID=106057199
 SEARCH_LANGUAGE=pt
 REMOTE_ONLY=true
 JOB_TYPES=C,F
 TIME_FILTER=r604800
+SEARCH_KEYWORDS=UX Designer,UI Designer,Product Manager,Product Owner
 
-# Keywords (opcional: fallback inicial)
-# SEARCH_KEYWORDS=UX Designer,UI Designer,Product Manager,Product Owner
-SEARCH_KEYWORDS=
-
-# Storage / Cache
-# DATABASE_URL template (substitua USER/PASS/HOST/PORT/DB)
-# DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@host:5432/${POSTGRES_DB}
-DATABASE_URL=
-
-# VALKEY/Redis URL
-VALKEY_URL=
-# Exemplo: redis://:password@localhost:6379/0
-
-# Cache TTL (ms)
+# Database / cache for backend running locally outside Docker
+DATABASE_URL=postgresql://vagas:vagas@localhost:5432/vagas
+VALKEY_URL=redis://localhost:6379/0
 CACHE_TTL_MS=600000
 
 # Scraping behavior
@@ -51,22 +37,20 @@ HEADLESS=false
 VIEWPORT_WIDTH=1280
 VIEWPORT_HEIGHT=800
 
-# Third-party API credentials (NUNCA commit valores reais)
+# Third-party API credentials
 ADZUNA_APP_ID=
 ADZUNA_APP_KEY=
+JOOBLE_API_KEY=
 
+# OAuth credentials
 GOOGLE_CLIENT_ID=
 GOOGLE_CLIENT_SECRET=
-
 LINKEDIN_CLIENT_ID=
 LINKEDIN_CLIENT_SECRET=
-
 GITHUB_CLIENT_ID=
 GITHUB_CLIENT_SECRET=
 
-# Scraper Go service URL
+# Local scraper services
 GO_SCRAPER_URL=http://localhost:8081
-
-
-SCRAPER_URL=http://scraper-go:8081
-PROMETHEUS_URL=http://prometheus:9090
+SCRAPER_URL=http://localhost:8081
+PROMETHEUS_URL=http://localhost:9090