Convoca Core

Plugin base del ecosistema Convoca. Proporciona la infraestructura compartida que usan el resto de módulos: logging centralizado, webhooks, locks atómicos, rate limiting, panel de control, salud del sistema, asistente de configuración, backup, licencias y branding de documentos. No registra shortcodes ni tipos de contenido propios; esos pertenecen a los módulos (Members, Enroll, Gateway, Shifts).

Requisitos: WordPress 6.4+ · PHP 8.1+ · probado hasta WordPress 7.1.

Manual para la junta directiva (sin conocimientos técnicos)¶

Esta página es la referencia técnica del plugin. Para el día a día hay un manual en tres partes, en castellano y con capturas:

• Instalación
• Configuración
• Guía de uso

1. Activación y arranque¶

Al activar el plugin, Convoca Core:

• Crea las tablas de base de datos convoca_logs, convoca_webhook_retries, convoca_locks y convoca_member_sequence.
• Programa los cron de limpieza de logs (convoca_log_cleanup y convoca_log_purge).
• Asigna al rol administrator las capacidades granulares manage_convoca_templates y manage_convoca_logs.
• Redirige al Asistente de Configuración en la primera activación (ver sección 6).

Si defines CONVOCA_KEEP_DATA_ON_UNINSTALL (valor verdadero) en wp-config.php, la desinstalación conserva todos los datos; de lo contrario, borra las tablas, opciones y crons del plugin.

2. Menú Convoca y páginas de administración¶

Convoca Core crea el menú superior Convoca (posición 3) en la barra lateral del admin. Las páginas que registra Core son:

Las páginas de socios, inscripciones, pagos, turnos, etc. las registran sus propios módulos, no Core. Core solo monta el menú raíz «Convoca» y sus páginas de infraestructura.

3. Panel de Control¶

Convoca → Panel de Control muestra un resumen agregado de todo el ecosistema, con caché de 5 minutos (botón Actualizar datos para refrescar):

Además incluye gráficas Chart.js —servidas localmente desde el plugin, sin CDN externo— de tendencia a 6 meses, ingresos mensuales, inscripciones por estado, métodos de pago y pagos de los últimos 7 días. El botón Generar memoria PDF descarga la memoria mensual (sección 15).

4. Salud del Sistema¶

Convoca → Salud del Sistema ejecuta un diagnóstico consolidado de todos los módulos instalados:

• Versión de Convoca Common.
• Estado de los plugins Members, Enroll, Gateway y Shifts (con sus checks internos).
• Existencia de las tablas convoca_logs, convoca_locks y convoca_webhook_retries.

Usa Forzar comprobación para repetir el diagnóstico sin caché. El resultado se clasifica en Todo correcto, Advertencias o Errores detectados, con sugerencias de reparación cuando el módulo las aporta.

5. Registros (Logs)¶

Convoca → Registros centraliza todos los logs del ecosistema en la tabla convoca_logs. Cada entrada guarda fecha, nivel (info, warning, error, debug), contexto (p. ej. Common/Security, Gateway/Redsys, Core/Lock), mensaje, usuario y objeto relacionado.

• Filtro por contexto y nivel; buscador; contador aproximado para tablas grandes (>10 000 filas).
• Clic en una entrada abre un modal con el mensaje completo.
• El logger interno está limitado a 50 escrituras por minuto para evitar inundaciones.

Retención (configurable por nivel, vía cron diario):

La retención se ajusta por nivel con la opción convoca_log_retention_days (array nivel→días, get_log_retention_days()), borrando cada día los registros que superan su antigüedad según su level. El exportador de la página de logs permite descargar los logs filtrados como CSV (BOM UTF-8, quoting RFC-4180, cabeceras created_at,level,context,message,user_id,object_id) con el botón «Exportar CSV».

6. Asistente de Configuración¶

Al activar por primera vez (o desde el enlace «Asistente Convoca» de la barra de admin), se abre un asistente de 7 pasos que comprueba y prepara la plataforma:

1. Infraestructura — verifica Convoca Common y las tablas de base de datos.
2. Páginas — crea las páginas obligatorias alta-socios, panel-socio y pago (con sus shortcodes).
3. Membresía — edita nombre, modalidad (Numerario/Familiar/Juvenil) y precio de los planes; al renombrar un ID corto migra los socios que lo usan.
4. Pagos (Redsys) — guarda Merchant Code y Secret Key.
5. Turnos — hora de apertura y cierre del centro.
6. Ecosistema — detecta qué módulos están activos y permite elegir el tema de los documentos.
7. Finalización — resumen con los requisitos cumplidos/pendientes.

