1. Qué hace

Addon del plugin ODSLocal Municipios que importa datos directamente desde la API pública de INEbase, guardándolos como mediciones approved en la plataforma.

• Módulo A — 9 indicadores demográficos (padrón, nomenclátor, atlas de renta, envejecimiento, dependencia).
• Módulo B — 26 indicadores ODS mapeados por UVigo (6 implementados y 20 pendientes de configuración).
• Cron anual opcional: cada 1 de enero a las 03:00 refresca todos los municipios activos.
• Poblar municipios: crea los ~8 100 territorios oficiales (CCAA, provincias, municipios) de España.

2. Instalación

1. Requiere ODSLocal Municipios activo.
2. Subir odslocal-ine-importer/ a wp-content/plugins/.
3. Activar. Se añade el submenú Municipios → Importar INE.

3. Poblar municipios

Primer paso típico tras instalar la plataforma: cargar todos los territorios oficiales.

1. Entra en Municipios → Importar INE → Poblar municipios.
2. Elige qué cargar: solo CCAA, CCAA + provincias, o todo (incluidos ~8 100 municipios).
3. Confirma. El proceso corre en el navegador por lotes → sin depender de max_execution_time.
4. Barra de progreso en vivo + log de errores por territorio.

4. Módulos de indicadores

4.1 Módulo A — Demográfico (9 indicadores)

• Población total, por sexos y grupos de edad (Padrón).
• Índice de envejecimiento, tasa de dependencia (calculados).
• Renta media (Atlas de renta).
• Densidad de población (Nomenclátor).

4.2 Módulo B — ODS (26 indicadores)

Mapeo oficial UVigo × INE. Estado actual:

• 6 implementados — consultables e importables.
• 20 pendientes — mapeo a completar. Ver Probador de operaciones (§10).

5. Importación interactiva

5.1 Seleccionar municipios

• Autocompletado por nombre o código INE (3+ caracteres).
• Añadir múltiples.
• Opción «Importar todos los municipios» (pide confirmación con estimación de tiempo y tamaño).

5.2 Elegir módulo e indicadores

Módulo A o B. Por defecto todos los indicadores implementados; se pueden deseleccionar individualmente.

5.3 Ejecutar

1. El cliente envía los municipios al servidor en lotes de 5.
2. Cada lote invoca la API del INE y guarda las mediciones.
3. La UI muestra progreso en vivo, contadores OK/error y log.
4. Se puede cancelar en cualquier momento: los lotes ya completados quedan persistidos.

6. Modo dry-run

Marca «Modo dry-run» antes de importar para simular sin escribir en la BD.

• Cada hallazgo aparece como [DRY] en el log.
• El import_run se guarda con prefijo [DRY-RUN] y no contiene mediciones reales.
• Ideal para validar un mapeo nuevo antes de persistir.

7. Cron automático anual

Desde la parte superior del panel, toggle «Activar cron automático».

• Frecuencia: una vez al año, 1 de enero a las 03:00.
• Hook: odslocal_ine_annual_import.
• Importa todos los municipios active × indicadores implementados.
• Guarda resumen en odslocal_ine_cron_last_run.

8. Ejecutar ahora (manual)

Botón «Ejecutar ahora» (solo manage_options) — dispara la misma importación que el cron pero desde el navegador, en lotes.

• No depende de max_execution_time del servidor (desde v1.0.7).
• Funciona en hostings compartidos con límites de 30 s.
• Cancelable en cualquier momento.

9. Histórico de importaciones

Al final de la página:

• Lista paginada con estado (processing, done, cancelled, error).
• Clic en una fila → drill-down: hasta 200 mediciones persistidas con municipio, indicador, año, valor, fuente.
• ⬇ CSV → descarga streaming de todas las mediciones del run (BOM UTF-8 para Excel).
• Cancelar para runs bloqueados en processing.
• Rollback — elimina todas las mediciones del run y marca el run como revertido.

10. Probador de operaciones INE

En la sección Módulo B, botón 🔬 Probador de operación INE (sólo admin).

Flujo recomendado para implementar un indicador pendiente:

1. Identifica una operación candidata (p. ej. «Encuesta de condiciones de vida», operación 4453).
2. En el probador: operation=4453, code_ine=28079 (Madrid), mun_var=19.
3. Si la operación cubre municipios, devuelve lista de series con sus nombres y último valor.
4. Copia un substring discriminante del Nombre de la serie correcta (p. ej. «Tasa de pobreza relativa»).
5. Edita includes/class-ine-ods.php: cambia status: 'implemented', pon operation, nombre_search y ajusta nult (últimos N años).
6. Usa Modo dry-run del importador para validar con varios municipios antes de persistir.

11. Diagnóstico y caché

11.1 Badge INE

En la parte superior del panel aparece un badge:

• 🟢 API del INE alcanzable.
• 🔴 Error de conectividad (DNS, timeout, INE caído).
• Clic → re-comprobar ignorando la caché de 60 s.

11.2 Test de conexión

Botón en sección Configuración: prueba manual detallada con headers y tiempo de respuesta.

11.3 Limpiar caché

Invalida todos los transients ine_*, preservando las sesiones de población activas. Útil si el INE publicó datos nuevos y tú ya tenías respuesta cacheada.

12. Seguridad

• Todas las acciones AJAX requieren capability ods_upload_data.
• Operaciones sensibles (cron run-now, populate-all) requieren manage_options.
• Cada import_run vinculado a su created_by; usuarios sin ods_edit_all sólo operan sobre sus propios runs.
• Usuarios con scope territorial sólo importan para territorios dentro de su ámbito.
• Nonces verificados en todas las llamadas.
• Códigos INE sanitizados a [0-9]{4,5}; rutas de fichero construidas sólo con dígitos (imposible path traversal).

13. Desinstalación

Al eliminar el plugin (no sólo desactivar), uninstall.php limpia:

• La programación cron odslocal_ine_annual_import.
• Opciones odslocal_ine_cron_enabled, odslocal_ine_cron_last_run, odslocal_ine_status_badge.
• Transients ine_* y odslocal_ine_*.

No toca las tablas del plugin padre (territorios, mediciones, import_runs) ni ficheros JSON cacheados en data/ y cache/.

14. Traducciones

• Text domain: odslocal-ine.
• languages/odslocal-ine.pot — 267 msgids (PHP + JS).
• Galego (gl_ES) al 100 %, inglés y catalán parciales.
• Strings JS servidos vía wp_localize_script.

15. Solución de problemas

Badge INE en rojo

• Prueba Test de conexión → ve los detalles.
• ¿Tu host bloquea conexiones salientes? Contacta al proveedor.
• Prueba desde CLI: curl https://servicios.ine.es/wstempus/js/ES/CONSULTA/.

Import run queda en processing tras cerrar navegador

En el historial, cancela el run y vuelve a iniciar. Los lotes ya completados quedan persistidos (upsert): volver a lanzar sólo añade/actualiza lo que falte.

Cron no dispara

• WP cron requiere tráfico en el sitio.
• Ejecuta wp cron event run odslocal_ine_annual_import para forzar.
• Configura un cron server-side apuntando a wp-cron.php.

Valor extraño (p. ej. 999999)

INE a veces devuelve códigos especiales para no aplicable. El plugin intenta filtrarlos; si pasas a dry-run ves el raw. Ajusta nombre_search si hace falta.

Rollback de un run

En el historial, abre el run → botón Rollback. Borra todas las mediciones creadas en ese run; no afecta a mediciones manuales posteriores sobre las mismas claves.