diff --git a/ADMIN_GUIDE.md b/ADMIN_GUIDE.md new file mode 100644 index 0000000..27b05d9 --- /dev/null +++ b/ADMIN_GUIDE.md @@ -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 |