Se puede volver a cualquier paso ya recorrido o Omitir asistente para configurar manualmente. El progreso se guarda en las opciones convoca_setup_wizard_completed, _dismissed y _progress.

6.1 Tema de los documentos (claro/oscuro)¶

En el paso 6 puedes elegir el estilo por defecto de carnets, certificados y emails transaccionales: Claro (por defecto) u Oscuro. Se guarda en la opción convoca_document_theme y puede cambiarse después desde la configuración del módulo correspondiente. El tema aplica al layout de email (Email_Layout) y a los documentos que respetan la opción global.

7. Copia de Seguridad (Backup y Restauración)¶

Convoca → Copia de Seguridad permite exportar e importar datos masivos del ecosistema.

Exportar genera un ZIP con:

• CSVs UTF-8 (con BOM para Excel) de miembros, inscripciones, proyectos y turnos.
• settings.json con la configuración de los módulos (solo opciones incluidas en una lista blanca: convoca_gateway_settings, convoca_members_settings, convoca_members_plans, convoca_enroll_settings, horarios y URL del calendario de turnos).

Importar sigue un flujo atómico:

1. Subes el ZIP (máx. 500 MB) y se valida su contenido, mostrando una previsualización con el número de registros por entidad.
2. Seleccionas qué entidades importar y confirmas. Se crean registros nuevos (los IDs originales se pierden) y se intenta remapear las relaciones internas (p. ej. inscripción → actividad).
3. Cada entidad exige su capacidad: proyectos/inscripciones → manage_inscripciones, miembros → gestionar_miembros, turnos → convoca_shifts_manage_turnos.
4. Antes de sobrescribir una opción de configuración se guarda una copia _backup_<fecha>.

La importación usa un lock (convoca_backup_import) para impedir importaciones concurrentes, y el archivo temporal se protege con .htaccess y un token de sesión.

8. Plantillas PDF¶

Ajustes → Plantillas PDF gestiona el HTML de los documentos generados por el sistema de firmas:

• Cada plantilla es HTML con placeholders {{nombre}}, {{dni}}, {{fecha}}, etc.
• Al guardar se crea un backup versionado de las últimas 5 versiones (opción convoca_pdf_templates_versions).
• Si una plantilla se corrompe (HTML inválido), se restaura a los valores por defecto guardando antes una copia de seguridad.
• Validación al guardar: tamaño máximo 500 KB, profundidad DOM < 30, máximo 10 bloques <style>, sin @import ni expression(), y sanitización de estilos peligrosos. Los usuarios sin unfiltered_html ven el HTML sanitizado con una lista blanca específica de Dompdf.

Usa Restaurar Plantillas por Defecto para volver al HTML original (pide confirmación).

9. Licencia¶

Convoca → Licencia activa/desactiva la clave de licencia (opción convoca_license) que habilita las funcionalidades PRO. La validación se hace contra la API remota con una petición firmada HMAC anti-replay; si el servidor no responde, guarda la clave en estado pending y reintenta. La cuadrícula de funcionalidades muestra qué módulos PRO están desbloqueados.

Sin licencia, Convoca Core sigue funcionando en modo gratuito.

10. Webhooks salientes¶

Convoca Core implementa el motor de webhooks (Webhook_Manager): los módulos emiten eventos y Core los entrega a las URLs registradas. La interfaz de configuración de las URLs vive en Convoca Members; Core se encarga del almacenamiento (opción convoca_webhooks), la entrega y los reintentos.

Eventos disponibles¶

Entrega y firma¶

Cada entrega incluye las cabeceras X-Convoca-Event, X-Convoca-Delivery (UUID único) y, si configuraste un secreto, X-Convoca-Signature con HMAC-SHA256 del cuerpo. Verificación en el receptor:

<?php
$secret   = 'tu-secreto-compartido';
$body     = file_get_contents( 'php://input' );
$computed = hash_hmac( 'sha256', $body, $secret );
if ( hash_equals( $computed, $_SERVER['HTTP_X_CONVOCA_SIGNATURE'] ?? '' ) ) {
    // Firma válida
}

• Deduplicación: mismo evento + payload se omite si se repite en 10 segundos.
• Reintentos con backoff exponencial: 60 s, 120 s, 240 s (máx. 3 intentos), procesados por el cron horario convoca_webhook_retry.
• Registro de entregas: últimas 50 por webhook.

