Geografía (datos maestros)

Audience

Este artículo es para operadores de la plataforma GCM. Los administradores de iglesia deberían ver el artículo Añadir un miembro para usar los desplegables de país / estado / ciudad — esta página es para el personal que mantiene las listas subyacentes.

Cada campo de dirección en la plataforma — perfiles de miembros, configuración de organización, el formulario público de donaciones, el formulario de visitantes — extrae de tres tablas maestras: countries, states, cities. Son de toda la plataforma, no por organización, por eso esta superficie vive en el administrador de plataforma. La pestaña Geografía (/platform/geography) es la consola CRUD para esas tablas, con un diseño de tres paneles en cascada e importación masiva por CSV para los detalles raros.

El diseño de tres paneles

La página se divide en tres tarjetas lado a lado. Cada panel solo se habilita cuando su padre está seleccionado:

1. Países — la lista maestra. Siempre visible.
2. Estados — se popula cuando se selecciona un país. El título de la tarjeta se ajusta para usar el admin_level_label del país ("Provincias" para Canadá, "Departamentos" para Colombia, "Estados" para EE. UU., etc.).
3. Ciudades — se popula cuando se selecciona un estado.

La selección persiste por panel: elegir un nuevo país restablece las selecciones de estado y ciudad; elegir un nuevo estado restablece solo la ciudad.

Cada panel tiene su propia caja de búsqueda que hace un includes del lado del cliente contra los nombres visibles.

Editando un país

Haz clic en Agregar en la parte superior del panel de Países — o el ícono del lápiz en cualquier fila — para abrir el formulario del país. Los campos son:

• Nombre (obligatorio) — el nombre de visualización, por ejemplo, "Colombia".
• Código ISO (obligatorio, 2 caracteres) — el código ISO 3166-1 alpha-2, por ejemplo, CO. Auto-convertido a mayúsculas.
• ISO numérico — el código numérico ISO 3166-1 (3 dígitos), por ejemplo, 170. Usado por algunas integraciones.
• Etiqueta de estado / provincia — cómo tu país llama a su subdivisión de primer nivel. "Departamento", "Provincia", "Región", "Cantón", "Prefectura". Controla el título y el texto de marcador en el selector de estado aguas abajo.
• Código de marcación — el prefijo internacional de marcación, por ejemplo, +57. Usado por el formateador de números de teléfono.
• Emoji de bandera — bandera Unicode pegada, por ejemplo, 🇨🇴. Se muestra junto al nombre del país en todas partes.

Guardar inserta una fila en countries si estabas agregando, o la actualiza en su lugar si estabas editando. La lista en caché se invalida para que el nuevo valor aparezca en cada desplegable de dirección en el siguiente render.

Eliminar un país abre una confirmación destructiva. La alerta es honesta sobre el cascade: eliminar Colombia también elimina cada estado y ciudad debajo de él. Si algún miembro o visitante se refiere a ese país por id, obtendrás una violación de FK — limpia esos primero o cambia el comportamiento de cascade en una migración, no desde esta interfaz.

Editando un estado

Los estados tienen dos campos:

• Nombre (obligatorio) — nombre de visualización.
• Código ISO — el código de subdivisión ISO 3166-2, por ejemplo, US-CA. Opcional pero recomendado. Auto-convertido a mayúsculas.

El mismo formulario de adición única, la misma confirmación de eliminación destructiva. El id del país se establece automáticamente desde la selección.

Editando una ciudad

Las ciudades tienen un campo: Nombre. No hay códigos; las ciudades son solo etiquetas asociadas a un estado y (desnormalizado para velocidad de consulta) un país.

Importación masiva por CSV

El formulario de adición única está bien para una entrada faltante. Para sembrar el conjunto de estados de todo un país (o el conjunto de ciudades de un estado), usa Importar en la parte superior del panel de estados o ciudades.

El diálogo de importación acepta texto plano, una fila por línea:

• Para estados: name,iso_code. El código ISO es opcional; si está en blanco, las primeras 3 letras del nombre se ponen en mayúsculas. Ejemplo:

  California,CA
  Texas,TX
  Florida,FL

• Para ciudades: name solamente.

Las líneas en blanco o que comienzan con # se omiten, por lo que puedes pegar listas fuente con comentarios.

El diálogo muestra un conteo en vivo de filas válidas analizadas debajo del área de texto, para que puedas hacer una verificación de cordura antes de presionar Importar. Todas las filas se insertan en un único viaje de ida y vuelta INSERT; el índice único en (country_id, name) (para estados) o (state_id, name) (para ciudades) significa que volver a importar la misma lista lanzará un error en el primer duplicado. El patrón correcto es: pegar solo las filas faltantes, no la lista completa.

Obtener datos

Para nuevos países, los datos canónicos de siembra son admin1CodesASCII.txt de GeoNames (estados) y el corte cities500.txt del país. Recórtalos a las columnas anteriores con awk y pégalos.

Situaciones comunes

"El formulario del miembro no muestra 'Cundinamarca' como departamento en Colombia." Selecciona Colombia en el panel de Países, busca "Cundi" en Estados. Si falta, Agrégalo con ISO CO-CUN. El desplegable se actualiza en todas partes inmediatamente — las consultas en caché se invalidan al guardar.

"Necesito agregar 47 ciudades faltantes a un estado." Selecciona el país, luego el estado, luego haz clic en Importar en el panel de Ciudades. Pega la lista, una por línea. Pulsa Importar. El diálogo reporta el conteo que insertó; si alguna falló (normalmente duplicados), el toast lo dice.

"Un cliente nos pidió que cambiemos el nombre de su país de 'United States' a 'US' para abreviar." No lo hagas. El nombre del país es global — todos los demás clientes también lo ven. Si debes localizar, el canal correcto son los archivos de traducción por idioma (src/i18n/locales/{en,es}.json) para las cadenas de visualización, manteniendo el iso_code para que los datos sean estables.

Lo que esta superficie no hace

• No hace geocodificación. El módulo de mapa usa Mapbox / Nominatim en el momento de la búsqueda; esta página solo alimenta los desplegables de dirección.
• No hace cumplir una jerarquía. Técnicamente puedes crear un estado en un país cuyo código ISO sea incorrecto, o una ciudad en un estado que pertenece a un país diferente. El formulario previene la mayoría de estos al establecer country_id desde la selección, pero una corrección SQL manual podría romperlo. El rastro de auditoría es tu red de seguridad.
• No versiona. No hay historia de "cómo se veía la lista el trimestre pasado". Trátalo como la verdad actual.

Si necesitas preservar datos históricos de direcciones (por ejemplo, para un miembro cuyo estado fue renombrado), captúralo en las columnas de texto address del miembro en el momento de la captura, no en el selector.