Manual de Desenvolvimento, Volume 01
Atualizado em 05/05/2026

SIMPE&MS

Guia editorial de instalação e desenvolvimento local. Para colegas que vão construir, consertar e melhorar o sistema integrado de monitoramento estratégico da Secretaria de Saúde.

OSIMPE-MS é o sistema que substituiu o antigo SAGA-SUS — uma migração de Firebase (NoSQL) para Supabase (PostgreSQL), com um frontend Next.js totalmente novo. Ele organiza o plano estratégico da SES-MS em uma hierarquia de objetivos, ações, resultados, entregas e atividades, com monitoramento por semáforo, métricas, compromissos, matriz de responsabilidade e relatórios.

Em maio/2026, o desenvolvimento ficou local-first: cada dev tem seu próprio Postgres rodando em Docker, com migrations isoladas por branch. Acabou a disputa pelo banco de testes compartilhado, e features paralelas finalmente conseguem ir para produção independentemente.

Este manual existe para que esse novo fluxo seja claro, reproduzível, e — quando possível — agradável de seguir.

A stack

Next.js 16 React 19 Supabase PostgreSQL 17 Tailwind 4 Radix · shadcn TanStack Virtual dnd-kit Vitest 4 Deno (edge)

Apêndice / Anatomia de um dia normal

Um dia com o Dev Matheus

Não é receita de bolo — é só como, na prática, eu abro a máquina, escrevo código e fecho o dia sem deixar nada queimando RAM. Use como referência ou como ponto de partida para criar o seu próprio ritmo.

  1. Abrir o VSCode no projeto

    Eu rodo no WSL2 Ubuntu, mas isso é detalhe — funciona igual no macOS ou no Windows nativo. O importante é abrir a pasta simpe-ms direto, não o workspace pai.

  2. Subir o Docker Desktop

    Antes de qualquer coisa, o Docker precisa estar de pé — é ele que vai segurar o Postgres, o Studio e o resto do stack do Supabase local.

  3. Abrir três terminais no VSCode

    Cada um com um propósito, para não embolar saída de log:

    • Supabase — supabase start, migrations, reset.
    • Next.js — o npm run dev rodando ininterrupto.
    • Externo — git, troca de branch, comandos avulsos.

  4. Abrir um terminal fora do VSCode — o Claude Code

    Em uma janela separada eu digito claude e deixo aberto o dia inteiro. Manter fora do VSCode evita que o painel do editor vire um caos de abas.

  5. Subir o Supabase local

    supabase start

  6. Subir o Next

    npm run dev

    Pronto. Agora é só pular pra branch da task e começar a editar.

  7. No Claude, três comandos que uso o tempo todo

    • /mcp — confiro se o MCP do Supabase local conectou. Se não, nada de query inteligente.
    • /usage — nunca passo dos 20% dos 200K de contexto. Se chega lá, paro a sessão e abro outra do zero. Contexto sujo gera resposta suja.
    • shift+tab — alterna pro plan mode, antes de pedir mudanças que envolvam várias etapas.

  8. Migrations, se a task encostar no schema

    # cria o arquivo de migration na branch atual
supabase migration new nome-descritivo

# aplica em cima (sem destruir dados)
supabase migration up

# ou: rebobina tudo, replay do zero + seed
supabase db reset

    up quando quero adicionar; db reset quando alterei algo já aplicado e preciso garantir que a migration roda limpa do começo.

  9. Edge functions, se mexi em alguma

    supabase functions serve

    Roda em modo watch — testo a função batendo nela direto enquanto edito.

  10. Tudo verde? Commit, push, PR para dev

    Mensagens de commit no padrão do repo, PR descrevendo o que muda e por quê, screenshots se for visual. Daí é com o revisor (veja o quadro abaixo).

  11. Antes de fechar o laptop — nunca esquecer

    supabase stop

    Se eu esquecer, o stack continua mastigando RAM em segundo plano e amanhã o ventilador me xinga. Vira hábito rápido.

Do outro lado: quem aprova o PR

Code review aqui não é só ler diff — é rodar de fato. Migration que parece inocente quebra na hora de aplicar em outro banco.

Etapa 01 · Validar local

Rodar a branch do PR

Faz checkout, sobe tudo do zero, garante que a feature anda na máquina dele exatamente como prometido: 

supabase start
npm run dev
supabase db reset

O db reset aqui faz todo o sentido: rebobina o banco e replay das migrations — é o teste real de que a migration nova roda limpa.

Etapa 02 · Promover para teste

Aprovou? Mergeia em dev

Logo depois, aplica as mudanças no projeto cloud de QA (simpe-ms-test): 

# aponta o CLI pro projeto de teste
supabase link # — escolher simpe-ms-test

# envia migrations
supabase db push

# publica edge functions alteradas
supabase functions deploy nome-da-funcao --no-verify-jwt
Etapa 03 · Produção

QA validou? PR de dev → main

Depois do merge em main, refaz o mesmo ritual — mas agora com supabase link apontado pro projeto simpe-ms-dev (que apesar do nome, é a produção). db push + functions deploy e a feature está no ar.

Comece pelo capítulo 01 — ou pule direto para o que precisar.