181 lines
5.2 KiB
Markdown
181 lines
5.2 KiB
Markdown
# 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
|
|
```
|