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

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

@@ -0,0 +1,160 @@
+# 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