160 lines
4.7 KiB
Markdown
160 lines
4.7 KiB
Markdown
# 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`)
|
||
|
||
```bash
|
||
# 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`
|
||
|
||
```bash
|
||
# 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`.
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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`
|
||
|
||
```bash
|
||
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`
|
||
|
||
```bash
|
||
code frontend/src/components/PropertyGridCard.tsx
|
||
# Testar em http://localhost:5174/imoveis — ativar toggle de Grade
|
||
```
|
||
|
||
### 3. Frontend: `ActiveFiltersBar`
|
||
|
||
```bash
|
||
code frontend/src/components/ActiveFiltersBar.tsx
|
||
# Testar: aplicar filtro cidade → chip aparece → clicar × → filtro removido
|
||
```
|
||
|
||
---
|
||
|
||
## Sprint 3 — Ordem de Trabalho Recomendada
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|