11. Notificaciones internas¶

Core añade una campanita 🔔 en la barra de admin con las notificaciones del ecosistema (pagos fallidos, altas pendientes, horas por aprobar, solicitudes de baja, etc.). Se almacenan por usuario en el meta _convoca_notifications (máx. 50) y se pueden marcar como leídas o descartar desde el desplegable o desde Convoca → Notificaciones. También existen notificaciones por socio (meta del miembro), visibles en su panel.

Las notificaciones llegan a los roles administrator y monitor_actividad, y pueden enviarse además como push vía ntfy.sh (opción convoca_ntfy_config).

Copia de los correos (administrador o monitor)¶

Todo correo que un plugin de Convoca envía a una persona se copia también a la asociación: a los responsables (monitores) de la actividad si el correo es de una actividad, y al correo de administración en cualquier otro caso. Así una alta, una renovación, un certificado o una tarjeta no pasan desapercibidos fuera del panel.

• Mecanismo: Convoca\Core\Email_Copy (includes/Email_Copy.php). Los correos salen por el mismo canal que el original (se lo inyecta quien invoca), así que heredan el proveedor de correo configurado.
• La copia se marca con el asunto [Copia] … y una cabecera que indica a quién se envió y de dónde viene (plugin, plantilla, actividad o inscripción). No duplica los adjuntos.
• Un correo dirigido ya al destinatario de la copia no se copia a sí mismo.
• Activada por defecto. Se apaga desde Ajustes de socios → General (convoca-members) o con el filtro convoca_email_copy_enabled.

12. Seguridad: rate limiter, locks y Security Monitor¶

Protecciones automáticas que no requieren configuración:

• Rate limiter (Utils::check_rate_limit): por defecto 10 peticiones por ventana de 5 minutos por IP, con contador atómico en base de datos (INSERT ON DUPLICATE KEY). Se aplica a formularios y endpoints públicos.
• Locks atómicos (Utils::acquire_lock/release_lock): evitan condiciones de carrera (p. ej. sobreventa de plazas) usando la tabla convoca_locks, con fallback a wp_options.
• Security Monitor: observa accesos 401/403 a rutas REST de Convoca (rest_post_dispatch) y registra la contención de locks. Un digest diario (convoca_security_digest) envía email al administrador cuando en 24 h se superan los umbrales (configurables con el filtro convoca_security_thresholds):

El digest se envía como máximo una vez al día (anti-spam).

13. Branding: logo del sitio y tema de documentos¶

• Logo: los emails y PDFs usan el logo del sitio WordPress (custom_logo del tema). No hay fallback a un logo interno del plugin: si no hay custom_logo, se muestra el nombre del sitio. Filtro: convoca_{contexto}_logo_url (p. ej. convoca_email_logo_url).
• Tema de documentos: opción convoca_document_theme (light por defecto, dark). La expone Utils::get_document_theme() con filtros convoca_document_theme y convoca_document_theme_{contexto} (p. ej. convoca_document_theme_email).

14. Bloques y assets del frontend¶

• Bloque: Core registra el bloque convoca-common/post-meta-field (muestra un postmeta formateado: texto, fecha, precio o número) y crea las categorías de bloques convoca-core, convoca-enroll, convoca-members, convoca-turnos y convoca-gateway.
• Assets comunes: los estilos convoca-core y el script convoca-common-js se registran siempre (no se imprimen por sí solos) para que los shortcodes de los módulos —incluidos los renderizados dentro de plantillas FSE, que corren después de wp_enqueue_scripts— puedan declararlos como dependencia sin que WordPress los descarte. Se encolan solo cuando la página contiene un shortcode [convoca_*] o un plugin lo pide con el filtro convoca_need_common_assets:

<?php
// Forzar los assets comunes en una página concreta
add_filter( 'convoca_need_common_assets', function ( $needed ) {
    return is_page( 'mi-pagina-convoca' ) ? true : $needed;
} );

El asistente crea páginas con shortcodes que pertenecen a los plugins de cada área ([convoca_alta_socio] y [convoca_mi_area] en Members, [convoca_pago] en Gateway). Verifica que cada página contenga su shortcode real y las repara si no.

15. Shortcodes de interfaz y contenido¶

Core registra los shortcodes que necesitan las plantillas del theme (los ficheros .html de FSE no ejecutan PHP). No inventan datos: si no hay menú, redes, relacionadas, cifras o fecha de evento, devuelven vacío.

