Como funciona o crawler de imóveis

Resumo executivo

Fluxo completo atual

O scheduler Laravel dispara o comando; por padrão chama o runner HTTP do container crawler. O runner inicia o CLI em uma thread quando assíncrono e devolve 202 Accepted. Cada scraper coleta e envia cada imóvel individualmente; o backend grava properties, imagens e endereço.

Quando roda

• Fuso: America/Sao_Paulo.
• withoutOverlapping(180) impede execução conflitante; onOneServer() coordena uma instância.
• O serviço Docker scheduler precisa estar ativo com php artisan schedule:work.
• O prune usa CRAWLER_STALE_DAYS, padrão 7, e não apaga registros.

Fonte: routes/console.php:L25-L65 · config/crawler.php:L15-L43

O que cada scraper faz

discover coleta o catálogo e chama sync_property() por imóvel. update consulta GET /api/v1/crawler/properties paginado (até 100 por página), filtrando ativos e imobiliária, e só então re-coleta os registrados.

registry · BaseScraper · cliente/paginação

Chaves, autenticação e payload

Formato enviado por imóvel

{
  "external_id": "ID da imobiliária", "external_url": "https://...",
  "real_estate_company_name": "Nome", "description": "...", "price": 0,
  "property_type": "apartment", "business_type": "sell",
  "latitude": -23.0, "longitude": -46.0,
  "count_suites": 1, "count_rooms": 2, "count_bedrooms": 2,
  "count_bathrooms": 2, "count_kitchens": 1, "count_parking_spaces": 1,
  "images": ["https://..."],
  "address": {"state":"SP","city":"...","neighborhood":"...","street":"...",
              "number":10,"address":"...","complement":"..."}
}

A validação exige ID, URL, imobiliária, tipo de propriedade, tipo de negócio e estado/cidade/bairro. Preço, coordenadas, contagens, imagens e detalhes de endereço podem ser nulos; imagens precisam ser URLs.

validação · serialização · token

O que acontece com cada imóvel

1. Resolve estado por nome/sigla; cidade por nome ou correspondência textual próxima; bairro com a mesma lógica.
2. Resolve a imobiliária por mapas de nomes/chaves, por exemplo carol-gianazi → Gianazi, luzia → Lúzia Imóveis, village → Village.
3. Identifica por real_estate_company_id + external_id via updateOrCreate; novo recebe ID, existente é atualizado.
4. Monta slug com tipo, bairro, cidade, imobiliária e ID externo; garante unicidade com -1, -2 etc.
5. Cada sync força active=true e last_synced_at=now(); preço, descrição, tipo, negócio, coordenadas e contagens vêm do payload.
6. Imagens externas entram com firstOrCreate; endereço é atualizado na relação.
7. Às 06:00, externo ativo com last_synced_at nulo ou anterior ao limite vira active=false; não é deletado.

upsert · prune · comando

Como a execução é disparada

O container crawler usa restart: unless-stopped, monta backend/crawler:/app e Chromium em /usr/bin/chromium. O scheduler usa php artisan schedule:work. Em produção, limites declarados: crawler 1 CPU/1536 MB; scheduler 0,20 CPU/256 MB.

comando Laravel · runner · Docker

Double check: Meilisearch e indexação

Pontos de atenção encontrados

1. Endereço/imagens não reindexam o imóvel sozinhos: no crawler, Property::updateOrCreate() acontece antes de PropertyAddress::updateOrCreate() e das imagens. Como PropertyAddress e PropertyImage não usam Searchable, uma mudança apenas no endereço pode não atualizar o documento do Meili.
2. Prune em massa não dispara evento do modelo: ->update(['active' => false]) é update de query. O campo active nem está no documento indexado, então a busca continua correta porque o MySQL filtra ativos, mas ficam documentos inativos no índice.
3. Configuração do índice é genérica: searchableAttributes=['*'], sem filterableAttributes e sortableAttributes. Isso é coerente com a implementação atual, mas impede aproveitar filtros/sort diretamente no Meili.
4. Dados atuais não estão recentes no ambiente local: o índice e o banco têm atualização máxima em 2026-07-09. Isso prova consistência de contagem, não atualização contínua; os containers crawler e scheduler não estavam em execução neste compose local.

Property/Searchable · config Scout · config produção · ordem do upsert do crawler

Standalone e fluxo legado

crawler-imoveis/ contém notebooks Jupyter, modelos e cliente de API. O código integrado em imovel-central-docker/backend/crawler/ é a versão operacional do Docker; o standalone é execução manual/experimental.

• Notebooks: village.ipynb, fadel.ipynb, carolgianazi.ipynb, luziaimoveis.ipynb, silvanalopesimobiliaria.ipynb.
• Recomendado no README: cada imóvel é enviado imediatamente por api_client.sync_property().
• Legado: storage.ipynb cria properties.json e envia arquivo para POST /api/v1/crawler/sync/properties.
• O lote salva arquivo, dispara ProcessCrawlerDataJob, divide em chunks de 200, despacha ProcessCrawlerChunkJob e apaga o arquivo; erros são registrados.
• O compose standalone expõe Jupyter em 8888 com token crawler123, diferente do runner operacional em 8080.

README · compose · job de lote

Operação e diagnóstico

# listar chaves
docker compose exec backend php artisan crawler:run --list

# descoberta manual
php artisan crawler:run --company=village --mode=discover

# atualizar cadastrados
php artisan crawler:run --company=fadel --mode=update

# aguardar término
php artisan crawler:run --company=luzia --mode=discover --sync

# simular prune
php artisan crawler:prune-stale --dry-run

# logs
docker compose logs -f crawler scheduler

Token vazio → 503; token incorreto → 401. Imobiliária/endereço não resolvido → falha de validação. Item sem ID/URL → skipped.

Fontes consultadas