docs: expand admin guide with field-by-field documentation

Aggiunta documentazione campo per campo per tutte le sezioni: Product Types, Categorie, Admin Users, Impostazioni (generale, footer, favicon). Corretto Base Price da centesimi a euro dopo la fix del form.
2026-05-19 09:17:38 +02:00
parent 7afb609386
commit 4a7cd9fbd4
1 changed files with 197 additions and 30 deletions
@@ -169,13 +169,14 @@ Il form è diviso in 4 sezioni.
 #### Sezione 2 — Pricing & Inventory

 **Base Price** *(obbligatorio)*
- Campo: `number` (valore in centesimi)
- **Attenzione:** il prezzo va inserito in centesimi, non in euro/dollari
+- Campo: `number` (valore in euro/dollari, con decimali)
+- Inserisci il prezzo nella valuta selezionata, con il punto come separatore decimale
 - Esempi:
-  - `1999` → €19,99
-  - `4990` → €49,90
-  - `10000` → €100,00
+  - `19.99` → €19,99
+  - `49.90` → €49,90
+  - `100` → €100,00
 - Valore minimo: `0`
+- Il sistema converte automaticamente in centesimi internamente (compatibilità con Stripe)

 ---

@@ -344,12 +345,35 @@ Un tipo di prodotto è essenzialmente uno schema che dice: "i prodotti di questa

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

-Esempio di schema:
+### 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:
 ```json
 {
  "type": "object",
@@ -361,7 +385,19 @@ Esempio di schema:
 }
 ```

-4. Clicca **"Save"**
+Esempio per elettronica:
+```json
+{
+  "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

@@ -395,12 +431,35 @@ Abbigliamento (padre)

 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
+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.
@@ -546,14 +605,48 @@ Gestisci gli account che possono accedere al pannello 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`
+3. Compila i campi (vedi sotto)
 4. Clicca **"Create"**

-Il nuovo admin riceverà le credenziali e dovrà cambiare la password al primo accesso.
+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

@@ -569,16 +662,6 @@ Clicca **"Delete"** accanto all'admin da rimuovere.

 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
@@ -587,6 +670,90 @@ Configura le impostazioni globali del negozio.

 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:
+```json
+[
+  {"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