# 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)
- [x] Documentação completa
- [x] 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**:
```typescript
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.