SS
AppTeam eStore Platform Documentazione pubblica
Landing Indice documenti
Core

Backend Laravel

Il cuore operativo del prodotto: backoffice, configurazioni, wizard di setup, catalogo locale e strumenti amministrativi.

Torna all'indice Vai alla landing

1. Ruolo del backend

Il backend Laravel e' il centro operativo del prodotto. Non si limita a esporre API per l'app mobile, ma gestisce:

  • installazione dell'istanza
  • autenticazione admin
  • configurazione del negozio
  • connessione Shopify
  • import e sync del catalogo
  • contenuti della home mobile
  • dispositivi push
  • notifiche manuali e automatiche
  • account cliente mobile
  • checkout reale

2. Struttura applicativa

Le aree piu' importanti del backend sono:

  • app/Http/Controllers/
  • app/Http/Middleware/
  • app/Models/
  • app/Support/
  • resources/views/admin/
  • routes/web.php
  • routes/api.php
  • database/migrations/

La logica piu' importante e' spostata nei service sotto app/Support/.

3. Route web reali

3.1 Root e wizard

  • GET /
  • GET /install
  • POST /install/database
  • POST /install/admin
  • POST /install/license
  • POST /install/shopify
  • POST /install/import
  • POST /install/webhooks
  • POST /install/branding
  • GET /install/{step}

3.2 Accesso admin

  • GET /admin/login
  • POST /admin/login
  • POST /admin/logout

3.3 Backoffice autenticato

  • GET /admin/
  • GET /admin/profile
  • PUT /admin/profile
  • GET /admin/users
  • GET /admin/users/{user}/edit
  • POST /admin/users
  • PUT /admin/users/{user}
  • DELETE /admin/users/{user}
  • GET /admin/slides
  • GET /admin/slides/create
  • POST /admin/slides
  • GET /admin/slides/{slide}/edit
  • PUT /admin/slides/{slide}
  • DELETE /admin/slides/{slide}
  • GET /admin/notifications
  • POST /admin/notifications
  • GET /admin/settings
  • POST /admin/settings
  • GET /admin/catalog
  • POST /admin/catalog/collections
  • POST /admin/catalog/sync
  • GET /admin/shopify
  • POST /admin/shopify/credentials
  • POST /admin/shopify/verify
  • POST /admin/shopify/import
  • POST /admin/shopify/webhooks

4. Middleware fondamentali

4.1 redirect.if.installed

Evita la riapertura del wizard dopo il completamento dell'installazione.

4.2 installation.complete

Blocca l'accesso al backoffice se l'istanza non risulta installata.

4.3 auth

Protegge l'area admin standard Laravel.

4.4 customer.auth

Protegge le API cliente usando il token sessione mobile hashato in customer_sessions.

5. Wizard di installazione

Il wizard e' uno degli elementi piu' strategici del backend perche' rende il prodotto distribuibile come pacchetto self-hosted.

5.1 Step reali

Gli step correnti sono:

  1. requirements
  2. database
  3. admin
  4. license
  5. shopify
  6. import
  7. webhooks
  8. branding
  9. finish

5.2 Cosa fa concretamente

  • verifica l'ambiente
  • salva configurazioni DB
  • crea il primo admin
  • inizializza shops
  • salva licenza locale in app_settings
  • collega Shopify via client_id e client_secret
  • ottiene il token Admin API programmaticamente
  • importa prodotti, varianti e collezioni
  • registra i webhook Shopify
  • salva branding, legali e servizi
  • marca l'installazione come conclusa

5.3 Recovery bootstrap

E' presente un flusso di bootstrap di emergenza per casi in cui:

  • .env manchi
  • APP_KEY sia assente
  • la configurazione di runtime non sia caricabile

Questo rende il prodotto piu' robusto in contesti hosting reali.

6. Dashboard admin

La dashboard e' una vista riepilogativa basata su metriche locali:

  • numero prodotti
  • numero categorie
  • numero slide attive
  • stato collegamento Shopify
  • riepilogo configurazione

Serve come punto di controllo rapido dello stato dell'istanza.

7. Gestione admin e accessi

Il backend ora include due aree distinte:

7.1 Profilo admin

Permette all'admin loggato di modificare:

  • nome
  • email
  • password

7.2 Gestione altri admin

Permette di:

  • creare nuovi admin
  • modificare admin esistenti
  • cambiare le loro credenziali
  • rimuovere admin non piu' necessari

7.3 Protezioni attive

Sono gia' presenti due regole di sicurezza importanti:

  • non e' possibile eliminare l'account con cui si e' loggati
  • deve restare almeno un admin attivo nel sistema

8. Impostazioni app

La sezione impostazioni governa:

  • nome app
  • tagline
  • contatti assistenza
  • logo
  • palette colori
  • privacy policy
  • terms URL
  • stato OneSignal
  • chiavi OneSignal

Queste configurazioni vengono salvate in app_settings.

9. Catalogo locale

Il catalogo locale e' la base delle API usate dalla mobile app.

9.1 Tabelle principali

  • products
  • product_variants
  • collections
  • collection_product

9.2 Perche' esiste

Serve a:

  • velocizzare la mobile app
  • applicare visibilita' locale sulle categorie
  • gestire immagini custom categorie
  • disaccoppiare il frontend dal runtime live di Shopify

