sass-imobiliaria/specs/023-ux-melhorias-imoveis/quickstart.md

Quickstart — 023-ux-melhorias-imoveis

Guia de desenvolvimento local para implementar as melhorias de UX/UI na página /imoveis.

---

Pré-requisitos

• Docker + Docker Compose em execução
• Branch: 023-ux-melhorias-imoveis (ou trabalhar direto em master)

# Verificar que os containers estão rodando
docker-compose ps
# Backend: http://localhost:5000
# Frontend: http://localhost:5174

---

Sprint 1 — Ordem de Trabalho Recomendada

1. Backend: parâmetro q

# Editar a rota
code backend/app/routes/properties.py

# Após editar, reiniciar o backend
docker-compose restart backend

# Testar manualmente
curl "http://localhost:5000/api/v1/properties?q=jardins" | python -m json.tool | head -30
curl "http://localhost:5000/api/v1/properties?q=AP-0042" | python -m json.tool | head -10
curl "http://localhost:5000/api/v1/properties?q=Rua+das+Flores&sort=price_asc" | python -m json.tool

2. Frontend: refactor PropertyRowCard

O frontend tem hot reload — editar e salvar recarrega automaticamente em http://localhost:5174/imoveis.

# Verificar TypeScript após edições
docker-compose exec frontend npx tsc --noEmit

Cheklist de validação do refactor semântico:

• Abrir DevTools → Elements → procurar <a> → confirmar que não há <button> filho
• Clicar no card (área de texto) → navega para detalhes
• Clicar em "Entre em contato" → abre modal (não navega)
• Clicar em "Comparar" → adiciona à barra de comparação
• Tab pelo teclado: foca em "Ver detalhes" → "Entre em contato" → "Comparar" independentemente

3. Frontend: SearchBar + integração

# Criar o novo componente
code frontend/src/components/SearchBar.tsx

# Verificar que q aparece na URL ao digitar
# http://localhost:5174/imoveis → digitar no campo → URL deve mudar para ?q=termo

---

Sprint 2 — Ordem de Trabalho Recomendada

1. Backend: parâmetro sort

docker-compose restart backend

# Testar ordenação
curl "http://localhost:5000/api/v1/properties?sort=price_asc&per_page=5" | \
  python -c "import sys,json; d=json.load(sys.stdin); [print(i['price']) for i in d['items']]"

curl "http://localhost:5000/api/v1/properties?sort=price_desc&per_page=5" | \
  python -c "import sys,json; d=json.load(sys.stdin); [print(i['price']) for i in d['items']]"

2. Frontend: PropertyGridCard

code frontend/src/components/PropertyGridCard.tsx
# Testar em http://localhost:5174/imoveis — ativar toggle de Grade

3. Frontend: ActiveFiltersBar

code frontend/src/components/ActiveFiltersBar.tsx
# Testar: aplicar filtro cidade → chip aparece → clicar × → filtro removido

---

Sprint 3 — Ordem de Trabalho Recomendada

# Animações: adicionar keyframe em index.css
code frontend/src/index.css

# Badges: testar com imóvel is_featured = true
curl "http://localhost:5000/api/v1/properties?per_page=50" | \
  python -c "import sys,json; d=json.load(sys.stdin); [print(i['title']) for i in d['items'] if i.get('is_featured')]"

# Se não houver imóveis com is_featured=true, setar um via psql:
docker-compose exec db psql -U postgres -d saas_imobiliaria \
  -c "UPDATE properties SET is_featured = true WHERE id = (SELECT id FROM properties LIMIT 1);"

---

Testes Backend

# Rodar testes existentes
docker-compose exec backend uv run pytest tests/ -v

# Rodar apenas testes de properties (quando criados para q e sort)
docker-compose exec backend uv run pytest tests/test_properties.py -v -k "search or sort"

---

Checklist de Validação Final (todos os sprints)

Semântica HTML

# Verificar no browser: DevTools → Console
document.querySelectorAll('a button, a a').length
# Deve retornar 0

Busca textual

• ?q=jardins filtra imóveis com "Jardins" no título/endereço/bairro
• ?q=AP-0042 encontra imóvel pelo código
• Campo vazio → sem parâmetro q na URL
• Caracteres especiais: ?q=São+Paulo não causa erro

Ordenação

• ?sort=price_asc → preços crescentes
• ?sort=price_desc → preços decrescentes
• ?sort=area_desc → áreas decrescentes
• ?sort=newest → mais recentes primeiro
• Valor inválido (?sort=invalid) → sem erro, usa default

Visualização

• Toggle Lista → cards horizontais
• Toggle Grade → grid de 1/2/3 colunas
• Recarregar página → preferência mantida

Mobile (testar com DevTools simulando iPhone)

• Carrossel: botões prev/next visíveis sem hover
• Card não trunca texto em 768px
• Drawer de filtros abre corretamente

Error state

• Desligar backend → mensagem de erro aparece
• Clicar "Tentar novamente" → refaz o request