Index et carte des capacités
Ce manuel documente les capacités du système : ni l'histoire du projet (qui se trouve dans
PANORAMICA_JOECMS.md) ni les corrections individuelles (FIX_FUNZIONAMENTO.md), mais ce qu'on peut construire sur ce CMS et comment faire.Une partie des connaissances réunies ici vient des projets jumeaux construits sur la même stack (JoeSING, JoeQUIZ, JoeSMTP) : des mécanismes généraux offerts par le CMS qui n'étaient jusqu'ici documentés que dans le projet qui les avait utilisés en premier.
Les chapitres
| # | Document | Contenu |
|---|---|---|
| 01 | Cycle d'une requête et routage | bootstrap, routage à trois niveaux, chemins réservés, remontée du routeur, $schema["request"] |
| 02 | Pages, templates et applets | contents/, ffTemplate et les marqueurs de bloc, applets, layout, CSS/JS |
| 03 | Services HTTP et webhooks | /srv, contrat JSON, bus de services, Jobs, réception de webhooks |
| 04 | API interne et publique | REST interne, api/1.0 avec Bearer, conventions du contrat, pièges |
| 05 | Cron, jobs et workers | cron HTTP, file de jobs, worker CLI, maintenance |
| 06 | Email, notifications, SMS et push | process_mail, Mailer, Notifier, OneSignal, JoeSMTP, Twilio |
| 07 | Données, base de données et contenus | ffDB_Sql et ses quatre pièges, Storage, modèle vgallery, migrations |
| 08 | Authentification, utilisateurs et permissions | module auth, session, profils, ACL, cookies |
| 09 | Backend et sections | ffGrid/ffRecord, ajouter une section, popups et toolbar |
| 10 | Modules et services tiers | structure d'un module, modules fonctionnels, tags tiers, consentement aux cookies |
| 11 | Médias, images et fichiers | showfiles, modes d'image, upload, gestionnaire de fichiers |
| 12 | Cache et performances | les quatre caches, niveaux, invalidation, quoi surveiller |
| 13 | Observabilité, diagnostic et CLI | gestion des erreurs, ?__debug__, logs, Sentry, exécution en ligne de commande |
| 14 | Environnements, installation et déploiement | config d'environnement, assistant, déploiement de la branche active avec bin/deploy.sh, paquet (avec le manuel en instantané), checklist, mise à jour automatique du manuel |
Carte des capacités
Légende : ✅ en production · 🟡 présent, à configurer ou à tester · ⚪ échafaudage upstream, à vérifier avant de compter dessus.
| Capacité | État | Où |
|---|---|---|
| Pages dynamiques sans enregistrement (fichier → URL) | ✅ | 02 |
| Templates à tokens et blocs, multilingue par dictionnaire | ✅ | 02 |
| Routage déclaratif XML + modules | ✅ | 01 |
| Modèle de contenu à nœuds avec champs dynamiques | ✅ | 07 |
| Backend avec grilles et formulaires générés depuis la BD | ✅ | 09 |
| Comptes : connexion, inscription, récupération, activation | ✅ | 08 |
| Groupes, profils, permissions par nœud avec héritage | ✅ | 08 |
Endpoints JSON de projet (/srv) | ✅ | 03 |
| API publique avec client credentials → Bearer | ✅ (auth seulement) | 04 |
| Emails transactionnels avec templates et pièces jointes | ✅ | 06 |
| Langue préférée sur le profil : pages, emails et notifications dans la langue de l'utilisateur, même depuis cron | ✅ | 12, 06 §2 |
| Redimensionnement d'images à la volée avec cache | ✅ | 11 |
| Cache de page par utilisateur/groupe/anonyme et par langue | ✅ | 12 |
| Services tiers configurables + consentement aux cookies côté serveur | ✅ | 10 |
Sitemap (une entrée par langue, avec hreflang) et version Markdown pour les LLM | ✅ | GUIDA_SITEMAP.md, GUIDA_INDICIZZAZIONE_AI.md, 12 §2 |
| Suivi des erreurs (Sentry) | ✅ (DSN requis) | 13 |
| Cron HTTP planifiables | 🟡 (schéma prêt, aucun job dans le dépôt de base) | 05 |
| Réception de webhooks de fournisseurs | 🟡 (modèle, pas d'instances) | 03 §2 |
| Notifications in-app avec programmation et expiration | 🟡 | 06 §3 |
| Push (OneSignal) et SMS (JoeSMTP, Twilio) | 🟡 (prêts, clés nécessaires) | 06 §4 |
| Second facteur à la connexion | 🟡 (désactivé, AUTH_2FA) | 08 §5bis |
File de jobs persistante (Jobs) et appels asynchrones | 🟡 | 05 §4 |
| Worker longue durée en CLI | 🟡 (shell + systemd nécessaires) | 05 §5 |
| Constructeur de formulaires depuis le backend avec archive des réponses | 🟡 | 10 §2 |
| Recherche dans les contenus | 🟡 | 10 §2 |
| Storage multi-driver (MySQL, MongoDB, fichier) | 🟡 | 07 §2 |
| Cache applicatif sur Redis/Memcached/APCu | 🟡 | 12 §4 |
| Import/export, sauvegarde, clonage de schéma | ⚪ | 07 §5 |
| Paiements avec passerelles en drivers (Stripe : paiements uniques, abonnements, remboursements, webhooks) | 🟡 (clés nécessaires) | 10 §2 |
| E-commerce (panier, wishlist, paiements) | ⚪ | 10 §2 |
| Serveur OAuth2 / apiserver | ⚪ (routes présentes, dossiers absents) | 08 §1 |
| Broker de files (RabbitMQ) | ⚪ (bibliothèque présente, non câblée) | 05 §4 |
| Mise à jour distante | ⚪ (abandonnée, rendue inerte) | 05 §3 |
Les règles non négociables
Synthèse des pièges qui ont déjà fait des dégâts dans l'écosystème. Le détail est dans les chapitres.
- Les marqueurs
<!--BeginX-->/<!--EndX-->ne sont pas des commentaires. Pas d'espaces, pas de suppressions, pas de réordonnancement. → 02 §2.2 use_cache(false)en tête de chaque service et de chaque page dynamique. → 12exità la fin de chaque endpoint JSON, sinon le CMS ajoute le layout. → 03 §1execute()pour écrire,query()pour lire : aprèsquery(),getInsertID()ment. → 07 §1.1- Les paramètres en query doivent être déclarés dans
$schema["request"], sinon le kernel les écarte par une redirection silencieuse. → 01 §5 - Le routeur ne répond pas 404 : il remonte. Il faut une garde sur le résidu de chemin. → 01 §4
- Les paramètres du cookie de session se définissent avant
session_start(), en un seul endroit. → 08 §6 Auth::env()etCms::env()lisent des buckets différents. → 08 §4- Le tenant/propriétaire n'arrive jamais du body. → 03, 04
- Chaque migration va aussi dans
database.sql, avecJC_SCHEMA_VERSIONincrémentée, et la version le déclare dans le CHANGELOG (· schema **N**,### Schema) : c'est là que joecms.it apprend s'il doit prévenir de mettre à jour la base de données. → 07 §4, 14 §5 display_errorsreste à 0 ; le debug se fait à la demande avec?__debug__. → 13- Lint après chaque modification de masse. → 13 §8
- Le logo dans les emails est un PNG, jamais un SVG. Par défaut il voyage comme URL absolue, et non plus comme pièce jointe
cid:: certains relais rejettent tout le message s'il contient une pièce jointe. → 06 §2 JC_APP_SECRETne se régénère pas : il va dans la sauvegarde. → 14 §2- Un code envoyé par email ne revient jamais dans la réponse au navigateur (activation, 2FA, récupération) : c'est le secret qui prouve l'accès à la boîte mail. → 08 §5
- Une adresse de retour prise dans l'URL n'est qu'un chemin du site : elle passe par
Auth::redirectLocale(), sinon c'est un open redirect. → 08 §5 - Le
sql_modedu serveur ne s'assouplit pas : on corrige la requête ou le schéma. Le code tourne sur les valeurs strict par défaut de MySQL 8 et MariaDB et sur le dialecteANSId'Aiven. → 07 §1 - Un texte que voit le visiteur ne s'écrit jamais dans une seule langue : dictionnaire dans les modèles,
Auth::text()dans les messages du compte, tables par langue là où il n'y a pas de base de données. → 02 §2.3
Documents liés
| Fichier | Contenu |
|---|---|
../../PANORAMICA_JOECMS.md | architecture et histoire des décisions |
../../PRESENTAZIONE_JOECMS.md | présentation non technique |
../../FIX_FUNZIONAMENTO.md | corrections qui changent le comportement |
../../MIGLIORIE_ESTETICHE.md | interventions CSS/UI uniquement |
../../MIGRAZIONE_PHP7_PHP8.md | migration vers PHP 8 |
../../INSTALLER_PIANO.md | plan détaillé de l'installeur |
../../VGALLERY_NEXT_PIANO.md | nouvel espace de gestion des contenus |
../../IGIENE_SEGRETI.md | gestion des secrets |
../../GUIDA_INDICIZZAZIONE_AI.md, ../../GUIDA_SITEMAP.md | réglages par défaut réutilisables |
../api-auth.md | référence opérationnelle de l'API publique |
../documentazione/cms-ricetta-portabile.md | la recette de travail sur la stack (origine JoeSMTP) |
../documentazione/joesing-convenzioni.md | conventions et pièges (origine JoeSING) |