16. Datos de evento de una entrada¶

Core añade a la ficha de edición de la entrada el bloque Evento (marcar el contenido como evento, fecha de inicio, fecha de fin, lugar y precio) y escribe las claves canónicas _convoca_has_event, _convoca_event_start_date, _convoca_event_end_date, _convoca_event_address y _convoca_event_price. El theme publica el schema.org y pinta esos datos, pero no los guarda.

El precio (_convoca_event_price) es el precio por persona en euros y alimenta offers.price del datos estructurados del evento: sin él, una actividad de pago se anunciaba como gratuita. Se normaliza al guardar con event_price_sanitize(): acepta coma o punto decimal, exige un número válido y no negativo, y guarda dos decimales. Vacío = evento gratuito, y un valor inválido borra el meta en lugar de inventarse un precio.

• Filtro convoca_event_meta_legacy_keys: mapa clave canónica => clave antigua para que un sitio con datos históricos (por ejemplo _legacy_event_*) los siga leyendo sin que el producto arrastre el nombre de ninguna asociación.
• Filtro convoca_site_stats: ajusta o amplía las cifras de [convoca_stats].
• Filtro convoca_social_links: array servicio => URL (más handle opcional) que alimenta [convoca_socials] y los tokens {social_*} del pie del theme.

15. Memoria mensual PDF¶

El botón Generar memoria PDF del Panel de Control genera un PDF (Dompdf) con el resumen mensual de la asociación: socios, altas, inscripciones, ingresos y turnos. El cron semanal (convoca_weekly_event) la genera automáticamente durante la primera semana de cada mes y la guarda en wp-content/uploads/convoca-memorias/, notificando al administrador por email.

16. Extras para desarrolladores¶

• Registro de módulos: los módulos externos se registran con el filtro convoca_register_module; Core valida core_min, funcionalidades PRO y capacidades, y dispara convoca_module_registered.
• Performance Probe: añade ?convoca_probe=1 a cualquier URL (solo admins) para ver tiempo total, memoria pico, hooks lentos y queries lentas al final de la página.
• Layout de email: Email_Layout::render() genera emails HTML con la identidad visual (naranja #FF8700 + púrpura #320028) respetando el tema claro/oscuro.
• Firmas PDF: Signature genera PDFs desde plantillas HTML con reemplazo de placeholders, sello de aceptación con hash SHA-256 y protección del directorio de salida.

Referencia técnica¶

Capacidades personalizadas¶

Definidas en Capabilities::get_all() y asignadas a roles en plugins_loaded (no hace falta reactivar el plugin tras una actualización):

Capacidades adicionales referenciadas en Utils (usadas por los módulos): manage_inscripciones, gestionar_miembros, gestionar_documentos_voluntariado, view_reports, manage_convoca_templates, manage_convoca_logs, manage_convoca_gateway.

Roles¶

Core asigna capacidades a estos roles, que crean sus respectivos módulos (Core no los registra):

Tablas de base de datos¶

Cron¶

API REST¶

Hooks y filtros públicos (prefijo convoca_)¶

Acciones que dispara Core: convoca_module_registered.

Acciones que Core escucha (de los módulos): convoca_members_estado_changed, convoca_members_created, convoca_members_membership_expired, convoca_gateway_payment_completed, convoca_gateway_payment_failed, convoca_members_payment_reminder_sent, convoca_enroll_inscripcion_nueva, convoca_enroll_inscripcion_cancelada, convoca_enroll_asistencia_cambiada, convoca_members_hours_submitted, convoca_members_hora_aprobada, convoca_members_hora_rechazada, convoca_member_created, convoca_payment_failed, convoca_hours_submitted, convoca_inscripcion_pendiente_pago, convoca_voluntario_pendiente, convoca_members_unsubscribe_request, convoca_voluntario_aprobado.

Filtros: convoca_document_theme, convoca_document_theme_{contexto}, convoca_need_common_assets, convoca_security_thresholds, convoca_admin_appearance_url, convoca_common_webhook_sslverify, convoca_register_module, convoca_license_api_url, convoca_pdf_html_safe_keys, convoca_pdf_allowed_html, convoca_{contexto}_logo_url.

Convención de metadatos (postmeta) que Core lee/escribe¶

Core no registra los tipos de contenido, pero lee y escribe estos metas sobre CPTs que pertenecen a sus módulos (Members, Enroll, Gateway, Shifts):

Los metadatos con prefijo _ son privados (no aparecen en el editor de WordPress por defecto).