sgse-app/PLANO_MIGRACAO_BETTER_AUTH.md

Plano de Migração para Better Auth - Garantia de Funcionamento

🎯 Estratégia: Migração Dual (Zero Downtime)

Garantia: Sistema atual continua funcionando durante toda a migração. Se algo falhar, simplesmente revertemos uma linha de código.

📋 Análise Completa de Dependências

Backend (7 arquivos usando getUsuarioAutenticado):

1. ✅ chat.ts - Crítico (mensagens)
2. ✅ usuarios.ts - Crítico (perfil)
3. ✅ pushNotifications.ts - Importante
4. ✅ preferenciasNotificacao.ts - Importante
5. ✅ atestadosLicencas.ts - Médio
6. ✅ permissoesAcoes.ts - Médio
7. ✅ monitoramento.ts - Baixo

Frontend (24 arquivos usando authStore):

• ✅ Todos usam useConvexClient() que pega auth automaticamente
• ✅ Não há setAuth() manual nos componentes (exceto refresh)
• ✅ Sidebar.svelte é o único lugar que faz login customizado

🔄 Fases de Migração (Cada fase é testável e reversível)

✅ FASE 0: Preparação (Sem Risco)

• Documentação completa
• Análise de dependências
• Backups de configuração atual

✅ FASE 1: Configurar Better Auth no Convex (Baixo Risco)

Status: Configuração apenas, sistema atual continua funcionando

Arquivo: packages/backend/convex/convex.config.ts

• Adicionar Better Auth provider
• Testar ctx.auth.getUserIdentity() retornando dados

Rollback: Simplesmente comentar a configuração

Tempo: 30 minutos

---

✅ FASE 2: Migração Dual - Login (Médio Risco)

Status: Ambos sistemas funcionam simultaneamente

Estratégia:

• Better Auth como primário
• Sistema customizado como fallback
• Logs para comparar resultados

Arquivos:

• apps/web/src/lib/components/Sidebar.svelte - Suportar ambos logins
• apps/web/src/lib/stores/auth.svelte.ts - Detectar qual método usar

Teste: Login com Better Auth e verificar que tudo funciona Rollback: Remover código Better Auth, manter apenas customizado

Tempo: 1 hora

---

✅ FASE 3: Migração Dual - Backend Helpers (Baixo Risco)

Status: Helper tenta Better Auth primeiro, fallback para customizado

Arquivos (7 arquivos):

• packages/backend/convex/chat.ts
• packages/backend/convex/usuarios.ts
• packages/backend/convex/pushNotifications.ts
• packages/backend/convex/preferenciasNotificacao.ts
• packages/backend/convex/atestadosLicencas.ts
• packages/backend/convex/permissoesAcoes.ts
• packages/backend/convex/monitoramento.ts

Estratégia:

async function getUsuarioAutenticado(ctx) {
  // 1. Tentar Better Auth primeiro
  const identity = await ctx.auth.getUserIdentity();
  if (identity?.email) {
    // Buscar usuário do Better Auth
    const usuario = await buscarPorEmail(identity.email);
    if (usuario) return usuario;
  }
  
  // 2. Fallback para sistema customizado (se Better Auth não funcionar)
  // ... código atual ...
}

Teste: Cada mutation/query deve funcionar com ambos sistemas Rollback: Remover código Better Auth, manter apenas fallback

Tempo: 1 hora

---

✅ FASE 4: Integrar Convex com Better Auth (Médio Risco)

Status: Convex passa a usar Better Auth automaticamente

Arquivo: apps/web/src/routes/+layout.svelte

• Descomentar createSvelteAuthClient
• Configurar Convex para usar Better Auth automaticamente

Teste: Todas requisições devem funcionar sem setAuth() manual Rollback: Comentar novamente

Tempo: 30 minutos

---

✅ FASE 5: Migração Completa - Frontend (Médio Risco)

Status: Remover sistema customizado do frontend

Arquivos:

• apps/web/src/lib/components/Sidebar.svelte - Usar apenas Better Auth
• apps/web/src/lib/stores/auth.svelte.ts - Adaptar para Better Auth
• Remover auth_token do localStorage

Teste: Login/logout completo Rollback: Reverter para código anterior

Tempo: 1 hora

---

✅ FASE 6: Migração Completa - Backend (Baixo Risco)

Status: Remover fallback customizado dos helpers

Arquivos: Os mesmos 7 arquivos da Fase 3

• Remover código de fallback customizado
• Manter apenas Better Auth

Teste: Tudo deve funcionar apenas com Better Auth Rollback: Restaurar código com fallback

Tempo: 30 minutos

---

✅ FASE 7: Limpeza (Sem Risco)

Status: Remover código não usado

Arquivos:

• packages/backend/convex/autenticacao.ts - Manter para logs históricos ou remover
• Limpar tokens antigos do localStorage (se houver)

Tempo: 30 minutos

---

⚠️ Pontos de Atenção e Como Mitigar

1. Sessões Ativas Existentes

Problema: Usuários logados perderão sessão Mitigação:

• Fazer migração fora do horário de pico
• Avisar usuários para fazer logout/login
• Manter ambos sistemas por alguns dias

2. Tokens no localStorage

Problema: Tokens antigos podem causar confusão Mitigação:

• Criar script de migração que limpa tokens antigos
• Detectar e migrar automaticamente na primeira abertura

3. Email como Identificador Único

Problema: Better Auth usa email, sistema atual usa ID Mitigação:

• Verificar que todos usuários têm email único
• Criar índices no banco se necessário

4. Testes em Produção

Problema: Diferenças entre dev e produção Mitigação:

• Testar em ambiente de staging primeiro
• Migração gradual por módulo
• Monitorar logs de erro

✅ Checklist de Garantia

Antes de completar cada fase:

• Testar login/logout
• Testar queries críticas
• Testar mutations críticas
• Verificar logs de erro
• Testar com múltiplos usuários
• Verificar autenticação em componentes críticos (Chat, Perfil, etc)

🚨 Plano de Rollback

Se algo der errado em qualquer fase:

1. Fase 1-3: Comentar configuração Better Auth, manter sistema atual
2. Fase 4: Reverter layout.svelte para código anterior
3. Fase 5: Restaurar código de Sidebar e authStore
4. Fase 6: Restaurar helpers com fallback

Tempo de rollback: Máximo 5 minutos por fase

📊 Garantia Final

Posso garantir:

• ✅ Sistema atual continua funcionando durante migração
• ✅ Rollback rápido em caso de problemas
• ✅ Testes em cada fase antes de prosseguir
• ✅ Documentação completa de cada passo

Não posso garantir:

• ❌ Zero bugs (impossível sem testes reais)
• ❌ Compatibilidade 100% sem testar em ambiente real
• ❌ Que não haverá necessidade de ajustes finos

Mas posso garantir:

• ✅ Que se algo falhar, revertemos imediatamente
• ✅ Que testes serão feitos antes de cada avanço
• ✅ Que código estará documentado para debugging fácil

🎬 Decisão

Opções:

1. Migração completa (6 horas total, fases separadas)
2. Solução rápida (Configurar Custom Auth Provider - 1 hora)
3. Manter como está (Corrigir apenas o problema imediato)

Minha recomendação: Opção 1, mas fazer fase por fase, testando bem entre cada uma.