diff --git a/README.md b/README.md index ded00a3..83f8309 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,12 @@ CMS per portali captive: gestione di card informative, gallerie, flip-book e con 5. [Limiti di testo](#limiti-di-testo) 6. [Sicurezza degli input](#sicurezza-degli-input) 7. [Struttura dei dati (`data/`)](#struttura-dei-dati-data) -8. [Backup e ripristino](#backup-e-ripristino) -9. [Factory Preset (developer)](#factory-preset-developer) -10. [Font](#font) -11. [Prerequisiti di sistema](#prerequisiti-di-sistema) -12. [Risoluzione problemi](#risoluzione-problemi) +8. [Stato zero, rilasci e aggiornamenti del codice](#stato-zero-rilasci-e-aggiornamenti-del-codice) +9. [Backup e ripristino](#backup-e-ripristino) +10. [Factory Preset (developer)](#factory-preset-developer) +11. [Font](#font) +12. [Prerequisiti di sistema](#prerequisiti-di-sistema) +13. [Risoluzione problemi](#risoluzione-problemi) --- @@ -120,7 +121,7 @@ Solo i video possono essere ricodificati. Alla ricezione il server sonda i codec - **Video già compatibile** (H.264 + AAC/MP3) → nessuna ricodifica, salvataggio immediato. - **Video non compatibile** (HEVC iPhone, VP9, AV1, audio Opus/Vorbis…) → messo in coda e ricodificato in background con `ffmpeg` verso **MP4 H.264 + AAC, max 720p**. L'admin vede un badge "Transcoding XX%" sulla miniatura; quando finisce il file diventa riproducibile su tutti i browser. -> Le immagini e i PDF **non** vengono mai trasformati: sono salvati identici al file caricato. +> Le immagini e i PDF **non** vengono mai trasformati né compressi: sono salvati **byte-per-byte identici** al file caricato. Non esiste alcuna conversione AVIF/WebP lato server — un file PNG resta PNG con la stessa dimensione. La transcodifica richiede `ffmpeg`/`ffprobe` sul server — vedi [Prerequisiti](#prerequisiti-di-sistema). Se mancano, gli upload di video che richiedono ricodifica rispondono `503`. @@ -162,7 +163,25 @@ data/ └── transcode-jobs.json ← stato della coda di transcodifica (creato all'occorrenza) ``` -Copiare via questa cartella = backup completo. Sostituirla = ripristino completo. Nessun database, nessuna migrazione. +Copiare via questa cartella = backup completo. Sostituirla = ripristino completo. Nessun database esterno. + +--- + +## Stato zero, rilasci e aggiornamenti del codice + +### Cosa costituisce lo "stato zero" +Lo stato applicativo (i dati) è **solo** il contenuto di `data/`: `cards.txt`, `portals.txt`, `uploads/`, `fonts/`. Tutto il resto — codice sorgente, `node_modules`, e gli asset di default in `public/` (es. `hero-bg.jpg`, `logo.png`) — **non** fa parte dello stato dati: arriva con il rilascio del software. "Azzerare" il CPC significa quindi sostituire `data/` con uno stato noto. + +### Contenuti vs codice (due archivi distinti) +- **Backup dei contenuti**: archivia solo `data/` (lo fanno il pulsante "Scarica backup" e il comando `zip` documentato sotto). È ciò che si conserva e si ripristina. +- **Aggiornamento del codice**: si sostituisce tutto **tranne** `data/`. I contenuti restano al loro posto. +- Da CLI un reset conservativo è: `mv data data.old && `. È l'equivalente del `tar zxf` citato dal QA — vedi nota su ZIP vs tar nella sezione [Backup](#backup-e-ripristino). + +### Compatibilità dei contenuti dopo un update del codice +I contenuti salvati da versioni precedenti continuano a funzionare: in lettura vengono adattati al volo (es. il vecchio `extraImages: string[]` viene convertito in `extraMedia: MediaItem[]` in [`lib/db.ts`](lib/db.ts)). **Convenzione per future modifiche di schema:** aggiungere il branch di migrazione nella lettura (`getCards`/`getPortals`), senza mai rcompattare i dati legacy in scrittura senza un fallback in lettura — così un archivio di contenuti vecchio resta sempre ripristinabile. + +### Far accompagnare lo stato zero ai rilasci +Per avere uno stato di partenza noto su ogni macchina nuova, includere nel pacchetto di rilascio un `factory/preset.zip` curato (vedi [Factory Preset](#factory-preset-developer)). Su una macchina nuova, il ripristino di quel preset porta allo stato zero ufficiale. --- @@ -191,6 +210,8 @@ Lo zip così prodotto è caricabile direttamente dal pulsante "Ripristina da ZIP > **Struttura obbligatoria:** i file devono stare alla radice dello zip. Uno zip con tutto dentro una cartella `data/` verrà rifiutato con "cards.txt assente". Deve essere uno **ZIP**, non un `.tar`. +> **ZIP vs tar:** il CPC usa archivi **ZIP** (via `zip`/`unzip`), non `tar`. La finalità è la stessa di un `tar cf`/`tar zxf`: un singolo archivio dei soli contenuti, ripristinabile in un colpo. Il restore accetta lo ZIP prodotto dal pulsante "Scarica backup" o dal comando `zip` qui sopra. + --- ## Factory Preset (developer)