# 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

```powershell
# Containers rodando
docker compose up -d

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

---

## 1. Verificar `property_count` no backend

### Cidades

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

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

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

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

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