Índice y mapa de capacidades
Este manual documenta las capacidades del sistema: no la historia del proyecto (que está en
PANORAMICA_JOECMS.md) ni las correcciones individuales (FIX_FUNZIONAMENTO.md), sino qué se puede construir sobre este CMS y cómo se hace.Parte del conocimiento aquí recogido viene de los proyectos hermanos construidos sobre el mismo stack (JoeSING, JoeQUIZ, JoeSMTP): mecanismos generales que ofrece el CMS y que hasta ahora estaban documentados solo en el proyecto que los había usado primero.
Los capítulos
| # | Documento | Contenido |
|---|---|---|
| 01 | Ciclo de una petición y enrutamiento | bootstrap, enrutamiento en tres niveles, rutas reservadas, subida del router, $schema["request"] |
| 02 | Páginas, plantillas y applets | contents/, ffTemplate y los marcadores de bloque, applets, layout, CSS/JS |
| 03 | Servicios HTTP y webhooks | /srv, contrato JSON, bus de servicios, Jobs, recepción de webhooks |
| 04 | API interna y pública | REST interna, api/1.0 con Bearer, convenciones del contrato, trampas |
| 05 | Cron, jobs y workers | cron HTTP, cola de jobs, worker CLI, mantenimiento |
| 06 | Email, notificaciones, SMS y push | process_mail, Mailer, Notifier, OneSignal, JoeSMTP, Twilio |
| 07 | Datos, base de datos y contenidos | ffDB_Sql y sus cuatro trampas, Storage, modelo vgallery, migraciones |
| 08 | Autenticación, usuarios y permisos | módulo auth, sesión, perfiles, ACL, cookies |
| 09 | Backend y secciones | ffGrid/ffRecord, añadir una sección, popups y toolbar |
| 10 | Módulos y servicios de terceros | estructura de un módulo, módulos funcionales, tags de terceros, consentimiento de cookies |
| 11 | Medios, imágenes y archivos | showfiles, modos de imagen, upload, filemanager |
| 12 | Caché y rendimiento | las cuatro cachés, niveles, invalidación, qué vigilar |
| 13 | Observabilidad, diagnóstico y CLI | gestión de errores, ?__debug__, logs, Sentry, ejecución desde línea de comandos |
| 14 | Entornos, instalación y despliegue | config de entorno, asistente, despliegue de la rama activa con bin/deploy.sh, paquete (con el manual como instantánea), checklist, actualización automática del manual |
Mapa de capacidades
Leyenda: ✅ en producción · 🟡 presente, por configurar o probar · ⚪ andamiaje upstream, verificar antes de contar con ello.
| Capacidad | Estado | Dónde |
|---|---|---|
| Páginas dinámicas sin registro (archivo → URL) | ✅ | 02 |
| Plantillas con tokens y bloques, multilingüe desde diccionario | ✅ | 02 |
| Enrutamiento declarativo XML + módulos | ✅ | 01 |
| Modelo de contenido por nodos con campos dinámicos | ✅ | 07 |
| Backend con tablas y formularios generados desde la BD | ✅ | 09 |
| Cuentas: login, registro, recuperación, activación | ✅ | 08 |
| Grupos, perfiles, permisos por nodo con herencia | ✅ | 08 |
Endpoints JSON de proyecto (/srv) | ✅ | 03 |
| API pública con client credentials → Bearer | ✅ (solo auth) | 04 |
| Email transaccional con plantillas y adjuntos | ✅ | 06 |
| Idioma preferido en el perfil: páginas, emails y notificaciones en el idioma del usuario, incluso desde cron | ✅ | 12, 06 §2 |
| Redimensionado de imágenes al vuelo con caché | ✅ | 11 |
| Caché de página por usuario/grupo/anónimo y por idioma | ✅ | 12 |
| Servicios de terceros configurables + consentimiento de cookies en servidor | ✅ | 10 |
Sitemap (una entrada por idioma, con hreflang) y versión Markdown para LLM | ✅ | GUIDA_SITEMAP.md, GUIDA_INDICIZZAZIONE_AI.md, 12 §2 |
| Seguimiento de errores (Sentry) | ✅ (requiere DSN) | 13 |
| Cron HTTP programables | 🟡 (esquema listo, ningún job en el repo base) | 05 |
| Recepción de webhooks de proveedores | 🟡 (patrón, no instancias) | 03 §2 |
| Notificaciones in-app con programación y caducidad | 🟡 | 06 §3 |
| Push (OneSignal) y SMS (JoeSMTP, Twilio) | 🟡 (listos, faltan claves) | 06 §4 |
| Segundo factor en el login | 🟡 (apagado, AUTH_2FA) | 08 §5bis |
Cola de jobs persistente (Jobs) y llamadas asíncronas | 🟡 | 05 §4 |
| Worker de larga duración desde CLI | 🟡 (requiere shell + systemd) | 05 §5 |
| Constructor de formularios desde backend con archivo de respuestas | 🟡 | 10 §2 |
| Búsqueda en los contenidos | 🟡 | 10 §2 |
| Storage multi-driver (MySQL, MongoDB, archivo) | 🟡 | 07 §2 |
| Caché de aplicación en Redis/Memcached/APCu | 🟡 | 12 §4 |
| Importación/exportación, backup, clonación de esquema | ⚪ | 07 §5 |
| Pagos con pasarelas como drivers (Stripe: pagos únicos, suscripciones, reembolsos, webhooks) | 🟡 (faltan claves) | 10 §2 |
| E-commerce (carrito, wishlist, pagos) | ⚪ | 10 §2 |
| Servidor OAuth2 / apiserver | ⚪ (rutas presentes, carpetas ausentes) | 08 §1 |
| Broker de colas (RabbitMQ) | ⚪ (librería presente, no conectada) | 05 §4 |
| Actualizador remoto | ⚪ (retirado, inerte) | 05 §3 |
Las reglas no negociables
Síntesis de las trampas que en el ecosistema ya han hecho daño. El detalle está en los capítulos.
- Los marcadores
<!--BeginX-->/<!--EndX-->no son comentarios. Nada de espacios, nada de eliminaciones, nada de reordenar. → 02 §2.2 use_cache(false)al principio de cada servicio y de cada página dinámica. → 12exital final de cada endpoint JSON, si no el CMS añade el layout. → 03 §1execute()para escribir,query()para leer: después dequery(),getInsertID()miente. → 07 §1.1- Los parámetros en query deben declararse en
$schema["request"], o el kernel los descarta con un redirect silencioso. → 01 §5 - El router no responde 404: sube. Hace falta una guarda sobre el residuo de ruta. → 01 §4
- Los parámetros de la cookie de sesión se configuran antes de
session_start(), en un solo punto. → 08 §6 Auth::env()yCms::env()leen buckets distintos. → 08 §4- El tenant/propietario nunca llega desde el body. → 03, 04
- Cada migración va también en
database.sql, conJC_SCHEMA_VERSIONincrementada, y la versión lo declara en el CHANGELOG (· schema **N**,### Schema): de ahí joecms.it sabe si debe avisar de actualizar la base de datos. → 07 §4, 14 §5 display_errorsse queda en 0; el debug es bajo demanda con?__debug__. → 13- Lint después de cada modificación masiva. → 13 §8
- El logo en los emails es un PNG, nunca un SVG. Por defecto viaja como URL absoluta, ya no como adjunto
cid:: algunos relays rechazan el mensaje entero si contiene una parte adjunta. → 06 §2 JC_APP_SECRETno se regenera: va en el backup. → 14 §2- Un código enviado por email nunca vuelve en la respuesta al navegador (activación, 2FA, recuperación): es el secreto que prueba el acceso al buzón. → 08 §5
- Una dirección de vuelta tomada de la URL es solo una ruta del sitio: pasa por
Auth::redirectLocale(), o es un open redirect. → 08 §5 - El
sql_modedel servidor no se relaja: se corrige la consulta o el esquema. El código funciona con los valores strict por defecto de MySQL 8 y MariaDB y con el dialectoANSIde Aiven. → 07 §1 - Un texto que ve el visitante nunca se escribe en un solo idioma: diccionario en las plantillas,
Auth::text()en los mensajes de la cuenta, tablas por idioma donde no hay base de datos. → 02 §2.3
Documentos relacionados
| Archivo | Contenido |
|---|---|
../../PANORAMICA_JOECMS.md | arquitectura e historia de las decisiones |
../../PRESENTAZIONE_JOECMS.md | presentación no técnica |
../../FIX_FUNZIONAMENTO.md | correcciones que cambian el comportamiento |
../../MIGLIORIE_ESTETICHE.md | intervenciones solo CSS/UI |
../../MIGRAZIONE_PHP7_PHP8.md | migración a PHP 8 |
../../INSTALLER_PIANO.md | plan detallado del instalador |
../../VGALLERY_NEXT_PIANO.md | nueva área de gestión de contenidos |
../../IGIENE_SEGRETI.md | gestión de secretos |
../../GUIDA_INDICIZZAZIONE_AI.md, ../../GUIDA_SITEMAP.md | valores por defecto reutilizables |
../api-auth.md | referencia operativa de la API pública |
../documentazione/cms-ricetta-portabile.md | la receta de trabajo sobre el stack (origen JoeSMTP) |
../documentazione/joesing-convenzioni.md | convenciones y trampas (origen JoeSING) |