9.3 Personalizzazioni supportate

  • visibilita' categoria in app
  • immagine personalizzata categoria
  • mapping locale prodotto-collezione

10. Slide home

Il backend permette la gestione editoriale della home mobile tramite home_slides.

Per ogni slide sono gestiti:

  • titolo
  • sottotitolo
  • CTA label
  • CTA URL
  • immagine
  • posizione
  • stato attivo/disattivo

Queste slide vengono poi esposte nell'endpoint home del catalogo.

11. Shopify tools

Il blocco Shopify nel backoffice permette di:

  • aggiornare credenziali
  • verificare la connessione
  • eseguire import catalogo
  • registrare webhook

11.1 Logica di connessione

Il sistema usa il modello Shopify attuale basato su:

  • client_id
  • client_secret

e genera il token Admin API dal backend, evitando di richiedere all'utente un token statico copiato a mano.

12. Service layer principale

12.1 ShopifyAdminAccessTokenService

Responsabilita':

  • ottenere token Admin API
  • rinnovarli
  • gestire errori di autenticazione

12.2 ShopifyConnectionProbe

Responsabilita':

  • validare credenziali
  • verificare scopes
  • distinguere problemi Admin API e Storefront API

12.3 ShopifyInitialImportService

Responsabilita':

  • import iniziale prodotti
  • import varianti
  • import collezioni
  • costruzione mapping collection-product

12.4 ShopifyDeltaCatalogSyncService

Responsabilita':

  • processare webhook prodotti e collezioni
  • aggiornare il catalogo locale
  • gestire delete e riallineamenti

12.5 ShopifyStorefrontCheckoutService

Responsabilita':

  • validare il carrello rispetto al DB locale
  • creare un cart Shopify reale
  • restituire checkout_url
  • allegare buyer identity cliente se presente

12.6 ShopifyCustomerAccountService

Responsabilita':

  • login cliente
  • registrazione cliente
  • recupero password
  • profilo cliente
  • ordini cliente
  • sessione locale
  • allineamento push identity

12.7 OneSignalPushService

Responsabilita':

  • invio push manuali
  • invio push a device filtrati
  • allegato immagine
  • deep linking prodotto
  • storico invii

12.8 ShopifyOrderPushService

Responsabilita':

  • tradurre eventi ordine Shopify in notifiche push cliente
  • cercare dispositivi per email ordine
  • inviare messaggi contestuali su create, paid e cancelled

13. API backend verso la mobile app

13.1 Stato piattaforma

  • GET /api/v1/platform/status

Restituisce stato installazione, dati essenziali shop e configurazione push.

13.2 Catalogo

  • GET /api/v1/catalog/home
  • GET /api/v1/catalog/collections
  • GET /api/v1/catalog/collections/{collection}
  • GET /api/v1/catalog/products
  • GET /api/v1/catalog/products/{product}

13.3 Commerce

  • POST /api/v1/commerce/checkout

13.4 Push device

  • POST /api/v1/push/devices

13.5 Customer auth

  • POST /api/v1/customer/login
  • POST /api/v1/customer/register
  • POST /api/v1/customer/password/recover
  • POST /api/v1/customer/logout
  • GET /api/v1/customer/me
  • GET /api/v1/customer/orders

14. Modelli principali

14.1 Shop

Rappresenta l'istanza del negozio. In questo progetto il runtime e' single-shop.

14.2 ShopifyConnection

Memorizza:

  • dominio Shopify
  • client id
  • client secret
  • admin api token
  • storefront token
  • webhook secret
  • stato token

I campi sensibili sono cifrati.

14.3 AppSetting

KV storage per:

  • branding
  • servizi
  • licenza
  • impostazioni legali
  • metadata di import

14.4 CustomerSession

Mantiene:

  • hash del token sessione mobile
  • customer access token Shopify cifrato
  • anagrafica base cliente
  • timestamps di revoca e attivita'

14.5 PushDevice

Memorizza:

  • subscription id
  • onesignal id
  • push token
  • piattaforma
  • email associata
  • stato notifiche

14.6 PushNotification

Storico invii manuali e automatici con metadati.

15. Sicurezza backend

Misure gia' implementate:

  • cifratura token sensibili
  • validazione HMAC webhook Shopify
  • hash del token sessione cliente
  • separazione wizard/admin tramite middleware
  • distruzione sessioni dell'admin eliminato

Misure consigliate come evoluzione:

  • audit log strutturato
  • ruoli e permessi granulari
  • rate limiting avanzato su endpoint sensibili
  • centralizzazione error reporting

16. Aspetti operativi importanti

  • il backend si appoggia al primo Shop del database come contesto corrente
  • il catalogo app e' locale, non live da Shopify
  • il checkout rimane Shopify-hosted
  • l'app cliente usa il backend come gateway applicativo

17. Debito tecnico controllato

Punti da tenere presenti:

  • sistema attualmente single-shop
  • backoffice senza RBAC avanzato
  • nessun motore code/worker complesso documentato nel flusso attuale
  • post-checkout non riconciliato in app
  • alcune logiche mobile lavorano ancora per ricerca testuale invece che browse puro di collection