docs: add comprehensive admin panel user guide (Italian)

Covers all admin sections with step-by-step instructions: login, dashboard, products (detailed field reference including image upload with aspect ratio guidance), product types, categories, orders, customers, reviews, admin users, settings, and recommended onboarding flow.
2026-05-18 17:54:19 +02:00
parent 676b173414
commit aab9d24800
1 changed files with 634 additions and 0 deletions
@@ -0,0 +1,634 @@
+# Guida Utente — Pannello Admin
+
+Guida completa all'uso del pannello di amministrazione dell'ecommerce platform.
+
+---
+
+## Indice
+
+1. [Accesso e primo login](#1-accesso-e-primo-login)
+2. [Dashboard](#2-dashboard)
+3. [Prodotti](#3-prodotti) ← **sezione principale**
+4. [Tipi di Prodotto](#4-tipi-di-prodotto-product-types)
+5. [Categorie](#5-categorie)
+6. [Ordini](#6-ordini)
+7. [Clienti](#7-clienti)
+8. [Recensioni](#8-recensioni)
+9. [Utenti Admin](#9-utenti-admin)
+10. [Impostazioni](#10-impostazioni)
+11. [Flusso consigliato per iniziare](#11-flusso-consigliato-per-iniziare)
+
+---
+
+## 1. Accesso e Primo Login
+
+### Avviare il server
+
+```bash
+docker compose up -d
+```
+
+Al primo avvio attendere 5-10 minuti. Per monitorare:
+
+```bash
+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:
+
+```json
+{
+  "colore": "Rosso",
+  "taglie_disponibili": ["S", "M", "L", "XL"],
+  "materiale": "100% cotone",
+  "lavaggio": "30°C"
+}
+```
+
+- Esempio per un prodotto elettronico:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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 |