sass-imobiliaria/.specify/features/006-client-area/quickstart.md

# Quickstart: Área do Cliente (Feature 006)

**Pré-requisito**: Feature 005 (autenticação) implementada e funcionando.

---

## 1. Rodar o ambiente de desenvolvimento

```powershell
# Na raiz do projeto
.\start.ps1
```

Isso inicia backend (Flask) na porta 5000 e frontend (Vite) na porta 5173 via Docker Compose.

---

## 2. Aplicar a migration

```bash
# Dentro do container backend ou com uv no host
docker compose exec backend flask db upgrade
```

Verifica que as tabelas `saved_properties`, `visit_requests` e `boletos` foram criadas:

```bash
docker compose exec db psql -U postgres -d imobiliaria -c "\dt"
```

---

## 3. Obter um token de ClientUser

```bash
# Registrar um cliente (se Feature 005 estiver implementada)
curl -X POST http://localhost:5000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "João Silva", "email": "joao@test.com", "password": "Senha123!"}'

# Login para obter token
curl -X POST http://localhost:5000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "joao@test.com", "password": "Senha123!"}'
# → {"access_token": "eyJ..."}
export TOKEN="eyJ..."
```

---

## 4. Testar rotas de favoritos

```bash
# Listar favoritos (deve retornar [])
curl http://localhost:5000/api/v1/me/favorites \
  -H "Authorization: Bearer $TOKEN"

# Adicionar imóvel aos favoritos (usar UUID de um imóvel existente)
curl -X POST http://localhost:5000/api/v1/me/favorites \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"property_id": "<uuid-do-imovel>"}'
# → 201

# Tentar adicionar novamente (deve retornar 409)
curl -X POST http://localhost:5000/api/v1/me/favorites \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"property_id": "<uuid-do-imovel>"}'
# → 409

# Remover favorito
curl -X DELETE http://localhost:5000/api/v1/me/favorites/<uuid-do-imovel> \
  -H "Authorization: Bearer $TOKEN"
# → 204
```

---

## 5. Testar criação de boleto (admin)

```bash
# Primeiro, obter o user_id do cliente criado
USER_ID="<uuid-do-client-user>"

curl -X POST http://localhost:5000/api/v1/admin/boletos \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"user_id\": \"$USER_ID\",
    \"description\": \"Aluguel Maio/2026\",
    \"amount\": 3500.00,
    \"due_date\": \"2026-05-10\"
  }"
# → 201

# Listar boletos do cliente
curl http://localhost:5000/api/v1/me/boletos \
  -H "Authorization: Bearer $TOKEN"
```

---

## 6. Testar atualização de status de visita (admin)

```bash
# Listar visitas (deve retornar [] inicialmente)
curl http://localhost:5000/api/v1/me/visits \
  -H "Authorization: Bearer $TOKEN"

# Criar visita via formulário de contato (com token JWT no header)
curl -X POST http://localhost:5000/api/v1/properties/<slug>/contact \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "João Silva", "email": "joao@test.com", "message": "Quero visitar."}'

# Obter ID da visita criada e atualizar status
VISIT_ID="<uuid-da-visita>"
curl -X PUT http://localhost:5000/api/v1/admin/visits/$VISIT_ID/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "confirmed", "scheduled_at": "2026-05-01T10:00:00"}'
# → 200
```

---

## 7. Rodar testes de backend

```bash
docker compose exec backend uv run pytest tests/test_client_area.py -v
```

Ou localmente (se Python 3.12 instalado):

```bash
cd backend
uv run pytest tests/test_client_area.py -v
```

---

## 8. Acessar a área do cliente no navegador

1. Abrir http://localhost:5173
2. Fazer login com as credenciais criadas no passo 3
3. Navegar para http://localhost:5173/area-do-cliente
4. Testar favoritar um imóvel do catálogo (coração no card)
5. Acessar http://localhost:5173/area-do-cliente/favoritos e verificar o imóvel favoritado
6. Adicionar imóveis à comparação (botão "Comparar" nos cards), acessar http://localhost:5173/area-do-cliente/comparar

---

## 9. UUID de imóveis existentes

Para obter UUIDs de imóveis para testar:

```bash
curl http://localhost:5000/api/v1/properties?per_page=3 | python -m json.tool
```

---

## Solução de Problemas

| Problema | Causa Provável | Solução |
|----------|----------------|---------|
| 401 em todas as rotas `/me` | Feature 005 não implementada ou `require_auth` não disponível | Verificar se `ClientUser` model e `require_auth` decorator existem |
| `relation "client_users" does not exist` | Migration da Feature 005 não aplicada | `flask db upgrade` para aplicar todas as migrations pendentes |
| `relation "saved_properties" does not exist` | Migration desta feature não aplicada | `flask db upgrade` |
| HeartButton não aparece nos cards | `FavoritesContext` não injetado no `App.tsx` | Verificar providers em `App.tsx` |
| Rotas `/area-do-cliente/*` não redirecionam para login | `ProtectedRoute` não configurado | Verificar `App.tsx` e componente `ProtectedRoute` de Feature 005 |