Como redesenhamos um processo de migração de 5.000+ clientes na Wellhub

O gargalo parecia ser uma migração lenta. O problema real estava no processo ao redor dela.

Durante aproximadamente um ano, trabalhei como Technical Program Manager na Wellhub em um programa de migração de clientes de um ambiente legado para um novo ambiente.

O desafio envolvia mais de 5.000 empresas. Como a Wellhub opera em um modelo B2B2C, cada uma dessas empresas poderia representar diversos utilizadores associados que também seriam impactados pela migração.

Quando recebi o projeto, a operação conseguia migrar aproximadamente 10 a 15 clientes por mês.

Meu desafio não veio acompanhado de uma solução definida. A pergunta era essencialmente:

Por que estamos migrando tão devagar e como podemos melhorar esse processo?

A resposta mais óbvia poderia ser otimizar ou reescrever a API responsável pelas validações.

Mas, depois de entender o fluxo de ponta a ponta, percebi que esse não era o principal problema.

A API continuou levando aproximadamente 15 minutos para executar antes e depois do projeto.

O que mudou foi tudo ao redor dela.

---

O problema que recebemos

Antes de uma empresa ser migrada, era necessário determinar se ela realmente estava preparada para o novo ambiente.

Isso envolvia diversas regras e verificações em diferentes sistemas.

Já existia uma aplicação e uma API responsáveis por executar essas validações. Portanto, tecnicamente, o mecanismo central do processo existia.

Mesmo assim, a velocidade das migrações era baixa.

Um dos primeiros passos foi entender não apenas o código ou a API, mas como as pessoas realmente operavam o processo.

Isso exigiu diversas conversas com Business Transformation, Data e outros developers.

Meu papel como Technical Program Manager nesse projeto ficou justamente na interseção entre essas áreas: entender o processo de negócio, identificar onde tecnologia poderia remover gargalos e transformar isso em uma solução que pudesse ser utilizada no dia a dia.

---

Como funcionava o processo

O fluxo original era aproximadamente este:

Google Sheet
      ↓
Exportação CSV
      ↓
Upload em uma aplicação
      ↓
API de validação
      ↓
~15 minutos de processamento
      ↓
Resultados armazenados em uma tabela
      ↓
Consulta através do Metabase
      ↓
Business Transformation analisa os erros
      ↓
Correções
      ↓
Nova tentativa

A Google Sheet possuía mais de 5.000 linhas, aproximadamente uma por empresa.

Business Transformation preparava os dados, exportava um CSV e enviava esse arquivo para o processo de validação.

A API então verificava diferentes sistemas e regras para determinar se cada cliente estava preparado para a migração.

O processamento levava aproximadamente 15 minutos.

Olhando apenas para esse fluxo, era fácil concluir que esses 15 minutos eram o problema.

Mas não eram.

---

O gargalo não estava onde parecia

Ao acompanhar o processo de perto, percebi que existiam gargalos importantes antes e depois da API.

Antes da API, havia um problema de qualidade dos dados.

Os CSVs podiam conter:

• problemas de formatação;
• campos obrigatórios ausentes;
• valores inválidos;
• combinações inconsistentes entre colunas.

Em alguns casos, o problema era simples o suficiente para impedir que o processamento começasse corretamente.

O impacto disso ia muito além de uma tentativa que falhou.

Quando um CSV não funcionava, Business Transformation precisava recorrer à Engenharia para descobrir o motivo.

Isso acontecia aproximadamente cinco vezes por dia.

Um developer precisava interromper o que estava fazendo, investigar o arquivo, identificar o problema e explicar o que precisava ser corrigido.

Depois o arquivo era ajustado e todo o processo começava novamente.

Existia também um problema depois da execução.

Mesmo quando a API funcionava corretamente, os resultados eram técnicos e difíceis de interpretar para quem estava operando a migração.

Portanto, tínhamos dois problemas diferentes:

Input difícil de validar
        ↓
       API
        ↓
Output difícil de interpretar

A API estava no meio do processo, mas grande parte do desperdício acontecia ao redor dela.

Foi nesse momento que a direção da solução ficou mais clara para mim.

Em vez de começar reescrevendo algo que já funcionava, poderíamos melhorar a maneira como as pessoas interagiam com esse sistema.

---

Aproximando a validação da origem dos dados

Os dados já eram preparados em uma Google Sheet.

Em vez de criar uma nova ferramenta e obrigar Business Transformation a adotar outro fluxo, propus transformar a própria planilha em uma camada operacional para o processo de migração.

A solução foi construída utilizando Google Apps Script e JavaScript.

A ideia era simples:

detectar o máximo possível de problemas antes que os dados chegassem à API.

