Installazione, Deploy e Operazioni

1. Scopo del documento

Questo documento descrive come installare, pubblicare e mantenere operativa la piattaforma in modo professionale.

E' pensato per:

• clienti tecnici
• partner di deployment
• system integrator
• team di supporto

2. Modello di distribuzione

La piattaforma e' distribuita in modalita' self-hosted.

2.1 Struttura di deploy

• sulla madre: backend/ contiene il control center Laravel, mentre la cartella pubblica reale dell'istanza corrente e' public_html/ e espone landing, documentazione e area admin
• sul client master: backend/ contiene il runtime ecommerce e mobile_app/ contiene il progetto Flutter
• nel bundle ufficiale del client master la cartella pubblica non viene distribuita col suo nome locale, ma come web_root/
• la madre conserva la documentazione ufficiale del client master e della sua app mobile

2.2 Vantaggi

• maggiore sicurezza
• separazione tra core e parte pubblica
• compatibilita' con hosting tradizionali e VPS Linux

3. Flusso di installazione

L'installazione non richiede setup manuale frammentato, ma usa un wizard guidato.

3.1 Step installativi

1. verifica ambiente
2. configurazione database
3. creazione admin principale
4. attivazione licenza
5. connessione Shopify
6. import iniziale catalogo
7. registrazione webhook
8. branding e servizi
9. completamento

3.2 Cosa produce il wizard

• ambiente Laravel funzionante
• primo admin
• shop iniziale
• collegamento Shopify
• catalogo locale
• webhook registrati
• branding pubblico pronto per app e backoffice

4. Requisiti infrastrutturali

I requisiti precisi possono dipendere dalla configurazione finale, ma l'architettura attuale presuppone un ambiente compatibile con:

• PHP moderno compatibile con Laravel 12
• database SQLite o MySQL/MariaDB a seconda dello scenario
• filesystem scrivibile per storage pubblico
• HTTPS disponibile
• accesso outbound verso Shopify e OneSignal

5. Configurazioni fondamentali

5.1 Database

Il wizard supporta il setup del database e salva i parametri necessari al runtime applicativo.

5.2 Shopify

Per il corretto funzionamento servono:

• dominio Shopify
• client_id
• client_secret
• token Storefront se richiesto dal flusso commerce

5.3 OneSignal

Per le notifiche push servono:

• OneSignal app id
• chiave privata corretta della singola app

5.4 Branding

Configurazioni lato backoffice:

• nome app
• logo
• palette
• supporto
• privacy policy
• terms URL

6. Storage e media

Il prodotto utilizza storage pubblico per:

• logo
• slide home
• immagini push caricate
• immagini custom categorie

6.1 Requisiti pratici

• il disco pubblico deve essere scrivibile
• gli URL media devono essere correttamente esposti
• il collegamento storage pubblico deve essere funzionante

7. Deploy backend

7.1 Principio corretto

Non bisogna esporre l'intera applicazione Laravel come document root. La root pubblica deve servire solo la parte pubblica.

7.2 Modello usato nel progetto

• il core e' in backend/
• la parte esposta dal dominio e' la document root reale del server
• sulla madre attuale questa cartella si chiama public_html/
• nel bundle release del client master questa cartella viene normalizzata in web_root/

7.3 Beneficio

Questo approccio e' molto piu' adatto a un prodotto commerciale distribuibile.

7.4 Regola pratica: i file non si aggiornano per path fissi, ma per ruolo

Il bundle ufficiale del client master contiene sempre tre blocchi logici:

• backend/
• mobile_app/
• web_root/

Questi nomi sono stabili dentro il pacchetto update e non dipendono dal nome reale delle cartelle del server cliente.

Sul singolo server si deve invece definire una mappa di destinazione:

• backend/ del bundle -> cartella backend reale dell'installazione
• web_root/ del bundle -> document root reale del dominio
• mobile_app/ del bundle -> cartella reale che contiene il sorgente Flutter del cliente

