ecommerce-platform/ADMIN_GUIDE.md

Guida Utente — Pannello Admin

Guida completa all'uso del pannello di amministrazione dell'ecommerce platform.

---

Indice

1. Accesso e primo login
2. Dashboard
3. Prodotti ← sezione principale
4. Tipi di Prodotto
5. Categorie
6. Ordini
7. Clienti
8. Recensioni
9. Utenti Admin
10. Impostazioni
11. Flusso consigliato per iniziare

---

1. Accesso e Primo Login

Avviare il server

docker compose up -d

Al primo avvio attendere 5-10 minuti. Per monitorare:

docker compose logs -f app

Accedere al pannello

• URL: http://localhost/admin
• Email: admin@example.com
• Password: Admin1234!test

Cambio password al primo accesso

Al primo login il sistema reindirizza automaticamente alla pagina Change Password. La nuova password deve rispettare tutti i requisiti:

Requisito	Dettaglio
Lunghezza minima	12 caratteri
Lettere maiuscole	almeno 1
Lettere minuscole	almeno 1
Numeri	almeno 1
Simboli	almeno 1 (!@#$% ecc.)

Dopo il cambio password si accede direttamente alla Dashboard.

---

2. Dashboard

URL: http://localhost/admin

La dashboard è la schermata iniziale e offre una panoramica rapida dello stato del negozio.

Metriche principali

Sei card in evidenza mostrano i dati in tempo reale:

Metrica	Descrizione
Total Orders	Numero totale di ordini ricevuti
Pending Orders	Ordini in attesa di elaborazione (status: PENDING)
Revenue	Fatturato totale da ordini pagati
Products	Numero di prodotti nel catalogo
Customers	Numero di clienti registrati
Pending Reviews	Recensioni in attesa di moderazione

Ordini recenti

Sotto le metriche compare una tabella con i 5 ordini più recenti, che mostra:

• ID ordine
• Cliente
• Importo
• Stato corrente

Cliccando su un ordine si apre il dettaglio.

Link rapidi

Pulsanti di navigazione veloce alle sezioni più usate (Prodotti, Ordini, Categorie).

---

3. Prodotti

Questa è la sezione più importante del pannello. Permette di gestire l'intero catalogo.

URL lista: http://localhost/admin/products

3a. Lista Prodotti

La pagina mostra tutti i prodotti con:

• Titolo del prodotto
• Stato (DRAFT / PUBLISHED / ARCHIVED)
• Prezzo base
• Stock disponibile
• Pulsanti azione: Modifica, Archivia

Ricerca e filtri

• Barra di ricerca: filtra per titolo in tempo reale
• Filtro stato: dropdown per mostrare solo DRAFT, PUBLISHED o ARCHIVED

Creare un nuovo prodotto

Clicca il pulsante "New Product" (in alto a destra) per aprire il form di creazione.

---

3b. Creazione Nuovo Prodotto (GUIDA DETTAGLIATA)

URL: http://localhost/admin/products/new

Importante: prima di creare prodotti, assicurati di aver creato almeno un Product Type e almeno una Categoria. Vedi le sezioni 4 e 5.

Il form è diviso in 4 sezioni.

---

Sezione 1 — Basic Information

Product Type (obbligatorio)

• Campo: select (menu a tendina)
• Seleziona il tipo di prodotto (es. "Abbigliamento", "Elettronica", "Libri")
• Il tipo determina quali attributi custom saranno disponibili nella sezione 4
• Se non hai ancora creato tipi, vai prima su http://localhost/admin/product-types

---

Title (obbligatorio)

• Campo: text
• Limite: massimo 200 caratteri
• Esempio: "Sneaker Running Pro Modello X"
• Usa un titolo descrittivo e chiaro per i clienti

---

Slug (obbligatorio)

• Campo: text
• Generato automaticamente dal titolo (es. sneaker-running-pro-modello-x)
• Formato: solo lettere minuscole, numeri e trattini (-), no spazi
• Viene usato nell'URL del prodotto nel negozio: /products/sneaker-running-pro-modello-x
• Puoi modificarlo manualmente, ma deve essere unico tra tutti i prodotti
• Non cambiarlo dopo la pubblicazione per evitare link rotti

---

Description (obbligatorio)

• Campo: textarea
• Inserisci una descrizione completa del prodotto
• Suggerimenti per una buona descrizione:
  • Materiali e composizione
  • Caratteristiche principali
  • Istruzioni d'uso o cura
  • Taglie disponibili (se non gestite tramite varianti)

---

Sezione 2 — Pricing & Inventory

Base Price (obbligatorio)

• Campo: number (valore in centesimi)
• Attenzione: il prezzo va inserito in centesimi, non in euro/dollari
• Esempi:
  • 1999 → €19,99
  • 4990 → €49,90
  • 10000 → €100,00
• Valore minimo: 0

---

Currency (obbligatorio)

• Campo: select
• Opzioni disponibili:
  • EUR — Euro (€)
  • USD — Dollaro americano ($)
  • GBP — Sterlina britannica (£)
• Di default usa la valuta configurata nelle Impostazioni generali

---

Stock (opzionale)

• Campo: number
• Indica le unità disponibili in magazzino
• Lasciare vuoto = stock illimitato (il prodotto non esaurisce mai)
• Inserire 0 = prodotto esaurito (non acquistabile)
• Inserire un numero positivo (es. 50) = scorte limitate

---

Sezione 3 — Status & Organization

Status (obbligatorio)

• Campo: select
• Tre opzioni:

Valore	Significato
DRAFT	Bozza — il prodotto non è visibile nel negozio. Usalo mentre stai lavorando al prodotto.
PUBLISHED	Pubblicato — il prodotto è visibile nel negozio e acquistabile.
ARCHIVED	Archiviato — il prodotto è nascosto e non vendibile. Usato per prodotti discontinuati.

Consiglio: inizia sempre con DRAFT, verifica tutto, poi cambia in PUBLISHED.

---

Categories (opzionale)

• Campo: checkbox multipli
• Assegna il prodotto a una o più categorie del catalogo
• Le categorie aiutano i clienti a navigare il negozio
• Un prodotto può appartenere a più categorie contemporaneamente
• Se non hai ancora creato categorie, vai su http://localhost/admin/categories

---

Sezione 4 — Custom Attributes

Attributes (opzionale)

• Campo: JSON
• Permette di aggiungere attributi personalizzati in formato JSON
• Gli attributi disponibili dipendono dal Product Type selezionato nella sezione 1
• Esempio per un prodotto di abbigliamento:

{
  "colore": "Rosso",
  "taglie_disponibili": ["S", "M", "L", "XL"],
  "materiale": "100% cotone",
  "lavaggio": "30°C"
}

• Esempio per un prodotto elettronico:

{
  "marca": "Samsung",
  "modello": "Galaxy S25",
  "ram_gb": 12,
  "storage_gb": 256,
  "colori": ["Nero", "Bianco", "Verde"]
}

Il JSON deve essere valido: usa virgolette doppie per le chiavi, nessuna virgola finale nell'ultimo elemento.

---

Salvare il prodotto

Una volta compilati tutti i campi obbligatori, clicca "Save Product" (o "Create Product").

Se ci sono errori di validazione, il form li mostra in rosso accanto al campo corrispondente. I più comuni:

• Slug già usato da un altro prodotto → cambia lo slug manualmente
• Prezzo negativo → inserire 0 o un valore positivo
• JSON non valido negli attributi → controlla la sintassi

---

3c. Modifica Prodotto Esistente

1. Vai su http://localhost/admin/products
2. Trova il prodotto nella lista (usa la ricerca se necessario)
3. Clicca "Edit" sulla riga del prodotto
4. Modifica i campi desiderati
5. Clicca "Save Product"

Tutti i campi sono modificabili in qualsiasi momento.

Cambiare lo status da DRAFT a PUBLISHED è il modo per rendere il prodotto visibile nel negozio.

---

3d. Archiviare un Prodotto

L'archiviazione rende il prodotto invisibile nel negozio senza eliminarlo.

1. Dalla lista prodotti, clicca "Archive" sulla riga del prodotto
2. Oppure, entra in modifica e cambia lo Status in ARCHIVED

I prodotti archiviati non vengono eliminati: puoi ripristinarli in qualsiasi momento cambiando lo status in PUBLISHED.

Non esiste un'eliminazione definitiva dall'interfaccia admin — l'archiviazione è l'operazione più "definitiva" disponibile.

---

3e. Immagini prodotto

La sezione Images appare in fondo alla pagina di modifica di un prodotto già salvato (non durante la creazione iniziale).

Formato consigliato

Proprietà	Valore
Proporzione	1:1 (quadrata)
Risoluzione minima	800 × 800 px
Risoluzione consigliata	1200 × 1200 px
Formati accettati	JPEG, PNG, WebP
Dimensione massima	5 MB per file

Il negozio mostra sempre le immagini in formato quadrato ritagliando al centro. Se carichi un'immagine rettangolare, le parti ai lati (o in alto/basso) verranno tagliate e non saranno visibili.

Esempio: una foto 1600×900 px (orizzontale) verrà mostrata ritagliata al centro come un quadrato 900×900 px — i bordi sinistro e destro spariranno.

Come aggiungere immagini

1. Crea e salva il prodotto → il sistema ti reindirizza alla pagina di modifica
2. Scorri fino alla sezione "Images" in fondo al form
3. Clicca "Aggiungi immagini" e seleziona uno o più file
4. Le anteprime appaiono subito nella griglia — il preview è quadrato, identico a come l'immagine apparirà nel negozio
5. Puoi caricare più immagini: la prima è quella mostrata nelle card del catalogo

Come eliminare un'immagine

Passa il mouse sopra l'anteprima e clicca il pulsante ✕ che appare nell'angolo in alto a destra.

---

4. Tipi di Prodotto (Product Types)

URL: http://localhost/admin/product-types

I Product Types definiscono la struttura degli attributi custom per categoria di prodotti. Vanno creati prima dei prodotti.

Cos'è un Product Type

Un tipo di prodotto è essenzialmente uno schema che dice: "i prodotti di questa categoria hanno questi attributi". Esempio:

• Tipo "Abbigliamento" → attributi: colore, taglia, materiale
• Tipo "Elettronica" → attributi: marca, RAM, storage, display
• Tipo "Libri" → attributi: autore, ISBN, editore, pagine

Come creare un Product Type

1. Vai su http://localhost/admin/product-types
2. Clicca "New Product Type"
3. Compila:
   • Name: nome del tipo (es. Abbigliamento)
   • Schema (JSON): definizione degli attributi in formato JSON Schema

Esempio di schema:

{
  "type": "object",
  "properties": {
    "colore": { "type": "string" },
    "taglia": { "type": "string" },
    "materiale": { "type": "string" }
  }
}

4. Clicca "Save"

Modifica e gestione

• I tipi esistenti si possono modificare cliccando "Edit"
• Modificare uno schema non altera i prodotti già creati con quel tipo
• Usare nomi chiari e descrittivi per ritrovarli facilmente

---

5. Categorie

URL: http://localhost/admin/categories

Le categorie organizzano il catalogo e aiutano i clienti a navigare il negozio.

Struttura gerarchica

Le categorie supportano una gerarchia padre/figlio:

Abbigliamento (padre)
├── Uomo
│   ├── T-shirt
│   └── Pantaloni
└── Donna
    ├── Vestiti
    └── Scarpe

Creare una categoria

1. Vai su http://localhost/admin/categories
2. Clicca "New Category"
3. Compila:
   • Name (obbligatorio): nome della categoria (es. Sneaker)
   • Slug (obbligatorio): generato automaticamente, usato nell'URL
   • Parent Category (opzionale): seleziona la categoria padre per creare una sottocategoria
4. Clicca "Save"

Modificare una categoria

Clicca "Edit" accanto alla categoria, modifica i campi, salva.

Eliminare una categoria

• Clicca "Delete" accanto alla categoria
• Attenzione: non è possibile eliminare una categoria se ha prodotti assegnati. Riassegna prima i prodotti ad altre categorie.

---

6. Ordini

URL: http://localhost/admin/orders

Gestisci tutti gli ordini ricevuti nel negozio.

Lista ordini

La lista mostra tutti gli ordini con:

• ID ordine
• Cliente (nome ed email)
• Data
• Importo totale
• Stato corrente

Filtrare per stato

Usa il menu "Filter by status" per vedere solo gli ordini in un determinato stato:

Stato	Descrizione
PENDING	Ordine creato, pagamento non ancora completato
PAID	Pagamento ricevuto, in attesa di evasione
FULFILLED	Ordine evaso e spedito al cliente
CANCELLED	Ordine annullato
REFUNDED	Rimborso effettuato

Dettaglio ordine

Clicca su un ordine per aprire il dettaglio. Trovi:

• Dati cliente: nome, email, indirizzo di spedizione
• Prodotti ordinati: lista articoli con quantità e prezzo unitario
• Riepilogo economico:
  • Subtotale
  • Tasse
  • Spedizione
  • Totale
• Dati pagamento: provider (Stripe), ID transazione, data pagamento

Aggiornare lo stato di un ordine

1. Apri il dettaglio dell'ordine
2. Trova il menu "Update Status"
3. Seleziona il nuovo stato
4. Clicca "Update"

Flusso tipico di un ordine:

PENDING → PAID → FULFILLED

In caso di problemi:

PAID → CANCELLED → REFUNDED

---

7. Clienti

URL: http://localhost/admin/customers

Visualizza tutti i clienti registrati nel negozio.

Informazioni disponibili

Per ogni cliente viene mostrato:

• Email e nome
• Stato verifica email: verificata o non verificata
• Numero di ordini effettuati
• Data registrazione

Cosa puoi fare

La sezione clienti è attualmente in sola lettura: puoi visualizzare i clienti ma non modificarli o eliminarli dall'interfaccia admin.

Per operazioni avanzate sui clienti (reset password, eliminazione account) è necessario intervenire direttamente sul database.

---

8. Recensioni

URL: http://localhost/admin/reviews

Modera le recensioni lasciate dai clienti sui prodotti.

Stati delle recensioni

Stato	Descrizione
PENDING	Recensione appena inviata, in attesa di moderazione
APPROVED	Recensione approvata e visibile nel negozio
HIDDEN	Recensione nascosta (spam, contenuto inappropriato)

Filtrare le recensioni

Usa il filtro per stato per vedere solo le recensioni che richiedono attenzione (es. solo PENDING).

Moderare una recensione

Ogni recensione mostra:

• Prodotto a cui è riferita
• Valutazione in stelle (1-5)
• Testo della recensione
• Cliente che l'ha scritta
• Data

Azioni disponibili:

• Approve → rende la recensione visibile nel negozio
• Hide → nasconde la recensione (non viene eliminata)
• Reset to Pending → riporta la recensione in stato di attesa

Best practice: approva rapidamente le recensioni PENDING per mantenere il negozio attivo e credibile. Nascondi solo recensioni con contenuto offensivo o spam.

---

9. Utenti Admin

URL: http://localhost/admin/admin-users

Gestisci gli account che possono accedere al pannello admin.

Ruoli disponibili

Ruolo	Permessi
ADMIN	Accesso completo al pannello, gestione prodotti/ordini/clienti
OWNER	Come ADMIN, più la possibilità di gestire altri admin e le impostazioni di sistema

Creare un nuovo admin

1. Vai su http://localhost/admin/admin-users
2. Clicca "New Admin User"
3. Compila:
   • Name: nome del nuovo admin
   • Email: email di accesso (deve essere unica)
   • Password: password iniziale (il sistema richiederà il cambio al primo login)
   • Role: seleziona ADMIN o OWNER
4. Clicca "Create"

Il nuovo admin riceverà le credenziali e dovrà cambiare la password al primo accesso.

Eliminare un admin

Clicca "Delete" accanto all'admin da rimuovere.

Attenzione: non è possibile eliminare il proprio account. Non eliminare l'ultimo account OWNER per non perdere l'accesso al pannello.

---

10. Impostazioni

URL: http://localhost/admin/settings

Configura le impostazioni globali del negozio.

Campi configurabili

Campo	Descrizione	Esempio
Site Name	Nome del negozio	Il Mio Negozio
Site Description	Descrizione breve	Il miglior ecommerce italiano
Support Email	Email di contatto per i clienti	support@mionegozio.it
Currency	Valuta di default	EUR
Tax Rate	Aliquota IVA in percentuale	22 (per il 22%)

Come modificare

1. Vai su http://localhost/admin/settings
2. Modifica i campi desiderati
3. Clicca "Save Settings"

Le modifiche hanno effetto immediato su tutto il negozio.

---

11. Flusso Consigliato per Iniziare

Se stai configurando il negozio da zero, segui quest'ordine:

Step 1 — Configura le impostazioni base

Vai su Impostazioni e imposta nome negozio, valuta e aliquota IVA.

Step 2 — Crea i Product Types

Vai su Product Types e crea i tipi per le tue categorie di prodotti. Esempio: "Abbigliamento", "Accessori", "Scarpe".

Step 3 — Crea le Categorie

Vai su Categorie e crea la struttura del catalogo. Esempio: "Uomo > T-shirt", "Donna > Vestiti".

Step 4 — Aggiungi i Prodotti

Vai su Prodotti → New Product e compila il form. Inizia con DRAFT per testare, poi passa a PUBLISHED.

Step 5 — Verifica il negozio

Apri http://localhost nel browser (non /admin) e naviga il negozio come farebbe un cliente. Controlla che i prodotti pubblicati siano visibili e che le categorie siano corrette.

Step 6 — Configura i pagamenti

Aggiungi le chiavi Stripe test nel file .env per testare il flusso di acquisto completo.

---

Riferimenti rapidi

Sezione	URL
Dashboard	http://localhost/admin
Prodotti	http://localhost/admin/products
Nuovo Prodotto	http://localhost/admin/products/new
Product Types	http://localhost/admin/product-types
Categorie	http://localhost/admin/categories
Ordini	http://localhost/admin/orders
Clienti	http://localhost/admin/customers
Recensioni	http://localhost/admin/reviews
Admin Users	http://localhost/admin/admin-users
Impostazioni	http://localhost/admin/settings
Email (Mailpit)	http://localhost:8025