Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 00

Indice e mappa delle capacità

Questo manuale documenta le capacità del sistema: non la storia del progetto (che sta in PANORAMICA_JOECMS.md) né i singoli fix (FIX_FUNZIONAMENTO.md), ma cosa si può costruire sopra questo CMS e come si fa.

Parte della conoscenza qui raccolta viene dai progetti gemelli costruiti sullo stesso stack (JoeSING, JoeQUIZ, JoeSMTP): meccanismi generali che il CMS offre e che finora erano documentati solo nel progetto che li aveva usati per primo.

I capitoli

#DocumentoContenuto
01Ciclo di una richiesta e routingbootstrap, routing a tre livelli, path riservati, risalita del router, $schema["request"]
02Pagine, template e appletcontents/, ffTemplate e i marker di blocco, applet, layout, CSS/JS
03Servizi HTTP e webhook/srv, contratto JSON, bus dei servizi, Jobs, ricezione webhook
04API interna e pubblicaREST interna, api/1.0 con Bearer, convenzioni del contratto, trappole
05Cron, job e workercron HTTP, coda di job, worker CLI, manutenzione
06Email, notifiche, SMS e pushprocess_mail, Mailer, Notifier, OneSignal, JoeSMTP, Twilio
07Dati, database e contenutiffDB_Sql e le sue quattro trappole, Storage, modello vgallery, migration
08Autenticazione, utenti e permessimodulo auth, sessione, profili, ACL, cookie
09Backend e sezioniffGrid/ffRecord, aggiungere una sezione, popup e toolbar
10Moduli e servizi di terze partistruttura di un modulo, moduli funzionali, tag di terze parti, consenso cookie
11Media, immagini e fileshowfiles, modi immagine, upload, filemanager
12Cache e prestazionile quattro cache, livelli, invalidazione, cosa guardare
13Osservabilità, diagnostica e CLIerror handling, ?__debug__, log, Sentry, esecuzione da riga di comando
14Ambienti, installazione e deployconfig d'ambiente, wizard, deploy del ramo attivo con bin/deploy.sh, pacchetto (con il manuale come istantanea), checklist, aggiornamento automatico del manuale

Mappa delle capacità

Legenda: ✅ in esercizio · 🟡 presente, da configurare o da collaudare · ⚪ impalcatura upstream, da verificare prima di contarci.

CapacitàStatoDove
Pagine dinamiche senza registrazione (file → URL)✅02
Template a token e blocchi, multilingua da dizionario✅02
Routing dichiarativo XML + moduli✅01
Modello di contenuto a nodi con campi dinamici✅07
Backend con griglie e form generati dal DB✅09
Account: login, registrazione, recupero, attivazione✅08
Gruppi, profili, permessi per nodo con ereditarietà✅08
Endpoint JSON di progetto (/srv)✅03
API pubblica con client credentials → Bearer✅ (solo auth)04
Email transazionali con template e allegati✅06
Lingua preferita sul profilo: pagine, email e notifiche nella lingua dell'utente, anche da cron✅12, 06 §2
Ridimensionamento immagini on-the-fly con cache✅11
Cache di pagina per utente/gruppo/anonimo e per lingua✅12
Servizi di terze parti configurabili + consenso cookie server-side✅10
Sitemap (una voce per lingua, con hreflang) e versione Markdown per LLM✅GUIDA_SITEMAP.md, GUIDA_INDICIZZAZIONE_AI.md, 12 §2
Error tracking (Sentry)✅ (serve DSN)13
Cron HTTP schedulabili🟡 (schema pronto, nessun job nel repo base)05
Ricezione webhook da provider🟡 (pattern, non istanze)03 §2
Notifiche in-app con programmazione e scadenza🟡06 §3
Push (OneSignal) e SMS (JoeSMTP, Twilio)🟡 (pronti, servono chiavi)06 §4
Secondo fattore al login🟡 (spento, AUTH_2FA)08 §5bis
Coda di job persistente (Jobs) e chiamate asincrone🟡05 §4
Worker longevo da CLI🟡 (serve shell + systemd)05 §5
Costruttore di form da backend con archivio risposte🟡10 §2
Ricerca sui contenuti🟡10 §2
Storage multi-driver (MySQL, MongoDB, file)🟡07 §2
Cache applicativa su Redis/Memcached/APCu🟡12 §4
Import/export, backup, clonazione schema⚪07 §5
Pagamenti con gateway a driver (Stripe: una tantum, abbonamenti, rimborsi, webhook)🟡 (servono chiavi)10 §2
E-commerce (carrello, wishlist, pagamenti)⚪10 §2
Server OAuth2 / apiserver⚪ (rotte presenti, cartelle assenti)08 §1
Broker di code (RabbitMQ)⚪ (libreria presente, non cablata)05 §4
Updater remoto⚪ (dismesso, reso inerte)05 §3

