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

.specify/features/005-authentication/quickstart.md

@@ -0,0 +1,137 @@
+# Quickstart: 005-authentication
+
+**Como configurar, migrar e testar o sistema de autenticação localmente.**
+
+---
+
+## Pré-requisitos
+
+- Docker + Docker Compose rodando (`.\start.ps1` ou `docker-compose up`)
+- Backend acessível em `http://localhost:5000`
+- Frontend acessível em `http://localhost:5173`
+
+---
+
+## 1. Variáveis de Ambiente
+
+Adicione ao `backend/.env` (e ao `docker-compose.yml` se o container não herdar o `.env`):
+
+```
+JWT_SECRET_KEY=sua-chave-secreta-longa-e-aleatoria-aqui
+```
+
+> Gere uma chave segura no terminal:
+> ```powershell
+> python -c "import secrets; print(secrets.token_hex(32))"
+> ```
+
+---
+
+## 2. Instalar Novas Dependências (backend)
+
+```powershell
+cd backend
+uv add "PyJWT>=2.9" "bcrypt>=4.2" "pydantic[email]"
+```
+
+Verifique que `uv.lock` foi atualizado e commit junto com o `pyproject.toml` atualizado.
+
+---
+
+## 3. Gerar e Aplicar a Migration
+
+```powershell
+# Com DATABASE_URL definida ou container rodando:
+uv run flask db migrate -m "add client_users"
+uv run flask db upgrade
+```
+
+Teste o ciclo completo antes de commitar:
+```powershell
+uv run flask db downgrade
+uv run flask db upgrade
+```
+
+---
+
+## 4. Testar os Endpoints Manualmente
+
+### Cadastro
+```powershell
+Invoke-WebRequest -Uri "http://localhost:5000/api/v1/auth/register" `
+  -Method POST `
+  -ContentType "application/json" `
+  -Body '{"name":"Teste","email":"teste@exemplo.com","password":"senha1234"}'
+```
+
+### Login
+```powershell
+Invoke-WebRequest -Uri "http://localhost:5000/api/v1/auth/login" `
+  -Method POST `
+  -ContentType "application/json" `
+  -Body '{"email":"teste@exemplo.com","password":"senha1234"}'
+```
+
+### Perfil autenticado
+```powershell
+$TOKEN = "<access_token da resposta acima>"
+Invoke-WebRequest -Uri "http://localhost:5000/api/v1/auth/me" `
+  -Headers @{ Authorization = "Bearer $TOKEN" }
+```
+
+### Rota protegida sem token (deve retornar 401)
+```powershell
+Invoke-WebRequest -Uri "http://localhost:5000/api/v1/auth/me"
+# Espera: StatusCode 401
+```
+
+---
+
+## 5. Rodar os Testes (backend)
+
+```powershell
+cd backend
+uv run pytest tests/ -v
+```
+
+---
+
+## 6. Frontend — Verificar os Fluxos
+
+Com backend + frontend rodando:
+
+| URL | Comportamento esperado |
+|-----|------------------------|
+| `http://localhost:5173/login` | Exibe formulário de login com estilo Linear dark |
+| `http://localhost:5173/cadastro` | Exibe formulário de cadastro |
+| `http://localhost:5173/area-do-cliente` | Redireciona para `/login` se não autenticado |
+| Após login bem-sucedido | Redireciona para `/area-do-cliente` |
+| Navbar sem autenticação | Botão "Entrar" visível |
+| Navbar autenticado | Inicial do usuário + botão "Sair" visível |
+
+---
+
+## 7. Verificar Token no localStorage
+
+No console do navegador (após login):
+
+```javascript
+localStorage.getItem('imob_token')  // deve retornar o JWT string
+```
+
+Após logout:
+
+```javascript
+localStorage.getItem('imob_token')  // deve retornar null
+```
+
+---
+
+## 8. Checklist de Segurança Pós-implementação
+
+- [ ] `JWT_SECRET_KEY` não aparece em nenhum arquivo versionado (`.env.example` pode ter placeholder)
+- [ ] `grep -r "JWT_SECRET" backend/app/` retorna apenas referências a `os.environ` ou `app.config`
+- [ ] Login com senha errada retorna 401 com mensagem genérica (não indica se e-mail ou senha está incorreto)
+- [ ] Cadastro com e-mail duplicado retorna 409 (não 500)
+- [ ] Acesso a `/api/v1/auth/me` sem token retorna 401 (não 500)
+- [ ] `password_hash` nunca aparece em nenhuma resposta JSON da API