Capítulo 03 / Quem é quem nos três ambientes

Ambientes

O SIMPE-MS opera em três ambientes distintos: o local na sua máquina, o de homologação na nuvem (simpe-ms-test) e o de produção (simpe-ms-dev). Saber qual é qual evita acidentes e ajuda a entender por que o gitflow é como é.

Local — sua máquina

Supabase Local

Docker

Stack inteiro rodando em containers no seu computador. Sem rede, sem dependência de internet, dados isolados de outros devs. É onde 95% do desenvolvimento acontece a partir de maio/2026.

http://localhost:3000 · banco em :54322 · Studio em :54323

Migrations criadas localmente entram primeiro no seu Postgres local via db:reset, são validadas, e só sobem para a nuvem quando o PR é aprovado. Cada branch pode ter seu próprio histórico de migrations sem brigar com o resto do time.

simpe-ms-test — homologação

simpe-ms-test

QA · Cloud

Ambiente de homologação na nuvem. Recebe o deploy automático de qualquer branch que não seja main — ou seja, todos os PRs e a branch dev.

Domínio: teste-ms.simpe.site
Project ref: (consulte o time)

Mudou em maio/2026: antes, os devs trabalhavam direto contra esse banco, escrevendo migrations diretamente nele. Hoje ele é apenas para QA — recebe migrations só quando uma feature está validada e mergeada em dev.

Se um QA / PO / colega abriu uma URL *.vercel.app ou teste-ms.simpe.site para testar, é esse banco que está atrás.

simpe-ms-dev — produção

simpe-ms-dev

Produção

Produção. Servindo a Secretaria de Saúde de verdade. Migrations só vão para cá depois de passarem pelo simpe-ms-test e o PR para main ser aprovado.

Domínio: ms.simpe.site

Regra absoluta

Nunca linke sua CLI a simpe-ms-dev. A promoção para produção é responsabilidade de quem aprova o merge em main. Se tiver dúvida sobre como fazer essa promoção, leia o capítulo Workflow.

Como a Vercel mapeia para os bancos

Os deploys do frontend ficam na Vercel. Cada branch git é configurada com variáveis de ambiente diferentes:

Branch git Vercel deploy Variáveis apontam para
main ms.simpe.site simpe-ms-dev (prod)
dev e qualquer outra teste-ms.simpe.site ou preview *.vercel.app simpe-ms-test (QA)

Ou seja: o que define qual banco a Vercel usa é a branch — não existe controle manual disso. Por isso a regra de "main = prod, qualquer outra = test" é tão importante.

O .env

Para o seu desenvolvimento local, o .env aponta exclusivamente para o Supabase local. Em algum momento o .env.example pode ter um bloco comentado para apontar contra o cloud (simpe-ms-test) caso você não consiga rodar Docker — mas a partir de maio/2026 esse caminho é exceção, não regra. O caminho padrão é local.

Variáveis

VariávelDescrição
NEXT_PUBLIC_SUPABASE_URL URL da API. Local: http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY Chave pública (publishable). Usada nos clients server e browser. Respeita RLS.
SUPABASE_SERVICE_ROLE_KEY Chave de service role. Usada apenas em leituras de cache no admin client (bypassa RLS). Nunca expor no browser.
NEXT_PUBLIC_AMBIENTE_DE_TESTE Quando "true", habilita features que só existem fora da produção (banner, feedbacks, etc.). Em produção (main), essa variável não é definida.
Detalhe das chaves locais

CLI 2.90+ gera chaves randomizadas por instância (sb_publishable_*, sb_secret_*). Toda vez que você roda supabase stop --no-backup e supabase start de novo, elas mudam. Por isso copiamos manualmente do supabase status em vez de embedar valores fixos.

Os três clients do Supabase

Independente do ambiente, o código do projeto usa três clients diferentes do Supabase — e a escolha é crítica:

ClientArquivoPara o quê
Admin utils/supabase/admin.ts Apenas leitura de tabelas de cache (bypassa RLS, é mais rápido)
Server utils/supabase/server.ts Mutations — respeita RLS e a sessão do usuário
Browser utils/supabase/client.ts Client-side (raro)

Nunca use o admin para mutations. Nunca use o server para leituras de cache (RLS deixa lento). Mais detalhes na seção "Architecture" do CLAUDE.md.