Migração de framework guiada

3. Antes de tudo: Fatia 0 (não é opcional)

Com 34% de cobertura e zero teste e2e, você não tem como saber se a migração quebrou o checkout. Esta é a condição de entrada, não uma boa prática desejável.

Fatia 0, rede de segurança nos caminhos intocáveis · 2 semanas-pessoa

• Testes e2e (Playwright) cobrindo: login, login com sessão expirada, checkout com cartão, checkout com cupom, checkout com falha de pagamento.
• Critério de pronto: os 5 fluxos rodam no CI a cada PR e o pipeline falha se algum quebrar.
• Rollback: não aplicável, é adição pura.

Se o time não puder investir estas 2 semanas, recomendo não iniciar a migração. O modo de falha aqui não é atraso, é derrubar o checkout em produção sem ninguém perceber por horas.

---

1. Fatias

Fatia 1, build e compatibilidade · 1,5 semana
Migrar de webpack/vue-cli para Vite, mantendo Vue 2.7 (que já traz Composition API). Nada de componente muda.

• Por quê primeiro: destrava tudo o mais e o risco é o menor de todas as fatias, se o build quebra, você descobre imediatamente, não em produção.
• Pronto: build de produção gera bundle funcional; os 5 e2e passam; tempo de dev server abaixo de 3s.
• Rollback: reverter o commit. Nenhum código de aplicação mudou.

Fatia 2: TypeScript em modo permissivo · 1 semana
Adicionar TS com allowJs: true e strict: false. Nenhum arquivo convertido ainda.

• Por quê aqui: separa a dor da configuração da dor da conversão. Misturar as duas é o erro clássico.
• Pronto: tsc --noEmit passa no CI com zero erro sobre a base atual.
• Rollback: remover do pipeline; os arquivos .js continuam válidos.

Fatia 3, camada de dados e utilitários · 3 semanas
Converter para TS e Composition API tudo que não é componente: stores, chamadas de API, formatadores, validadores.

• Por quê antes dos componentes: é onde os tipos pagam mais e onde o risco visual é zero. Também cria os tipos que os componentes vão consumir depois.
• Pronto: 100% dos arquivos de src/stores, src/api e src/utils em .ts; cobertura destes diretórios acima de 70%.
• Rollback: por arquivo, cada conversão é um commit independente.

Fatia 4, componentes folha · 4 semanas
Os ~90 componentes sem filhos (botão, campo, badge, card). Converter para <script setup lang="ts">.

• Por quê: folhas não quebram ninguém abaixo delas. Alto volume, baixo risco, é onde o time ganha fluência.
• Pronto: nenhum componente folha usa Options API; regra de lint proíbe novos.
• Rollback: por componente. Vue 2.7 aceita as duas APIs lado a lado, então uma reversão isolada não afeta os demais.

Fatia 5, componentes de página, exceto checkout e login · 5 semanas

• Pronto: todas as rotas exceto /checkout e /login convertidas; e2e verdes.
• Rollback: por rota.

Fatia 6, o salto para Vue 3 · 3 semanas
Só agora. Com tudo em Composition API e TS, o salto vira principalmente troca de dependências e ajuste de APIs quebradas (filtros, $listeners, ciclo de vida).

• Por quê por último: é a única fatia sem rollback granular. Você quer chegar nela com o máximo de código já verificado.
• Pronto: vue@3 instalado, aplicação sobe, os 5 e2e passam, nenhum aviso de compat no console.
• Rollback: feature flag no nível do bundle, mantenha o build Vue 2 publicável por 2 semanas após o corte.

Fatia 7, checkout e login · 3 semanas
Por último, com o restante estável e a suíte e2e já provada em uso real.

• Pronto: e2e verdes + uma semana em produção com 10% do tráfego via canary.
• Rollback: roteamento por porcentagem, volta para 0% em minutos.

Total: ~22,5 semanas-pessoa. Com 3 pessoas a 40%, são 1,2 semana-pessoa por semana, cerca de 19 semanas de calendário, ou 4 meses e meio. Se alguém prometeu dois meses, a conta não fecha.

2. Camada de compatibilidade

• Vue 2.7 é a peça central: aceita Composition API e Options API no mesmo projeto. Sem ela, as fatias 3 a 5 seriam impossíveis de fatiar. Removível na fatia 6.
• allowJs: true permite .ts e .js convivendo. Removível quando o último .js sumir, provavelmente durante a fatia 5.
• Tipos de fronteira primeiro: na fatia 3, tipar o que sai da API cria o contrato que os componentes consomem nas fatias 4 e 5. Permanente.
• Canary por porcentagem de tráfego na fatia 7. Removível após 2 semanas estáveis.

4. Sinais de que está falhando (olhar nas primeiras 4 semanas)

1. A fatia 1 passou de 3 semanas. Se a configuração de build resiste, há acoplamento não mapeado (plugin caseiro, dependência de webpack interno). Replaneje antes de seguir.
2. Os e2e da fatia 0 ficam intermitentes e alguém sugere desabilitá-los. É o começo do fim: sem a rede, o resto da migração roda às cegas. Trate falso positivo como bug prioritário, nunca desabilite.
3. PRs de migração ficam abertos mais de 5 dias. Sinal de que as fatias estão grandes demais. Corte mais fino imediatamente, o custo de rebase cresce mais rápido que o progresso.

5. O que NÃO migrar

• Componentes com menos de 50 linhas que não mudam há mais de 12 meses. Custo de conversão maior que o benefício. Deixe em Options API: Vue 3 continua suportando.
• A página de relatórios legada, se ela for de fato desligada em algum horizonte conhecido. Confirme antes: "vamos desligar" sem data marcada não vale como critério.
• Testes existentes escritos em JS. Converta a suíte só quando tocar no teste por outro motivo. Teste em .js continua rodando e não impede nada.

Critério geral: se um arquivo não foi tocado em 12 meses e não é caminho crítico, o custo de migrá-lo é maior que a chance de precisar mexer nele durante a migração.