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](#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 |