Mobile Flutter

1. Obiettivo dell'app mobile

L'app mobile rappresenta il front-end cliente della piattaforma. E' progettata per offrire un'esperienza ecommerce nativa, elegante e pronta alla pubblicazione, mantenendo Shopify come motore commerce e Laravel come hub di orchestrazione.

Questo documento resta pubblicato sulla madre come documentazione ufficiale del prodotto, ma la sorgente operativa dell'app mobile vive nel client master.

2. Punti chiave del progetto mobile

• app nativa multipiattaforma sviluppata in Flutter
• interfaccia orientata all'acquisto
• home promozionale gestita dal backoffice
• categorie e prodotti serviti dal backend locale
• login cliente reale
• ordini reali del cliente
• notifiche push integrate
• checkout Shopify reale

3. Architettura mobile reale

L'app segue una struttura feature-based. Le aree principali sono:

• features/account
• features/catalog
• features/commerce
• features/home
• features/navigation
• features/push

Questa organizzazione rende il progetto piu' estendibile e leggibile.

3.1 Collocazione del codice

• la madre ospita documentazione, marketing e release governance
• il client master ospita la sorgente reale della mobile app
• gli aggiornamenti distribuiti dalla madre vengono preparati a partire dal codice del client master

4. Tecnologie e pattern usati

4.1 Stack

• Flutter
• Material 3
• HTTP REST verso backend Laravel
• OneSignal SDK
• SharedPreferences per persistenza locale

4.2 Pattern architetturali

• repository pattern per il data access
• ChangeNotifier per stato locale
• AnimatedBuilder e widget stateful per reattivita'
• navigazione tramite Navigator

Non e' presente un framework di state management esterno pesante: l'app resta leggera, chiara e facilmente distribuibile.

5. Struttura dell'esperienza utente

La shell principale dell'app espone una navigazione stabile a quattro tab:

• Home
• Categorie
• Cerca
• Profilo

Questa struttura e' stata pensata per un uso ecommerce immediato e familiare.

6. Home

La home e' il primo touchpoint commerciale dell'app e viene popolata da dati reali provenienti dal backend.

6.1 Contenuti della home

• logo e branding dinamico
• slide promozionali configurate da backoffice
• blocco categorie visibili
• selezione prodotti in evidenza
• refresh dei contenuti

6.2 Vantaggio operativo

Il merchant puo' aggiornare la percezione dell'app senza dover pubblicare una nuova build, perche':

• slide e branding sono letti dal backend
• la visibilita' categorie e' controllata da backoffice
• i prodotti sono serviti dal catalogo locale sincronizzato

7. Categorie

La tab categorie mostra le collection rese visibili nel backoffice. Questo consente una gestione editoriale pulita del catalogo mostrato al cliente finale.

7.1 Cosa supporta oggi

• elenco categorie visibili
• immagine categoria
• navigazione verso lista prodotti

7.2 Nota progettuale

Il backend supporta gia' il dettaglio di collection, mentre una parte della UX mobile utilizza ancora una logica di ricerca testuale per l'apertura di alcuni listing. Questo e' un punto migliorabile in una futura evoluzione, ma la base dati e l'API sono gia' predisposte.

8. Ricerca

La tab ricerca offre un accesso rapido ai prodotti tramite query libera.

8.1 Funzioni

• campo di ricerca sempre disponibile
• risultato prodotto con immagine e prezzo
• accesso diretto al dettaglio prodotto

8.2 Beneficio

Questa scelta evita di obbligare il cliente a passare sempre da home o categorie per trovare un articolo.

9. Profilo

La tab profilo non e' una semplice pagina statica, ma il punto di convergenza di:

• account cliente
• storico ordini
• notifiche push
• supporto e link legali

10. Account cliente

L'app include un account cliente reale integrato con Shopify.

10.1 Funzioni disponibili

• login
• registrazione
• recupero password
• logout
• refresh profilo
• refresh ordini

10.2 Principio tecnico

L'autenticazione cliente non passa direttamente da Shopify verso il device. Il backend Laravel crea una sessione locale sicura e governa il token applicativo usato dall'app.

