ecommerce-platform/docs/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 euro/dollari, con decimali)
• Inserisci il prezzo nella valuta selezionata, con il punto come separatore decimale
• Esempi:
  • 19.99 → €19,99
  • 49.90 → €49,90
  • 100 → €100,00
• Valore minimo: 0
• Il sistema converte automaticamente in centesimi internamente (compatibilità con Stripe)

---

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 i campi (vedi sotto)
4. Clicca "Save"

Campi — Product Type

Name (obbligatorio)

• Campo: text
• Il nome del tipo di prodotto, visibile solo nell'admin
• Esempio: Abbigliamento, Elettronica, Libri
• Usa nomi chiari che descrivano la categoria merceologica

---

Slug (obbligatorio)

• Campo: text
• Identificatore univoco generato automaticamente dal nome
• Formato: solo lettere minuscole, numeri e trattini (es. abbigliamento, elettronica)
• Non può contenere spazi o caratteri speciali
• Viene usato internamente dal sistema per identificare il tipo — non è visibile ai clienti
• Non modificarlo dopo aver creato prodotti con questo tipo

---

Schema (JSON) (opzionale)

• Campo: textarea con formato JSON
• Definisce quali attributi personalizzati avranno i prodotti di questo tipo
• Usa il formato JSON Schema standard

Esempio per abbigliamento:

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

Esempio per elettronica:

{
  "type": "object",
  "properties": {
    "marca": { "type": "string" },
    "ram_gb": { "type": "number" },
    "storage_gb": { "type": "number" }
  }
}

Lo schema è una guida per te — il sistema non blocca l'inserimento di attributi non definiti nello schema.

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 i campi (vedi sotto)
4. Clicca "Save"

Campi — Categoria

Name (obbligatorio)

• Campo: text
• Il nome della categoria visibile ai clienti nel negozio
• Esempio: Sneaker, T-shirt Uomo, Smartphone
• Usa nomi brevi e chiari

---

Slug (obbligatorio)

• Campo: text
• Generato automaticamente dal nome
• Formato: solo lettere minuscole, numeri e trattini (es. sneaker, t-shirt-uomo)
• Viene usato nell'URL della categoria nel negozio: /category/sneaker
• Non modificarlo dopo aver pubblicato la categoria per evitare link rotti

---

Parent Category (opzionale)

• Campo: select (menu a tendina)
• Permette di creare una gerarchia padre/figlio
• Lascia vuoto per una categoria di primo livello (es. Abbigliamento)
• Seleziona una categoria esistente per creare una sottocategoria (es. Sneaker → padre: Scarpe)
• Puoi annidare più livelli (es. Running → padre: Sneaker → nonno: Scarpe)

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 i campi (vedi sotto)
4. Clicca "Create"

Il nuovo admin dovrà cambiare la password al primo accesso.

Campi — Admin User

Name (obbligatorio)

• Campo: text
• Nome e cognome dell'amministratore
• Visibile nella lista admin e nei log di audit
• Esempio: Mario Rossi

---

Email (obbligatorio)

• Campo: email
• Indirizzo email usato per accedere al pannello admin
• Deve essere unica — non è possibile avere due admin con la stessa email
• Esempio: mario.rossi@negozio.it

---

Role (obbligatorio)

• Campo: select
• Seleziona il livello di accesso:

Ruolo	Cosa può fare
ADMIN	Gestire prodotti, ordini, clienti, recensioni, categorie, tipi prodotto
OWNER	Tutto ciò che può fare ADMIN, più: gestire altri admin, modificare le impostazioni di sistema

Assegna OWNER solo a persone di fiducia — può modificare impostazioni critiche e creare/eliminare altri admin.

---

Password (obbligatorio)

• Campo: password
• Password temporanea assegnata al nuovo admin
• Deve rispettare i requisiti di sicurezza: minimo 12 caratteri, almeno una maiuscola, una minuscola, un numero e un simbolo
• Il sistema chiederà di cambiarla al primo accesso
• Esempio sicuro: Temp#2026Admin!

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.

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.

Campi — Impostazioni generali

Site Name

• Campo: text
• Il nome del negozio, mostrato nel titolo del browser, nelle email ai clienti e nel footer
• Esempio: Il Mio Negozio, ShopX Italia
• Tienilo breve e riconoscibile

---

Site Description

• Campo: text
• Breve descrizione del negozio, usata nei meta tag per i motori di ricerca (SEO)
• Esempio: Il miglior ecommerce di abbigliamento sportivo italiano
• Consigliato: massimo 160 caratteri

---

Support Email

• Campo: email
• Indirizzo email mostrato ai clienti per il supporto (es. nella pagina contatti, nelle email di conferma ordine)
• Esempio: supporto@mionegozio.it
• Assicurati che sia una casella monitorata

---

Default Currency

• Campo: text
• Valuta usata di default per i nuovi prodotti e per il negozio
• Valori accettati: EUR, USD, GBP (codice ISO 4217 a 3 lettere)
• Esempio: EUR
• Attenzione: cambiare la valuta dopo aver creato prodotti non converte automaticamente i prezzi esistenti

---

Tax Rate (%)

• Campo: number
• Aliquota IVA applicata agli ordini, espressa in percentuale
• Esempi:
  • 22 → IVA italiana al 22%
  • 10 → IVA ridotta al 10%
  • 0 → nessuna tassa applicata
• Il valore viene mostrato nel riepilogo dell'ordine al checkout

---

Campi — Footer

Testo copyright

• Campo: text
• Testo mostrato nel footer del negozio, solitamente l'indicazione del copyright
• Esempio: © 2026 Il Mio Negozio. Tutti i diritti riservati.
• Lascia vuoto per non mostrare nulla

---

Link footer (Footer Links)

• Campo: textarea con formato JSON
• Lista di link mostrati nel footer (es. Privacy Policy, Termini, Contatti)
• Formato: array JSON di oggetti con label (testo del link) e url (destinazione)
• Esempio:

[
  {"label": "Privacy Policy", "url": "/privacy"},
  {"label": "Termini e Condizioni", "url": "/termini"},
  {"label": "Contatti", "url": "/contatti"}
]

• Lascia [] per non mostrare link nel footer
• Gli URL possono essere relativi (/privacy) o assoluti (https://...)

---

Campi — Branding

Favicon

• Campo: file upload
• Icona del negozio mostrata nel tab del browser e nei preferiti
• Formati accettati: PNG, ICO, SVG, JPEG, WebP
• Dimensione massima: 1 MB
• Dimensione consigliata: 32×32 px o 64×64 px (quadrata)
• Come caricare: clicca "Scegli file", seleziona l'immagine, clicca "Upload Favicon"
• La favicon viene aggiornata immediatamente su tutte le pagine

---

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