In questo modo lo stesso bundle funziona sia su server che usano public_html/, sia su server che usano public/, htdocs/, www/ o nomi personalizzati.

7.5 Dove mettere i file della piattaforma

Schema corretto lato installazione cliente:

• il core Laravel va in una cartella non pubblica, per esempio /home/site/app/backend
• la document root del dominio va nella cartella pubblica reale del server, per esempio /home/site/public_html
• il sorgente Flutter va in una cartella separata dalla root web, per esempio /home/site/app/mobile_app

Mappa operativa da seguire quando si applica un aggiornamento:

• copiare backend/ del bundle nella cartella backend reale
• copiare web_root/ del bundle nella document root reale del server
• copiare mobile_app/ del bundle nella cartella reale del progetto mobile

7.6 Esempi concreti di mapping

Esempio A:

• backend/ -> /home/cliente/store/backend
• web_root/ -> /home/cliente/public_html
• mobile_app/ -> /home/cliente/store/mobile_app

Esempio B:

• backend/ -> /var/www/estore/backend
• web_root/ -> /var/www/estore/public
• mobile_app/ -> /var/www/estore/mobile_app

Esempio C con nome personalizzato:

• backend/ -> /srv/appteam/client/backend
• web_root/ -> /srv/appteam/httpdocs_store
• mobile_app/ -> /srv/appteam/client/mobile-src

7.7 Deploy profile minimo da salvare per ogni installazione

Per evitare ambiguita', ogni installazione cliente dovrebbe avere una propria scheda tecnica con almeno questi campi:

• backend_path
• document_root_path
• mobile_app_path
• shared_storage_path se lo storage non e' dentro il backend standard
• database_path oppure parametri DB reali
• preserve_env = file .env da non sovrascrivere
• preserve_storage = contenuti locali di storage/ da preservare
• preserve_uploads = file media cliente da non perdere durante l'update

Questo profilo serve a sapere con precisione dove mettere i file della piattaforma su quel server specifico.

7.8 Cosa non sovrascrivere durante un aggiornamento

Un update del bundle non deve trattare tutto come materiale usa e getta.

Di norma vanno preservati:

• .env
• database SQLite o connessione DB del cliente
• storage/app/
• storage/logs/
• eventuali upload pubblici e asset generati localmente
• chiavi, segreti e configurazioni white-label del cliente

7.9 Flusso corretto di applicazione update

1. scaricare il bundle release dalla madre
2. estrarre lo zip in una directory temporanea
3. leggere il deploy profile dell'installazione
4. copiare backend/ verso backend_path
5. copiare web_root/ verso document_root_path
6. copiare mobile_app/ verso mobile_app_path
7. ripristinare o preservare i file locali che non vanno sovrascritti
8. eseguire post-update backend come composer install, migration e pulizia cache
9. rigenerare il branding mobile e ricompilare la app se il cliente distribuisce una nuova build

7.10 Nota importante sulla mobile app

Aggiornare mobile_app/ sul server non aggiorna automaticamente i telefoni degli utenti finali.

L'update del bundle aggiorna il sorgente Flutter del cliente. Dopo l'update bisogna:

• rigenerare il branding white-label
• produrre una nuova build Android/iOS
• distribuire la nuova app tramite il canale previsto

8. Deploy mobile

La mobile app puo' essere compilata per:

• Android
• iOS

8.1 Parametri chiave

• nome visualizzato dell'app
• icona
• splash
• URL base API
• configurazione OneSignal

8.2 Nota operativa

Bundle id e package name fanno parte del livello di build e distribuzione, quindi possono essere gestiti come elementi white-label nella pipeline di rilascio.

8.3 Sorgente e distribuzione

• la sorgente della mobile app non deve restare nella madre
• la build e il pacchetto aggiornamento vanno preparati partendo dal client master
• la madre pubblica documentazione, release, compatibilita' e download controllato dei pacchetti update

9. Operativita' quotidiana del merchant

Dal backoffice il merchant puo' gia' gestire:

