sass-imobiliaria/specs/024-filtro-busca-avancada/quickstart.md

Quickstart: Filtro de Busca Avançada — FilterSidebar

Feature: 024-filtro-busca-avancada | Date: 2026-04-20

Guia de verificação rápida após implementação. Execute em ordem.

---

Pré-requisitos

# Containers rodando
docker compose up -d

# Backend saudável
curl http://localhost:5000/api/v1/cities

---

1. Verificar property_count no backend

Cidades

curl -s http://localhost:5000/api/v1/cities | python -m json.tool | grep property_count

Esperado: cada objeto de cidade tem "property_count": <número inteiro ≥ 0>.

Bairros

curl -s "http://localhost:5000/api/v1/neighborhoods?city_id=1" | python -m json.tool | grep property_count

Esperado: campo presente, valores numéricos, bairros sem imóvel retornam 0.

Tipos de imóvel

curl -s http://localhost:5000/api/v1/property-types | python -m json.tool

Esperado:

• subtypes[*].property_count presente e ≥ 0
• Tipos pai (parent_id: null) têm property_count: 0

NFR-005 — apenas imóveis ativos

# Desativar um imóvel e verificar que property_count decresce
docker exec saas_imobiliaria-backend-1 uv run python -c "
from app import create_app; from app.extensions import db; from app.models.property import Property
app = create_app()
with app.app_context():
    p = Property.query.filter_by(is_active=True).first()
    if p:
        print('Imóvel:', p.city_id, p.neighborhood_id)
"

---

2. Verificar estado inicial das seções (User Story 2)

1. Acessar http://localhost:5173/imoveis sem parâmetros de URL
2. Verificar que apenas a seção "Preço" está expandida ao carregar
3. Verificar que "Localização", "Tipo de imóvel", "Quartos e vagas", "Área", "Comodidades" estão colapsadas

✅ Apenas "Preço" expandida → FR-009 PASS

4. Acessar http://localhost:5173/imoveis?city_id=1&bedrooms_min=2
5. Verificar que as seções "Localização" e "Quartos e vagas" estão expandidas além de "Preço"

✅ Seções com filtros ativos expandidas → FR-010 PASS

---

3. Verificar truncamento e popularidade (User Story 3)

1. Abrir a seção "Localização" → subseção Bairros (com cidade selecionada que tenha > 5 bairros)
2. Verificar que apenas 5 bairros são exibidos inicialmente
3. Verificar que os 3 primeiros têm badge "Popular" visível
4. Verificar que os 5 exibidos são os mais populares (maiores property_count)
5. Clicar em "Ver mais (N)" → todos os bairros são exibidos
6. Clicar em "Ver menos" → volta aos 5 primeiros

✅ Truncamento top-5 → FR-012 PASS
✅ Ordenação por popularidade → FR-013 PASS
✅ Badge "Popular" → FR-014 PASS
✅ "Ver mais" toggle → FR-017 PASS

7. Selecionar um bairro que não está entre os 5 primeiros
8. Colapsar e reabrir a seção
9. Verificar que o bairro selecionado aparece visível mesmo sem clicar em "Ver mais"

✅ Item selecionado sempre visível → FR-015 PASS

---

4. Verificar busca cross-categoria (User Story 1)

1. Verificar que o campo "Buscar filtro…" aparece acima de todas as seções accordion
2. Digitar "apar" e aguardar 200 ms
3. Verificar sugestão inline com grupo "Tipo de imóvel" → "Apartamento"
4. Clicar em "Apartamento" → filtro subtype_id aplicado, campo limpo, seção "Tipo de imóvel" expandida

✅ FR-001, FR-002, FR-003, FR-004, FR-006 PASS

5. Digitar "copa" → verificar "Copacabana" sob grupo "Bairro"
6. Digitar "apto xyz 999" → verificar mensagem "Nenhum filtro encontrado para "apto xyz 999""

✅ FR-005 (normalização), FR-005 (case-insensitive) PASS

7. Com sugestões visíveis:
   • Pressionar ↓ → primeiro item highlighted
   • Pressionar ↓ novamente → segundo item
   • Pressionar Enter → filtro aplicado
   • Abrir novamente, pressionar Escape → sugestões fechadas

✅ FR-008 (navegação por teclado) PASS

8. Testar com catalogLoading = true (simular estado de carregamento):
   • Campo deve aparecer desabilitado (opacidade reduzida, cursor not-allowed)

✅ FR-007 PASS

---

5. Verificar design tokens (NFR-003)

Inspecionar no DevTools:

Elemento	Token esperado	Classe Tailwind
Campo de busca (borda)	borderSubtle	border-borderSubtle
Campo de busca (texto placeholder)	textTertiary	placeholder-textTertiary
Badge "Popular" (fundo)	brand/20	bg-brand/20
Badge "Popular" (texto)	brand	text-brand
Botão "Ver mais"	textTertiary	text-textTertiary
Cabeçalhos de grupos de sugestão	textTertiary uppercase	text-textTertiary uppercase
Animação sugestões	duration-200 ease-out	CSS grid trick

---

6. Verificar que filtros existentes não quebraram (NFR-004 / SC-005)

cd backend && uv run pytest tests/ -v

Esperado: todos os testes passando.

Testar manualmente na UI:

• Filtro por preço (min/max + presets)
• Filtro por quartos/banheiros/vagas (chips)
• Filtro por área
• Filtro por comodidades (checkboxes)
• Botão "Limpar (N)"
• Toggle Venda / Aluguel

✅ Nenhum filtro existente quebrado → NFR-004, SC-005 PASS