# 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