sgse-app/CONFIGURACAO_CONVEX_LOCAL.md

# 🏠 CONFIGURAÇÃO CONVEX LOCAL - SGSE

**Data:** 27/10/2025  
**Modo:** Desenvolvimento Local (não nuvem)

---

## ✅ O QUE FOI CORRIGIDO

O erro 500 estava acontecendo porque o frontend estava tentando conectar ao Convex Cloud, mas o backend está rodando **localmente**.

### **Problema identificado:**
```
❌ Frontend tentando conectar: https://sleek-cormorant-914.convex.cloud
✅ Backend rodando em: http://127.0.0.1:3210
```

### **Solução aplicada:**
1. ✅ Criado arquivo `.env` no frontend com URL local correta
2. ✅ Adicionado `setupConvex()` no layout principal
3. ✅ Configurado para usar Convex local na porta 3210

---

## 📂 ARQUIVOS CONFIGURADOS

### **1. Backend - `packages/backend/.env`**
```env
BETTER_AUTH_SECRET=+Nfg4jTxPv1giF5MlmyYTxpU/VkS3QaDOvgSWd+QmbY=
SITE_URL=http://localhost:5173
```
- ✅ Secret configurado
- ✅ URL da aplicação definida
- ✅ Roda na porta 3210 (padrão do Convex local)

### **2. Frontend - `apps/web/.env`**
```env
PUBLIC_CONVEX_URL=http://127.0.0.1:3210
PUBLIC_SITE_URL=http://localhost:5173
```
- ✅ Conecta ao Convex local
- ✅ URL pública para autenticação

### **3. Layout Principal - `apps/web/src/routes/+layout.svelte`**
```typescript
// Configurar Convex para usar o backend local
setupConvex(PUBLIC_CONVEX_URL);
```
- ✅ Inicializa conexão com Convex local

---

## 🚀 COMO INICIAR O PROJETO

### **Método Simples (Recomendado):**

```powershell
cd "C:\Users\Deyvison\OneDrive\Desktop\Secretaria de Esportes\Tecnologia da Informacao\SGSE\sgse-app"
bun dev
```

Isso inicia automaticamente:
- 🔹 **Backend Convex** na porta **3210**
- 🔹 **Frontend SvelteKit** na porta **5173**

### **Método Manual (Dois terminais):**

**Terminal 1 - Backend:**
```powershell
cd "C:\Users\Deyvison\OneDrive\Desktop\Secretaria de Esportes\Tecnologia da Informacao\SGSE\sgse-app\packages\backend"
bunx convex dev
```

**Terminal 2 - Frontend:**
```powershell
cd "C:\Users\Deyvison\OneDrive\Desktop\Secretaria de Esportes\Tecnologia da Informacao\SGSE\sgse-app\apps\web"
bun run dev
```

---

## 🌐 ACESSAR A APLICAÇÃO

Após iniciar os servidores, acesse:

**URL Principal:** http://localhost:5173

---

## 🔍 VERIFICAR SE ESTÁ FUNCIONANDO

### **✅ Backend Convex (Terminal 1):**
Deve mostrar:
```
✔ Convex functions ready!
✔ Serving at http://127.0.0.1:3210
```

### **✅ Frontend (Terminal 2):**
Deve mostrar:
```
VITE v... ready in ...ms
➜  Local:   http://localhost:5173/
```

### **✅ No navegador:**
- ✅ Página carrega sem erro 500
- ✅ Dashboard aparece normalmente
- ✅ Dados são carregados do Convex local

---

## 📊 ARQUITETURA LOCAL

```
┌─────────────────────────────────────────┐
│         Navegador (localhost:5173)      │
│              Frontend SvelteKit         │
└────────────────┬────────────────────────┘
                 │ HTTP
                 │ setupConvex(http://127.0.0.1:3210)
                 ↓
┌─────────────────────────────────────────┐
│      Convex Local (127.0.0.1:3210)     │
│              Backend Convex             │
│         ┌─────────────────────┐         │
│         │  Banco de Dados     │         │
│         │  (SQLite local)     │         │
│         └─────────────────────┘         │
└─────────────────────────────────────────┘
```

---

## ⚠️ IMPORTANTE: MODO LOCAL vs NUVEM

### **Modo Local (Atual):**
- ✅ Convex roda no seu computador
- ✅ Dados armazenados localmente
- ✅ Não precisa de internet para funcionar
- ✅ Ideal para desenvolvimento
- ✅ Porta padrão: 3210

