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
| # | Documento | Contenuto |
|---|---|---|
| 01 | Ciclo di una richiesta e routing | bootstrap, routing a tre livelli, path riservati, risalita del router, $schema["request"] |
| 02 | Pagine, template e applet | contents/, ffTemplate e i marker di blocco, applet, layout, CSS/JS |
| 03 | Servizi HTTP e webhook | /srv, contratto JSON, bus dei servizi, Jobs, ricezione webhook |
| 04 | API interna e pubblica | REST interna, api/1.0 con Bearer, convenzioni del contratto, trappole |
| 05 | Cron, job e worker | cron HTTP, coda di job, worker CLI, manutenzione |
| 06 | Email, notifiche, SMS e push | process_mail, Mailer, Notifier, OneSignal, JoeSMTP, Twilio |
| 07 | Dati, database e contenuti | ffDB_Sql e le sue quattro trappole, Storage, modello vgallery, migration |
| 08 | Autenticazione, utenti e permessi | modulo auth, sessione, profili, ACL, cookie |
| 09 | Backend e sezioni | ffGrid/ffRecord, aggiungere una sezione, popup e toolbar |
| 10 | Moduli e servizi di terze parti | struttura di un modulo, moduli funzionali, tag di terze parti, consenso cookie |
| 11 | Media, immagini e file | showfiles, modi immagine, upload, filemanager |
| 12 | Cache e prestazioni | le quattro cache, livelli, invalidazione, cosa guardare |
| 13 | Osservabilità, diagnostica e CLI | error handling, ?__debug__, log, Sentry, esecuzione da riga di comando |
| 14 | Ambienti, installazione e deploy | config 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à | Stato | Dove |
|---|---|---|
| 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.
- I marker
<!--BeginX-->/<!--EndX-->non sono commenti. Niente spazi, niente rimozioni, niente riordini. → 02 §2.2 use_cache(false)in cima a ogni servizio e a ogni pagina dinamica. → 12exitalla fine di ogni endpoint JSON, altrimenti il CMS appende il layout. → 03 §1execute()per scrivere,query()per leggere: dopoquery(),getInsertID()mente. → 07 §1.1- I parametri in query vanno dichiarati in
$schema["request"], o il kernel li scarta con un redirect silenzioso. → 01 §5 - Il router non risponde 404: risale. Serve una guardia sul residuo di percorso. → 01 §4
- I parametri del cookie di sessione vanno impostati prima di
session_start(), in un solo punto. → 08 §6 Auth::env()eCms::env()leggono bucket diversi. → 08 §4- Il tenant/proprietario non arriva mai dal body. → 03, 04
- Ogni migration va anche in
database.sql, conJC_SCHEMA_VERSIONbumpata, 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 display_errorsresta a 0; il debug è on-demand con?__debug__. → 13- Lint dopo ogni modifica di massa. → 13 §8
- 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 JC_APP_SECRETnon si rigenera: va nel backup. → 14 §2- Un codice spedito per email non torna nella risposta al browser (attivazione, 2FA, recupero): è il segreto che prova l'accesso alla casella. → 08 §5
- Un indirizzo di ritorno preso dall'URL è solo un percorso del sito: passa da
Auth::redirectLocale(), o è un open redirect. → 08 §5 - Il
sql_modedel server non si allenta: si corregge la query o lo schema. Il codice gira sui default strict di MySQL 8 e MariaDB e sul dialettoANSIdi Aiven. → 07 §1 - 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
| File | Contenuto |
|---|---|
../../PANORAMICA_JOECMS.md | architettura e storia delle decisioni |
../../PRESENTAZIONE_JOECMS.md | presentazione non tecnica |
../../FIX_FUNZIONAMENTO.md | fix che cambiano il comportamento |
../../MIGLIORIE_ESTETICHE.md | interventi solo CSS/UI |
../../MIGRAZIONE_PHP7_PHP8.md | migrazione a PHP 8 |
../../INSTALLER_PIANO.md | piano dettagliato dell'installer |
../../VGALLERY_NEXT_PIANO.md | nuova area di gestione contenuti |
../../IGIENE_SEGRETI.md | gestione dei segreti |
../../GUIDA_INDICIZZAZIONE_AI.md, ../../GUIDA_SITEMAP.md | default riusabili |
../api-auth.md | riferimento operativo dell'API pubblica |
../documentazione/cms-ricetta-portabile.md | la ricetta di lavoro sullo stack (origine JoeSMTP) |
../documentazione/joesing-convenzioni.md | convenzioni e trappole (origine JoeSING) |