🗄️ Vercel KV Setup Guide¶

O que é Vercel KV?¶

Vercel KV é um Redis database serverless, totalmente gerido pela Vercel. Perfeito para: - Armazenar métricas de uso - Cache de dados - Rate limiting - Session storage

🚀 Como Configurar¶

Método 1: Via Vercel Dashboard (Recomendado)¶

⚠️ NOTA: A Vercel moveu o KV e Postgres para o Marketplace!

Acede ao teu projeto no Vercel:

https://vercel.com/seu-username/codeslick2

Vai para o Marketplace:
Clica em "Storage" no menu lateral (vai redirecionar para o Marketplace)
Ou acede diretamente ao Marketplace: https://vercel.com/marketplace
Ou no teu projeto: vai para "Integrations" ou procura por "Vercel KV"
Instala Vercel KV via Marketplace:
Procura por "Vercel KV" no Marketplace
Clica em "Add Integration" ou "Install"
Seleciona o teu projeto codeslick2
Autoriza a instalação
Cria uma nova KV Database:
Depois de instalar, vai para Storage no teu projeto
Clica em "Create Database"
Seleciona "KV" (Redis)
Nome sugerido: codeslick-metrics
Região: Escolhe a mais próxima dos teus users (ex: Frankfurt para EU)
Conecta ao Projeto:
Depois de criar, clica em "Connect Project"
Seleciona o projeto codeslick2
Seleciona os ambientes: Production, Preview, Development
Clica em "Connect"

Variáveis Criadas Automaticamente: A Vercel cria estas variáveis automaticamente:

KV_REST_API_URL=https://...
KV_REST_API_TOKEN=...
KV_REST_API_READ_ONLY_TOKEN=...

Redeploy:
Vai para Deployments
Clica nos 3 pontinhos do último deployment
Clica em "Redeploy"

Método 2: Via CLI¶

# 1. Install Vercel CLI (se ainda não tens)
npm i -g vercel

# 2. Login
vercel login

# 3. Link ao projeto
cd "/Users/vikthor/Dropbox/My Mac (MacBook-Air-de-Vitor.local)/Documents/GitHub/codeslick2"
vercel link

# 4. Criar KV database
vercel kv create codeslick-metrics

# 5. Conectar ao projeto
# Segue as instruções no terminal para conectar

# 6. Pull environment variables para local
vercel env pull .env.local

# 7. Deploy
vercel --prod

🧪 Testar Localmente¶

Opção A: Com Vercel KV Real (Recomendado)¶

Pull das variáveis de ambiente:
```
vercel env pull .env.local
```
Inicia o servidor:
```
npm run dev
```
Testa uma análise de código:
Acede: http://localhost:3000
Cola código e clica em "Analyze"
Depois acede: http://localhost:3000/dashboard
Verifica se as métricas aparecem!

Opção B: Sem Vercel KV (Mock)¶

Se não quiseres configurar KV ainda, podes usar um mock local:

# Instala Redis localmente (opcional)
brew install redis  # macOS
# ou
apt-get install redis  # Linux

# Inicia Redis
redis-server

# Atualiza .env.local
KV_REST_API_URL=http://localhost:6379
KV_REST_API_TOKEN=mock-token

Nota: O código vai funcionar sem KV, mas não vai armazenar métricas (vai mostrar 0s no dashboard).

📊 Como Funciona o Tracking¶

1. Quando um user faz análise de código:¶

// src/lib/utils/advanced-qwen.ts
await this.trackUsage({
  prompt: "...",  // Código enviado
  response: {...}, // Resposta da AI
  latency: 1250,  // Tempo de resposta (ms)
  success: true   // Se foi bem-sucedido
});

2. UsageTracker armazena em KV:¶

// src/lib/tracking/usage-tracker.ts
await kv.set(`usage:together:${timestamp}`, {
  tokens: { input: 1200, output: 800, total: 2000 },
  cost: 0.0004,  // $0.0004
  latency: 1250,
  model: "Qwen/Qwen2.5-Coder-32B-Instruct",
  success: true
});

3. Agregados diários e mensais:¶

// Agregado do dia
await kv.set('usage:together:daily:2025-10-05', {
  totalTokens: 125000,
  totalCost: 0.025,
  totalRequests: 50,
  successfulRequests: 48,
  failedRequests: 2
});

4. Dashboard busca métricas:¶

// src/lib/integrations/together-client.ts
const metrics = await UsageTracker.getMetrics('last30days');
// Retorna: tokens, custos, latência, taxa de sucesso

💰 Custos do Vercel KV¶

Free Tier¶

✅ 256 MB de storage
✅ 3GB de dados transferidos/mês
✅ Perfeito para começar

Se precisares mais:¶

Pro Plan: $20/mês
1 GB storage
50 GB data transfer

Estimativa para CodeSlick:¶

Cada análise = ~2KB de dados
1000 análises/mês = ~2MB
Free tier é mais que suficiente!

🔍 Debugging¶

Ver dados no Vercel KV:¶

Via Dashboard:
Vai para: https://vercel.com/seu-username/codeslick2/stores/codeslick-metrics
Clica em "Data Browser"
Podes ver todas as keys e values

Via CLI:

# Ver todas as keys
vercel kv list

# Ver um valor específico
vercel kv get "usage:together:daily:2025-10-05"

Testar tracking:

# Faz uma análise no localhost
# Depois verifica:
curl http://localhost:3000/api/metrics | jq '.together'

🐛 Troubleshooting¶

Erro: "kv is not defined"¶

Causa: Variáveis KV não configuradas

Solução:

vercel env pull .env.local
# ou
vercel link  # Re-link ao projeto

Métricas mostram 0 no dashboard¶

Causa: KV não está conectado ou sem dados

Solução: 1. Faz uma análise de código primeiro 2. Espera ~30s 3. Recarrega o dashboard 4. Se ainda estiver em 0:

# Verifica se KV tem dados
vercel kv get "usage:together:daily:$(date +%Y-%m-%d)"

Erro: "Cannot connect to KV"¶

Causa: KV database não existe ou não está conectada

Solução: 1. Vai para Vercel Dashboard > Storage 2. Verifica se o database existe 3. Verifica se está conectado ao projeto 4. Redeploy o projeto

✅ Checklist de Setup¶

Criar KV database no Vercel
Conectar ao projeto codeslick2
Pull environment variables: vercel env pull
Testar localmente: fazer uma análise
Ver métricas no dashboard: http://localhost:3000/dashboard
Deploy para produção: vercel --prod
Testar em produção: fazer análise e ver dashboard

📝 Variáveis de Ambiente (Referência)¶

Depois de configurar o KV, estas variáveis estarão no .env.local:

# Vercel KV (geradas automaticamente)
KV_REST_API_URL=https://generous-fox-12345.kv.vercel-storage.com
KV_REST_API_TOKEN=AabBcCdDeEfF...
KV_REST_API_READ_ONLY_TOKEN=AabBcCdDeEfF...

# Outras variáveis (já configuradas antes)
DASHBOARD_API_KEY=c9fa6315e5a9569a49652f8a882831529f2e6a5ca127d1b6fb7177249322deb2
QWEN_API_KEY=tgp_v1_...
# etc.

🎉 Setup completo! Agora o dashboard vai mostrar métricas reais de uso da API!