Capítulo 05 de 35

O Ciclo de Vida do Código: Ambientes Permanentes de Homologação e Sandbox

Índice do Manual

Em sistemas de software sob medida de missão crítica (B2B SaaS), qualquer erro implantado no ambiente oficial pode corromper os dados dos clientes e destruir a confiança na ferramenta.

Você nunca, em hipótese alguma, terá dores de cabeça com a infraestrutura se seguir este Padrão Ouro de separação de ambientes arquiteturais utilizando Supabase, Vercel e Git.

1. Separação Estrita de Ambientes

No Passo 1 do Setup Inicial, nós criamos dois projetos separados no painel da Supabase e configuramos as chaves duplas na Vercel. Esse é o motivo: toda arquitetura corporativa moderna deve iniciar com pólos espelhados e independentes.

Separação no Backend (Supabase)

Criamos dois projetos (bancos de dados isolados) separados logicamente e geograficamente:

  • Projeto STAGING (sistema-staging): Usado para testes, injeção de dados fictícios, onde você trabalha no dia a dia e onde o cliente fará a homologação visual.
  • Projeto PROD (sistema-prod): O ambiente real e intocável, usado pelos usuários finais.

As senhas e chaves de acesso são criptograficamente separadas. É fisicamente impossível um dado de teste vazar para o sistema oficial.

Separação no Frontend (Vercel)

A Vercel possui suporte nativo impecável para espelhar esse fluxo (graças às chaves duplas de Production e Preview que nós cadastramos no Passo 1 do Setup Inicial):

  • Produção (Oficial): Sempre que código testado é mesclado (Merged) para a branch principal (main) no GitHub, a Vercel atualiza o link oficial (ex: app.empresa.com.br) conectado com o banco sistema-prod.
  • Preview (Homologação): Quando o desenvolvimento ocorre em uma branch paralela (ex: staging), a Vercel gera um link temporário (ex: staging.empresa.com.br) conectado ao banco sistema-staging.

2. O Fluxo de Desenvolvimento Diário (Git Flow)

Uma dúvida clássica na hora de construir um sistema corporativo é: "Como eu codifico a primeira versão e as próximas atualizações sem transformar o repositório numa bagunça perigosa?"

A resposta é que, a partir do Dia 1, você nunca programa diretamente na main nem na staging. A branch main é sagrada (reflete o que o usuário final vê), e a branch staging é a sua URL oficial de testes para o cliente validar.

Para organizar essa orquestração segura entre Produção e Sandbox, o padrão da indústria baseia-se na diferenciação clara das Branches (ramificações do código):

As Branches Permanentes (Ambientes)

Estas duas branches nunca são apagadas. Elas ficam ativas 24 horas por dia:

  • main (Produção): É o código oficial dos clientes (app.empresa.com.br). Só recebe código impecável e extensamente testado.
  • staging (Homologação / Sandbox): É a cópia exata do sistema (staging.empresa.com.br) usada para treinamentos, demonstrações e aprovação final pelo Product Owner ou Dono da Empresa antes da funcionalidade ir ao ar.

A Branch de Feature (A Tarefa Temporária)

Desenvolvedores seniores nunca escrevem código diretamente na main ou na staging. Quando uma nova funcionalidade é solicitada (ex: "Crie uma tela de Relatório de Vendas"), cria-se uma branch temporária exclusiva para essa tarefa.

O ciclo de vida prático (Passo a Passo com Comandos):

Passo 1: Criando a Branch Temporária Antes de iniciar, o desenvolvedor atualiza sua base e cria a ramificação local isolada:

# Muda para a branch de produção e atualiza o código oficial mais recente
git checkout main
git pull origin main

# Cria a nova branch temporária baseada na main (código limpo)
git checkout -b feature/relatorio-vendas

Passo 2: Programação e Commit O código é desenvolvido, quebrado, consertado e testado. Ao finalizar, as alterações são seladas:

# Adiciona todos os arquivos modificados
git add .

# Salva na história com uma mensagem descritiva clara
git commit -m "feat: adiciona nova tela de relatorio de vendas"

Passo 3: Enviando para a Nuvem e Pull Request A branch é enviada (Push) para o repositório remoto:

git push origin feature/relatorio-vendas

No painel web do GitHub:

  • Aparecerá um alerta amarelo e um botão verde "Compare & pull request". Clique nele.
  • Selecione a base branch como staging e a compare branch como feature/relatorio-vendas.
  • Clique em "Create pull request".

Passo 4: A Regra de Ouro da Homologação (Quem testa o quê?) Neste exato momento em que o PR foi aberto, o código ainda não está na Staging. Ele está numa "fila de espera" no GitHub pedindo autorização (Merge). A Vercel, por sua vez, atua como um "robô espião" que assiste o seu GitHub 24 horas por dia. Ao ver o seu pedido, ela cria automaticamente um simulador seguro:

  • Teste Técnico (O link de Preview temporário): A Vercel injeta um comentário no Pull Request com uma URL descartável (ex: empresa-feature-relatorio.vercel.app). Use este link para os seus próprios testes rápidos ou se tiver um QA terceirizado. Se houver um erro fatal no código, ele quebra apenas esse link descartável, mantendo a Staging oficial ilesa.
  • Teste do Cliente Final (A URL fixa da staging): Se o código no link de Preview funcionou perfeitamente, agora sim você clica no botão verde gigantesco "Merge pull request" (que fica 100% dentro do painel do GitHub). A Vercel detecta esse clique e injeta o código de vez na branch staging. Finalmente, avise o cliente para acessar a URL fixa de homologação (staging.empresa.com.br). Clientes detestam receber links temporários diferentes a cada atualização. Acostume-os a validar na mesma URL fixa.

