Pular para o conteúdo principal

Status: Approved · v3 · SPEC-ARCH-ENV-001

depends_on: SPEC-ARCH-MONOREPO-001, SPEC-ARCH-SECURITY-001, SPEC-ARCH-CONTAINER-001

used_by: IS-ZERO-00.4, IS-ZERO-00.5, IS-MVP-18.1, IS-MVP-18.2

Ambientes e deployment

Ambientes são promovidos por PR entre branches protegidas e mantêm URLs, variáveis, dados e credenciais separados.

Modelo canônico de branches​

BranchPapelEntrada permitidaWeb VercelAPI
developintegração contínua e teste manual inicialPR de feature/fixPreview branch com URL estável e env própriosserviço/container de desenvolvimento
homolhomologação da release candidataPR a partir de develop; exceção documentada para hotfixPreview branch com URL estável e env própriosserviço/container de homologação
masterproduçãoPR a partir de homol; exceção documentada para hotfixProduction Branch e domínio públicoserviço/container de produção

Push direto, force push e deleção ficam bloqueados nas três branches. O administrador pode intervir somente por bypass consciente e auditável quando a plataforma/plan permitir; intervenção manual não transforma gate vermelho em release aprovada.

Promoção​

feature/* ou fix/* → PR develop → PR homol → PR master

Cada promoção usa o mesmo commit ou histórico rastreável. Rebuild pode ocorrer por ambiente, mas não há alteração manual de código entre os estágios. Rollback aponta para deployment/artefato previamente aprovado e registra o SHA.

Web na Vercel com custo zero​

O baseline usa um projeto Vercel Hobby conectado ao monorepo:

  • Root Directory apps/web, com acesso aos packages/workspaces necessários;
  • Production Branch master;
  • develop e homol como Preview branches, cada uma com domínio/alias estável e variáveis de Preview específicas da branch;
  • demais PRs recebem URL efêmera de preview quando o orçamento de build permitir;
  • Vercel Custom Environments não é requisito, pois exige plano Pro/Enterprise; se futuramente disponível, homol pode migrar sem mudar o contrato lógico.

Vercel constrói o web a partir do Git/monorepo. A imagem Docker do web serve integração e portabilidade, não é o artefato enviado à Vercel.

API containerizada​

A API não é acoplada à Vercel. O pipeline produz uma imagem imutável por SHA e aciona o provider configurado apenas quando services/api ou dependências transitivas forem afetados.

Para testes sem custo, Render Free é um target inicial permitido para develop/homol e, apenas durante validação sem usuários reais, para master. Devem ficar visíveis no runbook: cold start após inatividade, filesystem efêmero, limite compartilhado de horas, ausência de SLA e inadequação a produção real. A troca de provider não altera o pipeline de qualidade nem a imagem.

Cada branch usa serviço, URL, CORS e secrets separados. Até existir persistência real, reinício/deploy apaga o estado em memória; testes manuais não podem tratar dados como duráveis.

Mobile​

O mobile participa de gates seletivos e build/export quando apps/mobile ou dependências forem afetados, mas não faz deploy na Vercel. Releases automáticas em Google Play e Apple App Store ficam em IS-POST-13.1, após definição de EAS, assinatura, tracks, revisão e secrets das lojas.

Variáveis e isolamento​

Públicas por cliente​

NEXT_PUBLIC_USE_MOCKS, NEXT_PUBLIC_MOCK_SCENARIO, NEXT_PUBLIC_API_BASE_URL e EXPO_PUBLIC_* são configuradas por ambiente e podem ser bundled. Nunca recebem segredo.

Server-only​

JWT, banco, storage, Pix/webhook, tokens Vercel/Render, signing e job flags existem apenas no secret store do ambiente/CI. Secrets de develop, homol e master não são reutilizados, salvo credencial explicitamente compartilhável e documentada.

Política de mocks​

  • develop: mocks permitidos apenas quando o cenário de teste pedir; integração API deve estar disponível.
  • homol: mocks desabilitados; providers externos podem usar sandbox/fake canônico.
  • master: mocks proibidos pelo production guard.

Domínios-alvo​

  • produção web: raizfc.com.br;
  • homologação web: homol.raizfc.com.br ou alias Vercel equivalente;
  • desenvolvimento web: develop.raizfc.com.br ou alias Vercel equivalente;
  • produção API: api.raizfc.com.br quando houver hosting produtivo aprovado;
  • homologação API: api-homol.raizfc.com.br ou URL do provider;
  • desenvolvimento API: api-develop.raizfc.com.br ou URL do provider.

Gates e pós-deploy​

Deploy só inicia após o workflow de qualidade global concluir com sucesso. Cada alvo executado realiza smoke próprio; falha impede promoção e deve permitir rollback. Web verifica rotas P0 e integração com a API do mesmo ambiente; API verifica health, CORS e versão/SHA.

Critérios de aceite​

  • develop, homol e master aceitam mudanças somente via PR e checks obrigatórios.
  • Vercel associa master a Production e develop/homol a previews isolados por domínio e env.
  • Web de cada ambiente aponta somente para a API correspondente.
  • API é publicada por imagem SHA somente quando afetada e passa health/smoke.
  • Mobile é validado seletivamente sem tentativa de deploy Vercel.
  • Production falha se USE_MOCKS=true; secrets nunca são bundled/logados.
  • Runbooks cobrem configuração manual GitHub/Vercel/Render, promoção, rollback e limites dos free tiers.
  • Falta de recurso gratuito bloqueia deploy daquele alvo sem enfraquecer gates ou misturar ambientes.

Histórico​

  • 3.0 — branches protegidas develop/homol/master, Vercel Hobby branch-based, API containerizada e mobile diferido para stores.
  • 2.0 — modelo inicial local/preview/staging/produção.