Le regole che non si negoziano

Sintesi delle trappole che nell'ecosistema hanno già fatto danni. Il dettaglio è nei capitoli.

  1. I marker <!--BeginX--> / <!--EndX--> non sono commenti. Niente spazi, niente rimozioni, niente riordini. → 02 §2.2
  2. use_cache(false) in cima a ogni servizio e a ogni pagina dinamica. → 12
  3. exit alla fine di ogni endpoint JSON, altrimenti il CMS appende il layout. → 03 §1
  4. execute() per scrivere, query() per leggere: dopo query(), getInsertID() mente. → 07 §1.1
  5. I parametri in query vanno dichiarati in $schema["request"], o il kernel li scarta con un redirect silenzioso. → 01 §5
  6. Il router non risponde 404: risale. Serve una guardia sul residuo di percorso. → 01 §4
  7. I parametri del cookie di sessione vanno impostati prima di session_start(), in un solo punto. → 08 §6
  8. Auth::env() e Cms::env() leggono bucket diversi. → 08 §4
  9. Il tenant/proprietario non arriva mai dal body. → 03, 04
  10. Ogni migration va anche in database.sql, con JC_SCHEMA_VERSION bumpata, e il rilascio lo dichiara nel CHANGELOG (· schema **N**, ### Schema): da lì joecms.it sa se avvisare di aggiornare il database. → 07 §4, 14 §5
  11. display_errors resta a 0; il debug è on-demand con ?__debug__. → 13
  12. Lint dopo ogni modifica di massa. → 13 §8
  13. Il logo nelle email è un PNG, mai un SVG. Di default viaggia come URL assoluto, non più allegato cid:: certi relay rifiutano il messaggio intero se contiene una parte allegata. → 06 §2
  14. JC_APP_SECRET non si rigenera: va nel backup. → 14 §2
  15. Un codice spedito per email non torna nella risposta al browser (attivazione, 2FA, recupero): è il segreto che prova l'accesso alla casella. → 08 §5
  16. Un indirizzo di ritorno preso dall'URL è solo un percorso del sito: passa da Auth::redirectLocale(), o è un open redirect. → 08 §5
  17. Il sql_mode del server non si allenta: si corregge la query o lo schema. Il codice gira sui default strict di MySQL 8 e MariaDB e sul dialetto ANSI di Aiven. → 07 §1
  18. Un testo che vede il visitatore non si scrive in una lingua sola: dizionario nei template, Auth::text() nei messaggi dell'account, tabelle per lingua dove non c'è database. → 02 §2.3

Documenti correlati

FileContenuto
../../PANORAMICA_JOECMS.mdarchitettura e storia delle decisioni
../../PRESENTAZIONE_JOECMS.mdpresentazione non tecnica
../../FIX_FUNZIONAMENTO.mdfix che cambiano il comportamento
../../MIGLIORIE_ESTETICHE.mdinterventi solo CSS/UI
../../MIGRAZIONE_PHP7_PHP8.mdmigrazione a PHP 8
../../INSTALLER_PIANO.mdpiano dettagliato dell'installer
../../VGALLERY_NEXT_PIANO.mdnuova area di gestione contenuti
../../IGIENE_SEGRETI.mdgestione dei segreti
../../GUIDA_INDICIZZAZIONE_AI.md, ../../GUIDA_SITEMAP.mddefault riusabili
../api-auth.mdriferimento operativo dell'API pubblica
../documentazione/cms-ricetta-portabile.mdla ricetta di lavoro sullo stack (origine JoeSMTP)
../documentazione/joesing-convenzioni.mdconvenzioni e trappole (origine JoeSING)