### **Modo Nuvem (NÃO estamos usando):**
- ❌ Convex roda nos servidores da Convex
- ❌ Dados na nuvem
- ❌ Precisa de internet
- ❌ Requer configuração adicional
- ❌ URL: https://[projeto].convex.cloud

---

## 🔧 SOLUÇÃO DE PROBLEMAS

### **Erro 500 ainda aparece:**
1. **Pare todos os servidores** (Ctrl+C)
2. **Verifique o arquivo .env:**
   ```powershell
   cd apps\web
   Get-Content .env
   ```
   Deve mostrar: `PUBLIC_CONVEX_URL=http://127.0.0.1:3210`
3. **Inicie novamente:**
   ```powershell
   cd ..\..
   bun dev
   ```

### **"Cannot connect to Convex":**
1. Verifique se o backend está rodando:
   ```powershell
   # Deve mostrar processo na porta 3210
   netstat -ano | findstr :3210
   ```
2. Se não estiver, inicie o backend:
   ```powershell
   cd packages\backend
   bunx convex dev
   ```

### **"Port 3210 already in use":**
Já existe um processo usando a porta. Mate o processo:
```powershell
# Encontrar PID
netstat -ano | findstr :3210

# Matar processo (substitua PID)
taskkill /PID <PID> /F
```

### **Dados não aparecem:**
1. Verifique se há dados no banco local
2. Execute o seed (popular banco):
   ```powershell
   cd packages\backend\convex
   # (Criar script de seed se necessário)
   ```

---

## 📝 CHECKLIST DE VERIFICAÇÃO

- [ ] Backend Convex rodando na porta 3210
- [ ] Frontend rodando na porta 5173
- [ ] Arquivo `.env` existe em `apps/web/`
- [ ] `PUBLIC_CONVEX_URL=http://127.0.0.1:3210` está correto
- [ ] Navegador abre sem erro 500
- [ ] Dashboard carrega os dados
- [ ] Nenhum erro no console do navegador (F12)

---

## 🎯 DIFERENÇAS DOS ARQUIVOS .env

### **Backend (`packages/backend/.env`):**
```env
# Usado pelo Convex local
BETTER_AUTH_SECRET=... (secret criptográfico)
SITE_URL=http://localhost:5173 (URL do frontend)
```

### **Frontend (`apps/web/.env`):**
```env
# Usado pelo SvelteKit
PUBLIC_CONVEX_URL=http://127.0.0.1:3210 (URL do Convex local)
PUBLIC_SITE_URL=http://localhost:5173 (URL da aplicação)
```

**Importante:** As variáveis com prefixo `PUBLIC_` no SvelteKit são expostas ao navegador.

---

## 🔐 SEGURANÇA

### **Arquivos .env:**
- ✅ Estão no `.gitignore`
- ✅ Não serão commitados
- ✅ Secrets não vazam

### **Para Produção (Futuro):**
Quando for colocar em produção:
1. 🔐 Gerar novo secret de produção
2. 🌐 Configurar Convex Cloud (se necessário)
3. 🔒 Usar variáveis de ambiente do servidor

---

## 📞 COMANDOS ÚTEIS

```powershell
# Verificar se portas estão em uso
netstat -ano | findstr :3210
netstat -ano | findstr :5173

# Matar processo em uma porta
taskkill /PID <PID> /F

# Limpar e reinstalar dependências
bun install

# Ver logs do Convex
cd packages\backend
bunx convex dev --verbose

# Ver logs do frontend (terminal do Vite)
cd apps\web
bun run dev
```

---

## ✅ RESUMO

| Componente | Status | Porta | URL |
|------------|--------|-------|-----|
| Backend Convex | ✅ Local | 3210 | http://127.0.0.1:3210 |
| Frontend SvelteKit | ✅ Local | 5173 | http://localhost:5173 |
| Banco de Dados | ✅ Local | - | SQLite (arquivo local) |
| Autenticação | ✅ Config | - | Better Auth |

---

## 🎉 CONCLUSÃO

**Tudo configurado para desenvolvimento local!**

- ✅ Erro 500 corrigido
- ✅ Frontend conectando ao Convex local
- ✅ Backend rodando localmente
- ✅ Pronto para desenvolvimento

**Para iniciar:**
```powershell
bun dev
```

**Para acessar:**
```
http://localhost:5173
```

---

**Criado em:** 27/10/2025 às 09:15  
**Modo:** Desenvolvimento Local  
**Status:** ✅ Pronto para uso

---

**🚀 Bom desenvolvimento!**