Dados mestres de Geografia

Público

Este artigo é para operadores da plataforma GCM. Administradores de igreja devem ver o artigo Adicionar um membro para usar os dropdowns de país / estado / cidade — esta página é para a equipe que mantém as listas subjacentes.

Todo campo de endereço na plataforma — perfis de membros, configurações de organização, o formulário público de doação, o formulário de visitante — puxa de três tabelas mestras: countries, states, cities. Elas são em toda a plataforma, não por organização, e é por isso que essa superfície vive no Administrador de plataforma. A aba Geografia (/platform/geography) é o console CRUD para essas tabelas, com um layout em cascata de três painéis e import em massa por CSV para os casos de cauda longa.

O layout de três painéis

A página é dividida em três cartões lado a lado. Cada painel só habilita quando seu pai é selecionado:

1. Países — a lista mestra. Sempre visível.
2. Estados — preenche quando um país é selecionado. O título do cartão se adapta para usar o admin_level_label do país ("Províncias" para o Canadá, "Departamentos" para a Colômbia, "Estados" para os EUA, etc.).
3. Cidades — preenche quando um estado é selecionado.

A seleção persiste por painel: escolher um novo país reseta as seleções de estado e cidade; escolher um novo estado reseta só a cidade.

Cada painel tem sua própria caixa de busca que faz um includes no lado do cliente contra os nomes visíveis.

Editando um país

Clique em Adicionar no topo do painel Países — ou no ícone de lápis em qualquer linha — para abrir o formulário do país. Os campos são:

• Nome (obrigatório) — o nome de exibição, por exemplo "Colombia".
• Código ISO (obrigatório, 2 caracteres) — o código ISO 3166-1 alpha-2, por exemplo CO. Convertido automaticamente em maiúsculas.
• ISO Numérico — o código numérico ISO 3166-1 (3 dígitos), por exemplo 170. Usado por algumas integrações.
• Rótulo de Estado / Província — como seu país chama sua subdivisão de primeiro nível. "Department", "Province", "Region", "Canton", "Prefecture". Dirige o título e o texto placeholder do seletor de estado a jusante.
• Código de discagem — o prefixo internacional de discagem, por exemplo +57. Usado pelo formatador de número de telefone.
• Emoji da bandeira — bandeira Unicode colada, por exemplo 🇨🇴. Mostrada ao lado do nome do país em todo lugar.

Salvar insere uma linha em countries se você estava adicionando, ou atualiza no lugar se você estava editando. A lista em cache é invalidada para que o novo valor apareça em cada dropdown de endereço no próximo render.

Excluir um país abre uma confirmação destrutiva. O alerta é honesto sobre o cascade: excluir Colômbia também exclui cada estado e cidade abaixo. Se qualquer membro ou visitante se refere a esse país por id, você terá violação de FK — limpe esses primeiro ou mude o comportamento de cascade em uma migração, não a partir desta UI.

Editando um estado

Estados têm dois campos:

• Nome (obrigatório) — nome de exibição.
• Código ISO — o código de subdivisão ISO 3166-2, por exemplo US-CA. Opcional, mas recomendado. Convertido automaticamente em maiúsculas.

O mesmo formulário de adição única, a mesma confirmação destrutiva de exclusão. O id do país é definido automaticamente a partir da seleção.

Editando uma cidade

Cidades têm um campo: Nome. Não há códigos; cidades são apenas rótulos associados a um estado e (desnormalizado para velocidade de consulta) a um país.

Import CSV em massa

O formulário de adição única é bom para uma entrada ausente. Para semear o que vale um país inteiro de estados (ou um estado inteiro de cidades), use Importar no topo do painel de estados ou cidades.

O diálogo de import aceita texto puro, uma linha por registro:

• Para estados: name,iso_code. O código ISO é opcional; se em branco, as 3 primeiras letras do nome são convertidas em maiúsculas. Exemplo:

  California,CA
  Texas,TX
  Florida,FL

• Para cidades: apenas name.

Linhas em branco ou que começam com # são puladas, então você pode colar listas com linhas comentadas.

O diálogo mostra uma contagem em execução de linhas válidas analisadas abaixo da textarea, para que você possa fazer uma checagem de sanidade antes de apertar Importar. Todas as linhas são inseridas em uma única ida e volta INSERT; o índice único em (country_id, name) (para estados) ou (state_id, name) (para cidades) significa que reimportar a mesma lista lança um erro no primeiro duplicado. O padrão certo é: cole só as linhas ausentes, não a lista inteira.

Fontes de dados

Para novos países, os dados canônicos de semeadura são o admin1CodesASCII.txt do GeoNames (estados) e a fatia cities500.txt do país. Reduza-os às colunas acima com awk e cole-os.

Situações comuns

"O formulário de membro não mostra 'Cundinamarca' como departamento na Colômbia." Selecione Colômbia no painel Países, busque por "Cundi" em Estados. Se faltar, Adicione-o com ISO CO-CUN. O dropdown atualiza em todo lugar imediatamente — consultas em cache são invalidadas ao salvar.

"Preciso adicionar 47 cidades ausentes a um estado." Selecione o país, depois o estado, depois clique em Importar no painel Cidades. Cole a lista, uma por linha. Aperte Importar. O diálogo informa a contagem que inseriu; se alguma falhou (geralmente duplicadas), o toast diz.

"Um cliente nos pediu para renomear o país dele de 'United States' para 'US' por brevidade." Não faça. O nome do país é global — todo outro cliente vê também. Se precisa localizar, o canal certo é os arquivos de tradução por locale (src/i18n/locales/{en,es}.json) para as strings de exibição, com o iso_code mantendo o dado estável.

O que essa superfície não faz

• Não geocoda. O módulo map usa Mapbox / Nominatim no momento da busca; esta página só alimenta os dropdowns de endereço.
• Não impõe uma hierarquia. Você pode tecnicamente criar um estado em um país cujo código ISO está errado, ou uma cidade em um estado que pertence a um país diferente. O formulário previne a maioria desses casos definindo country_id a partir da seleção, mas um conserto SQL manual pode quebrar. A trilha de auditoria é sua rede de segurança.
• Não versiona. Não há histórico de "como a lista parecia no trimestre passado". Trate como a verdade atual.

Se precisa que dados históricos de endereço sejam preservados (por exemplo, para um membro cujo estado foi renomeado), capture nas colunas de texto address do membro no momento da captura, não no seletor.