feat: add full project - backend, frontend, docker, specs and configs

2026-04-20 23:59:45 -03:00 · 2026-04-20 23:59:45 -03:00 · e6cb06255b
commit e6cb06255b
parent b77c7d5a01
24489 changed files with 61341 additions and 36 deletions
--- a/specs/024-filtro-busca-avancada/quickstart.md
+++ b/specs/024-filtro-busca-avancada/quickstart.md
@ -0,0 +1,181 @@
+# 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
+```