• accessi admin
• profilo admin
• slide promozionali
• categorie visibili
• immagini categorie
• branding app
• notifiche push manuali
• collegamento Shopify

10. Operativita' catalogo

La vita del catalogo segue questa logica:

1. Shopify resta master
2. Laravel mantiene cache/catalogo locale
3. webhook e sync manuali mantengono allineato il sistema

10.1 Quando usare il sync manuale

E' utile in caso di:

• riallineamento iniziale
• problemi temporanei webhook
• variazioni massive di categoria

11. Operativita' notifiche push

11.1 Notifiche manuali

L'admin puo' inviare:

• titolo
• messaggio
• immagine opzionale
• prodotto opzionale per deep link

11.2 Notifiche automatiche ordini

Il sistema invia push in base agli eventi Shopify:

• ordine creato
• ordine pagato
• ordine annullato

11.3 Requisito funzionale

Perche' la push ordine arrivi al destinatario corretto, il device deve essere associato all'email del cliente.

12. Sicurezza operativa

12.1 Misure gia' adottate

• token sensibili cifrati nel database
• HMAC Shopify validato
• sessioni cliente hashate
• separazione root pubblica e core applicativo
• protezioni sulla gestione admin

12.2 Buone pratiche consigliate

• usare solo HTTPS
• ruotare periodicamente i segreti
• limitare l'accesso al backoffice
• mantenere backup regolari
• testare le notifiche dopo cambi credenziali

13. Backup e continuita' operativa

Per un prodotto commerciale sono consigliati backup regolari di:

• database
• storage pubblico
• file di configurazione necessari al runtime

13.1 Motivo

Il catalogo puo' essere reimportato da Shopify, ma:

• branding
• slide
• immagini custom
• impostazioni
• cronologia locale

sono asset applicativi da proteggere.

14. Health check consigliati

Un controllo operativo sano dovrebbe verificare regolarmente:

• accesso backoffice
• stato installazione
• validita' connessione Shopify
• disponibilita' Storefront token
• invio push di test
• accessibilita' storage pubblico

15. Test e verifiche

La codebase include test backend e verifiche tecniche utili per ridurre regressioni.

15.1 Verifiche consigliate dopo modifiche critiche

• test backend Laravel
• verifica webhook
• test invio push
• test login cliente
• test checkout reale
• test visualizzazione media pubblici

15.2 Verifiche consigliate prima della consegna cliente

• wizard installazione completo
• login admin
• configurazione branding
• import Shopify
• categorie in app
• login cliente
• lista ordini
• push manuale
• push ordine automatico
• checkout reale

16. Troubleshooting operativo

16.1 Le immagini non si vedono

Controllare:

• storage pubblico
• URL media
• permessi filesystem

16.2 Le push non partono

Controllare:

• OneSignal app id
• chiave privata corretta
• device registrati
• opt-in notifiche

16.3 Il catalogo non riflette Shopify

Controllare:

• import iniziale
• webhook registrati
• HMAC valido
• sync manuale dal backoffice

16.4 Il cliente non vede gli ordini

Controllare:

• login cliente funzionante
• sessione valida
• token Storefront corretto
• customer account abilitato correttamente lato Shopify

16.5 Il checkout fallisce

Controllare:

• Storefront token
• pubblicazione prodotto/varianti sul canale corretto
• esistenza locale della variante

17. Evoluzioni operative consigliate

Per aumentare ancora il valore commerciale del prodotto, i passi piu' utili sono:

• guida upgrade versionata
• checklist pre-release formale
• audit log backoffice
• monitor webhook con retry manuale
• ruoli admin avanzati
• dashboard tecnica di salute sistema

18. Conclusione

La piattaforma e' gia' strutturata per essere installata, configurata e gestita come un prodotto reale. Il modello scelto punta a un equilibrio molto forte tra:

• semplicita' di distribuzione
• controllo da backoffice
• potenza di Shopify
• esperienza mobile premium