Passo 5: O Go-Live (Merge Final para a Produção) Uma vez que o novo relatório roda perfeitamente na Homologação (staging.empresa.com.br), é hora de despachá-lo aos clientes finais. Atenção Suprema: Você NUNCA mescla a branch staging inteira para a main! Se houvesse outras features em testes na staging que ainda não foram aprovadas, elas iriam para Produção por acidente. O Go-Live seguro é feito mesclando a sua branch isolada direto na oficial:

  • No painel do GitHub, vá em Pull Requests e clique em "New pull request".
  • Selecione a base branch como main e a compare branch como feature/relatorio-vendas (a sua branch original).
  • Clique em "Merge pull request". A Produção é atualizada imediatamente sem tirar o sistema do ar.

Limpeza Automática: A Morte da Branch Temporária

A branch feature/relatorio-vendas cumpriu sua missão. Para manter o repositório organizado corporativamente, ela deve ser deletada para não gerar lixo.

O padrão arquitetural é automatizar esse descarte diretamente no repositório remoto:

  1. Acesse as Configurações (Settings) do repositório no GitHub.
  2. Na aba Pull Requests, ative a opção: ✅ "Automatically delete head branches".

Com isso, no exato segundo em que o botão "Merge Pull Request" for clicado e o código da feature entrar na branch alvo com sucesso, o servidor destruirá a ramificação temporária automaticamente, mantendo a estrutura 100% enxuta.

(Nota: Para espelhar essa limpeza no ambiente local do desenvolvedor, executa-se o comando manual git branch -d feature/relatorio-vendas).

(Nota de Agilidade Solo: Para funcionalidades médias e grandes, usar o fluxo oficial completo com Pull Requests do GitHub ensinado acima é o padrão ouro. Veja abaixo a exceção tática de agilidade para tarefas minúsculas).

A Exceção de Trivialidades (Hotfix Rápido)

Se o cliente pediu uma alteração minúscula (ex: "Mudar a cor de um botão" ou "Corrigir erro de digitação"), a burocracia visual do GitHub (Pull Requests) não é necessária. Como Desenvolvedor Solo, você ganha agilidade tática fazendo o Merge Local direto no terminal:

# 1. Cria a branch rápida da base
git checkout main
git pull origin main
git checkout -b fix/cor-botao

# (Faça a mudança no código e salve)
git add .
git commit -m "fix: altera cor do botao"

# 2. Envia para a Staging para o cliente olhar (Merge Local)
git checkout staging
git merge fix/cor-botao
git push origin staging

# 3. Cliente aprovou na Staging? Manda pra Produção (Merge Local)
git checkout main
git merge fix/cor-botao
git push origin main

# 4. Limpeza (Volte para a base e apague o rastro)
git checkout staging
git branch -d fix/cor-botao

3. O Bônus da Arquitetura: Sandbox de Treinamento Permanente

Para aplicações SaaS B2B, manter a staging permanentemente ativa (a abordagem imortal ensinada acima) gera um benefício comercial massivo no longo prazo.

A URL de testes (staging.empresa.com.br) e o Banco de Testes correspondente nunca deixam de existir. Eles funcionam como uma pista de testes vitalícia para a empresa cliente.

Ao preservar esse ambiente Sandbox (completamente desvinculado dos dados financeiros e reais), você resolve o problema de Onboarding do seu cliente corporativo. Quando o cliente contratar um novo funcionário para operar o SaaS, você o instrui a usar exclusivamente o ambiente staging. Ele pode disparar alertas, cadastrar clientes errados, excluir campanhas e aprender todas as engrenagens da plataforma — sem qualquer risco para a operação oficial.

Esta infraestrutura concede paz de espírito total para você (que desenvolve isolado) e entrega para o cliente um simulador gratuito de voo.

O Próximo Passo: E o Banco de Dados?

Até agora, você dominou como orquestrar o código (Frontend e Backend) com segurança de um ambiente para outro usando o Git Flow.

Mas se você criar uma tabela de "Relatório de Vendas" no banco da sua máquina local, como você garante que essa tabela também seja criada no banco da staging e, posteriormente, no banco de Produção, sem precisar entrar no painel e recriar tudo manualmente correndo o risco de esquecer uma coluna?

É exatamente aqui que a infraestrutura se eleva ao nível máximo com as Migrations. Siga para o próximo capítulo para aprender como versionar o banco de dados e aplicar o esquema do "Go-Live Automático" com o Supabase CLI.

Capítulo AnteriorO Ciclo de Vida do Código: Local, Staging e ProduçãoPróximo Capítulo Migrations e Versionamento de Banco (Supabase CLI)