Questo porta diversi vantaggi:

• maggiore controllo lato piattaforma
• possibilita' di integrare push e identita' cliente
• migliore separazione tra client mobile e token Shopify

11. Ordini cliente

Dopo il login il cliente puo' vedere i suoi ordini reali.

11.1 Informazioni mostrate

• numero ordine
• stato
• totale
• righe principali
• data
• link alla pagina di stato ordine Shopify

11.2 Vantaggio commerciale

Questo rende l'app molto piu' completa rispetto a una semplice vetrina catalogo con checkout esterno.

12. Dettaglio prodotto

Il dettaglio prodotto e' la schermata centrale del funnel di acquisto.

12.1 Elementi presenti

• gallery immagine
• titolo
• prezzo
• varianti
• CTA aggiunta al carrello
• CTA wishlist

12.2 Comportamento

L'utente seleziona una variante reale e puo':

• aggiungerla al carrello
• salvarla tra i preferiti

13. Carrello

Il carrello e' persistente in locale, quindi sopravvive anche alla chiusura dell'app.

13.1 Cosa gestisce

• linee carrello
• quantita'
• subtotale
• rimozione articoli

13.2 Vantaggio UX

La persistenza locale migliora l'esperienza mobile e riduce l'attrito d'acquisto.

14. Wishlist

La wishlist e' anch'essa mantenuta in locale e permette al cliente di salvare articoli da recuperare in un secondo momento.

15. Checkout

Il checkout e' reale e usa Shopify Storefront API tramite backend Laravel.

15.1 Flusso

1. il cliente aggiunge articoli al carrello
2. l'app invia linee e varianti al backend
3. il backend valida le varianti locali
4. il backend crea un cart Shopify
5. se il cliente e' autenticato, allega la buyer identity
6. il backend restituisce checkout_url
7. l'app apre il checkout Shopify

15.2 Significato per il merchant

Il checkout resta affidabile e compatibile con l'ecosistema Shopify, mentre l'app mantiene una UX proprietaria fino al momento del pagamento.

16. Push notifications

L'integrazione push e' un blocco strategico dell'app.

16.1 Cosa supporta

• richiesta automatica permesso notifiche al primo avvio
• registrazione device OneSignal
• associazione email notifiche
• ricezione push manuali dal merchant
• ricezione push automatiche sugli ordini
• deep link verso prodotto

16.2 Collegamento con account cliente

Quando il cliente effettua login:

• l'email del suo account viene allineata sul device

Quando effettua logout:

• il device viene scollegato dall'identita' cliente

Questo e' fondamentale per inviare notifiche ordini al cliente corretto.

17. Persistenza locale

L'app mantiene tre blocchi di stato persistente:

17.1 Commerce store

Contiene:

• carrello
• wishlist

17.2 Customer account store

Contiene:

• token sessione cliente
• profilo
• ordini

17.3 Push preferences store

Contiene:

• email notifiche
• stato del prompt automatico permessi

18. Comunicazione col backend

I repository principali sono tre:

• catalog repository
• commerce repository
• customer account repository

In questo modo ogni area funzionale ha un punto di accesso dati chiaro e separato.

19. Branding dinamico

L'app non e' rigidamente compilata con tutti i contenuti. Alcuni elementi vengono serviti dinamicamente:

• nome app lato backend
• logo
• colori
• slide
• categorie visibili
• supporto
• link legali

Questo e' un vantaggio enorme in ottica white-label o rivendita.

20. Punti di forza della soluzione mobile

• architettura semplice ma solida
• login cliente reale
• ordini reali
• checkout reale
• backoffice che governa l'esperienza
• notifiche push realmente integrate
• contenuti promozionali aggiornabili senza nuova release

21. Evoluzioni consigliate

Le estensioni piu' naturali della parte mobile sono:

• navigazione category-first ancora piu' precisa
• stato ordine dettagliato in-app
• profilo cliente piu' ricco
• supporto coupon o promozioni dedicate
• tracking analytics piu' avanzato