A planilha passou a executar uma série de pré-validações.

Entre elas estavam:

• validação de formatos;
• verificação de campos obrigatórios;
• obrigatoriedade condicional de campos;
• relações entre valores de diferentes colunas;
• comparação entre valores;
• cálculos e validações relacionados aos valores dos planos.

Por exemplo, se determinado modelo de contrato fosse selecionado, outras colunas poderiam se tornar obrigatórias.

Em outros casos, o valor de um campo não poderia ser inferior ao valor presente em outro.

Também existiam validações envolvendo cálculos, como a relação entre o valor por utilizador e o valor total de um plano.

O objetivo não era reproduzir toda a lógica da API dentro da planilha.

A API continuava sendo responsável pelas validações que dependiam dos sistemas e regras existentes.

A pré-validação tinha outro objetivo:

impedir que erros que já podiam ser identificados na origem percorressem todo o pipeline.

---

O desafio de validar mais de 5.000 registros

A primeira versão dessa ideia trouxe outro problema técnico.

A planilha tinha mais de 5.000 registros e diversas regras precisavam ser verificadas.

Executar todas essas validações sequencialmente tornou-se inviável.

O processamento demorava demais e começava a atingir os limites e timeouts do Google Apps Script.

Isso criou um trade-off interessante.

Quanto mais validações adicionávamos para proteger o processo, mais pesado ficava o próprio mecanismo de pré-validação.

Não adiantava criar uma solução que evitasse erros na API se o utilizador precisasse esperar indefinidamente pela planilha.

Foi necessário mudar a estratégia de processamento.

---

Processamento assíncrono e paralelo

Para tornar a pré-validação viável nesse volume, redesenhei o processamento para dividir o trabalho e executar partes das validações através de processos assíncronos e paralelizados.

Em vez de tratar as mais de 5.000 linhas como uma única execução sequencial, o trabalho passou a ser dividido.

Conceitualmente:

5.000+ registros
      ↓
Divisão do processamento
      ↓
Execuções assíncronas / paralelas
      ↓
Consolidação dos resultados
      ↓
Resultado da pré-validação

Essa mudança permitiu executar as validações dentro das limitações da plataforma.

Foi uma parte importante do projeto porque mostrou que a solução não era apenas adicionar algumas regras em uma planilha.

A ferramenta precisava funcionar com o volume real da operação.

Ao mesmo tempo, escolhemos continuar utilizando Google Sheets e Apps Script porque havia uma vantagem importante nisso: Business Transformation já trabalhava nesse ambiente.

Uma solução tecnicamente mais sofisticada poderia significar construir e manter uma aplicação completamente nova.

Nesse momento, isso não era necessário.

O objetivo era melhorar o processo, não aumentar a quantidade de sistemas envolvidos nele.

---

Transformando erros técnicos em informação acionável

Detectar um erro não era suficiente.

Era necessário permitir que a pessoa que estava preparando a migração conseguisse entender e corrigir o problema sem depender de um developer.

Por isso, desenvolvi também uma interface lateral dentro da própria Google Sheet.

Quando a pré-validação encontrava problemas, essa interface apresentava informações como:

• linha;
• coluna;
• descrição do problema.

O utilizador podia clicar em um erro e ser levado diretamente para a linha correspondente.

A linha também era destacada visualmente.

O fluxo deixou de ser algo próximo de:

Algo deu errado
      ↓
Chamar Engenharia
      ↓
Developer investiga
      ↓
Developer explica
      ↓
Corrigir

e passou a se aproximar de:

Problema identificado
      ↓
Erro explicado
      ↓
Ir diretamente ao registro
      ↓
Corrigir
      ↓
Validar novamente

Essa mudança parece simples, mas teve um impacto importante.

A ferramenta não estava apenas validando dados.

Ela estava transformando conhecimento que antes dependia da Engenharia em feedback acionável para quem realmente operava o processo.

Somente depois de passar por essas pré-validações os dados eram enviados para a API existente.

A própria chamada para a API também passou a ser realizada através do Google Apps Script.

---

O problema também existia depois da API

Resolver os problemas de entrada era apenas metade do trabalho.

Depois que a API terminava suas validações, ainda existia a questão de interpretar os resultados.

Não havia uma API disponível para recuperar essas informações diretamente.

Os resultados podiam ser consultados através do Metabase.

Em vez de criar uma integração que não existia, trabalhamos dentro dessa restrição.

Criei uma segunda interface na Google Sheet onde Business Transformation podia importar o CSV de resultados obtido no Metabase.

A ferramenta associava esses resultados à execução original e processava os erros.

