Pular para o conteúdo principal

Multi-Tenancy e Países

Princípio fundamental​

Zero código de país no override da marca. O core detecta o país via configuração e retorna o comportamento correto automaticamente.

Como funciona​

Cada ambiente de marca define apenas variáveis de ambiente no worker (front-ops/config/brands/<repo>/environments/<env>/deploy.yml):

BRAND_COUNTRY=BRA           # Código do país ISO 3166 alpha-3
BRAND_LANGUAGE=pt-br        # Idioma padrão
BRAND_CURRENCY=BRL          # Moeda
BRAND_TIMEZONE=America/Sao_Paulo   # server-only, NÃO faz parte do ClientEnv

BRAND_COUNTRY é alpha-3 (BRA, CHL, MEX, PER, NGA) — o loader do _layout faz getCountryByAlpha3(clientEnv.BRAND_COUNTRY.toUpperCase()).

Os pacotes @cactus-agents/* usam essas variáveis para resolver:

PacoteResolução por país
@cactus-agents/paymentsProviders de pagamento (PIX para BR, SPEI para MX)
@cactus-agents/kycDocumentos exigidos (CPF para BR, CURP para MX)
@cactus-agents/validationsValidators (formato CPF, formato CURP, etc.)
@cactus-agents/brandselectByCountry() filtra dados multi-país da API

selectByCountry​

A função selectByCountry(items, country) do @cactus-agents/brand segue a chain:

  1. Exact match — item com country.code === BRAND_COUNTRY
  2. Default — item com is_default === 1
  3. Fallback — primeiro item do array

Isso permite que a API retorne dados para múltiplos países e o SDK selecione automaticamente.

Sem repo por país — e sem repo por marca​

Errado: front-web-base-mex, front-web-base-bra

Certo: Um único front-web-base. Países são resolvidos no core via env vars.

O mesmo vale pra marca: uma marca é um diretório overrides/<brand-key>/ dentro do front-web-base, resolvido em build time pelo brandOverridesPlugin a partir do ORIGIN_DOMAIN do worker. Não há repo por marca.

Exemplo real dos dois eixos operando juntos: cl-bet7k-com é o override de marca e o ambiente correspondente roda com BRAND_COUNTRY=CHL. Se essa marca precisasse operar em outro país, o que mudaria seriam as env vars do ambiente — nenhum código.

:::info Marca × país × trunk São três eixos independentes. O terceiro (trunk — qual branch de longa duração serve o ambiente) está documentado em Trunks de marca. :::

Dados multi-país na API​

A API retorna arrays com items por país em vários endpoints. Exemplos:

  • features.contacts — contatos (SAC, suporte) por país
  • features.validation_modules — regras de validação por módulo e país
  • settings — limites de depósito/saque por país

O @cactus-agents/brand usa selectByCountry para filtrar na transformação.