Países, estados, cidades

Todo endereço no GCM — endereço residencial de membro, local de reunião de grupo, sede de ministério, campus de escola — escolhe de três dropdowns em cascata: País → Estado / Província → Cidade. Os valores vêm de três tabelas de referência (countries, states, cities) e as listas são gerenciadas pela plataforma, então você verá as mesmas opções seja uma plantação de 50 membros em Belize ou uma rede de 5.000 membros no Brasil.

Esse artigo percorre onde aparecem, como a cascata funciona, o que está pré-carregado, e o que admins de plataforma fazem nos bastidores.

Onde geografia aparece

Os dropdowns de país / estado / cidade aparecem em:

• Perfil do membro — campos de endereço residencial.
• Perfil de grupo / ministério — sede da reunião.
• Campus de escola — local físico.
• Formulário de visitante — campo público "de onde você é?".
• Configurações da org — o próprio endereço da igreja.
• Módulo de mapa — endereços são geocodificados e fixados, depois agrupados por cidade / estado.

Cada tabela contém o nome legível por humano mais um código ISO para que a edge function de geocodificação e análises a jusante falem em um padrão.

A cascata

As três tabelas são ligadas por chaves estrangeiras:

countries  ← states (country_id)  ← cities (state_id, country_id)

Na UI, escolher um país restringe o dropdown de estado a estados nesse país, e escolher um estado restringe o dropdown de cidade. Escolha Jamaica e o dropdown de estado mostra as 14 paróquias; escolha Saint Andrew e o dropdown de cidade mostra Kingston, Half Way Tree, etc.

Se seu país usa províncias em vez de estados ou departamentos em vez de províncias, a coluna para esse nível é a mesma — a tabela de referência da plataforma armazena admin_level_label por país para que a UI possa renderizar "Província" no Canadá e "Estado" nos Estados Unidos sem uma mudança de código.

Por que isso é gerenciado pela plataforma

Três razões:

1. Consistência de geocodificação. O módulo de mapa do GCM chama um serviço de geocodificação (Nominatim por padrão, opcionalmente Google ou Mapbox). O serviço espera nomes canônicos de país e estado — se a igreja A escreve Saint Andrew e a igreja B escreve St Andrew, o geocodificador devolve duas lat/lon diferentes e o mapa parece quebrado.
2. Estatísticas cross-tenant. Análises da plataforma rolam contagens de membros por país e estado. Texto livre tornaria esses totais sem sentido.
3. i18n. Cada país tem traduções para inglês, espanhol, português, francês — possuir a lista deixa a plataforma manter essas traduções limpas.

Você não verá países / estados / cidades na página de Dados de Referência no nível org. Eles vivem atrás de Admin de Plataforma → Geografia, acessado apenas por equipe do GCM.

O que está pré-carregado

No momento do seed, a plataforma carrega:

• Cada país — todos os 195 países mais territórios dependentes, com códigos ISO 3166-1 alpha-2, códigos de discagem, e emojis de bandeira.
• Estados / províncias / regiões — para cada país, as divisões administrativas de nível superior.
• Cidades — uma lista inicial das 30-50 maiores cidades por país.

Se seu dropdown de endereço está faltando uma cidade — particularmente comum para cidades pequenas ou áreas recentemente incorporadas — o caminho é pedir uma adição via suporte, ou ter um admin de plataforma adicionar diretamente pela aba de geografia (veja Adicionando estados ou cidades abaixo).

Adicionando estados ou cidades

Esse é trabalho de admin de plataforma mas vale a pena saber como acontece para você poder pedir adições eficientemente.

O admin de plataforma abre Admin de Plataforma → Geografia e vê uma cascata de três painéis: Países à esquerda, Estados no meio, Cidades à direita. Clicar num país carrega seus estados; clicar num estado carrega suas cidades.

Para uma ou duas adições, eles clicam no botão + ao lado do cabeçalho do painel, preenchem o nome (e código ISO para estados), salvam.

Importação CSV em massa

Para um novo país distribuindo uma lista grande — digamos, todos os 50 estados americanos ou 200 municípios brasileiros — há uma importação CSV em massa.

1. Selecione o país (para estados) ou estado (para cidades) à esquerda.
2. Clique em Upload no cabeçalho do painel.
3. Cole linhas no textarea de importação, uma por linha:
   • Estados: name,iso_code (o código ISO padrão é as primeiras 3 letras do nome se omitido)
   • Cidades: name
4. Linhas começando com # são ignoradas. Linhas em branco são ignoradas.
5. Clique em Importar.

Nos bastidores, faz um único round-trip INSERT; o índice único da tabela significa que reimportar a mesma lista é um no-op para linhas que já existem. Uma importação típica de 50 estados americanos é abaixo de um segundo.

Exemplo de importação de estados para os Estados Unidos:

# US states — full list
Alabama,AL
Alaska,AK
Arizona,AZ
# ...

Como o admin de org deve tratar uma cidade faltando

Você não tem acesso de edição, mas aqui está o workflow:

1. O membro adiciona a cidade como sobreposição em texto livre. O perfil do membro tem um campo de fallback "Cidade (texto livre)" que é usado quando o dropdown não cobre. O geocodificador ainda funciona porque volta para a cidade em texto livre.
2. Você envia e-mail ao suporte com o país, estado, e nome da cidade para adicionar.
3. Equipe de plataforma adiciona em alguns dias úteis, o dropdown a pega automaticamente, e da próxima vez que o membro é editado o registro dele pode ser movido do fallback em texto livre para a cidade canônica.

A lat/lon geocodificada do membro sobrevive ao movimento porque está armazenada diretamente na linha do membro, não na cidade.

Campos de país além do nome

Cada linha de país tem mais que apenas um nome:

Coluna	Exemplo	Usado para
iso_code	JM	Geocodificação, validação de telefone, integrações
iso_numeric	388	Bancário, roteamento BIC
dial_code	+1	Prefixo automático do campo de telefone no formulário de visitante
flag_emoji	🇯🇲	Decoração visual em dropdowns
admin_level_label	Parish	Como chamar a divisão de segundo nível na UI

Você verá o emoji de bandeira no dropdown de país e o código de discagem pré-preenchido em inputs de telefone — é aí que esses campos extras aparecem para o usuário final.

Traduções

Países, estados, e cidades todos suportam a coluna translations JSONB. A plataforma pré-preenche inglês; traduções para espanhol e português são carregadas para os 30+ maiores países. Se uma tradução está faltando, a UI volta para o nome em inglês. Veja Rótulos multilíngues.

Próximo

• Rótulos multilíngues — como nomes de país / estado / cidade são renderizados por locale.
• Personalizar tipos de membros — de volta às listas que você possui totalmente.