Isso fechava o ciclo dentro do ambiente que o time já utilizava:

Preparação dos dados
      ↓
Pré-validação
      ↓
Correções
      ↓
Envio para API
      ↓
Processamento
      ↓
Resultado do Metabase
      ↓
Importação
      ↓
Análise dos erros
      ↓
Novas correções

O processo continuava envolvendo diferentes sistemas, mas a complexidade dessa interação passou a ficar escondida atrás de uma experiência operacional mais simples.

---

Dashboards e acompanhamento da migração

Além dos erros individuais, precisávamos entender o comportamento do processo como um todo.

Cada execução passou a gerar também um registro resumido dentro da própria Google Sheet.

Essa área era protegida contra alterações manuais.

O objetivo era manter um histórico das execuções que permitisse acompanhar o processo e analisar a performance das validações.

Também criei dois níveis principais de visualização dos resultados.

Summary / Dashboard

A visão resumida permitia acompanhar informações como:

• clientes enviados;
• clientes que passaram;
• clientes com erros;
• distribuição dos erros por categoria;
• evolução das migrações.

Isso permitia olhar para o programa de forma mais ampla e entender onde os problemas estavam concentrados.

Error Report

A segunda visão era operacional.

Ela apresentava os clientes com problemas agrupados por categoria.

Em vez de analisar uma lista de respostas técnicas, Business Transformation conseguia identificar grupos de problemas semelhantes e trabalhar diretamente nas correções necessárias.

A diferença era importante.

Não queríamos apenas responder:

"A validação falhou."

Queríamos ajudar a responder:

"O que precisa ser corrigido para que esses clientes possam avançar?"

---

Resultados

O resultado mais importante não foi tornar a API mais rápida.

Ela continuou levando aproximadamente 15 minutos.

O ganho veio da redução do desperdício ao redor dela.

Antes do projeto, a operação conseguia migrar aproximadamente:

10–15 clientes por mês.

Depois das mudanças, passamos para aproximadamente:

15–30 clientes por semana.

Também houve uma mudança significativa na relação entre Business Transformation e Engenharia.

Antes, problemas nos dados geravam aproximadamente cinco interrupções por dia para o time de Engenharia.

Depois, Business Transformation passou a conseguir identificar e resolver grande parte desses problemas de forma independente.

Engenharia continuou necessária para casos mais complexos.

Mas, em vez de interrupções constantes ao longo do dia, esses casos passaram a ser tratados aproximadamente em uma sessão de uma hora por semana.

A melhoria veio principalmente de cinco pontos:

• maior qualidade dos inputs;
• feedback de erros mais claro;
• maior autonomia para Business Transformation;
• menos retrabalho;
• maior visibilidade sobre o processo.

O sistema central de validação permaneceu praticamente o mesmo.

O que mudou foi a eficiência do sistema humano e técnico construído ao redor dele.

---

O que aprendi com o projeto

Esse projeto mudou bastante a forma como penso sobre otimização.

Quando recebemos um problema descrito como "o processo está lento", existe uma tendência natural de procurar o componente tecnicamente mais lento.

Nesse caso, havia uma API que demorava aproximadamente 15 minutos.

Seria fácil assumir que o projeto deveria começar ali.

Mas analisar apenas o tempo de execução da API teria ignorado grande parte do problema.

O custo real estava espalhado pelo processo:

• tentativas que nem deveriam ter sido enviadas;
• erros que poderiam ter sido identificados antes;
• feedback difícil de interpretar;
• developers interrompidos constantemente;
• correções manuais;
• novas tentativas;
• pouca visibilidade sobre o estado das migrações.

Meu papel como Technical Program Manager foi conectar essas partes.

Eu propus a abordagem e desenvolvi diretamente os scripts e interfaces em Google Apps Script/JavaScript.

Mas a solução só foi possível porque o entendimento das regras e do processo foi construído em colaboração com Business Transformation, Data e outros developers.

As conversas com essas equipes foram essenciais para entender as regras, identificar onde estavam os gargalos e decidir quais problemas valia a pena resolver.

Talvez esse seja o principal aprendizado que levei desse projeto:

uma melhoria de engenharia não precisa necessariamente tornar uma API mais rápida.

Às vezes, o maior ganho está em compreender o sistema completo.

Neste caso, isso significou aproximar a validação da origem dos dados, transformar erros técnicos em informação acionável, criar observabilidade sobre o processo e permitir que quem operava a migração resolvesse grande parte dos problemas sem depender constantemente da Engenharia.

Começamos tentando entender por que uma migração era lenta.

Terminamos descobrindo que o verdadeiro gargalo não estava na migração em si.

Estava no processo ao redor dela.