Varianti, Modificatori e Extra

Il sistema di varianti permette di personalizzare i prodotti al momento dell'ordine: scelta della cottura, aggiunta di ingredienti, selezione della taglia. Le varianti sono gestite tramite Gruppi Varianti (variant-groups), entita indipendenti che possono essere associate a uno o piu prodotti.

Concetti Fondamentali

Gruppo Varianti

Un gruppo varianti definisce un set di opzioni tra cui l'operatore (o il cliente) puo scegliere. Ogni gruppo ha:

Campo	Descrizione	Esempio
groupId	Identificativo univoco	grp_cottura_carne
name	Nome visualizzato	Cottura
type	Tipo di selezione	SINGLE o MULTIPLE
isRequired	Obbligatorio per procedere	true
minSelection	Selezioni minime	1
maxSelection	Selezioni massime	1 (per SINGLE), 5 (per MULTIPLE)
options	Array di opzioni disponibili	vedi sotto

Tipo SINGLE vs MULTIPLE

• SINGLE: l'operatore deve scegliere esattamente una opzione (es. cottura: al sangue / media / ben cotta)
• MULTIPLE: l'operatore puo scegliere piu opzioni simultaneamente (es. topping pizza: olive, funghi, prosciutto)

Opzione

Ogni opzione all'interno di un gruppo contiene:

Campo	Descrizione	Esempio
optionId	Identificativo univoco	opt_media
name	Nome visualizzato	Media Cottura
priceDelta	Sovrapprezzo o sconto	0 (nessun extra) o 1.50
action	Modifica alla ricetta	NONE, ADD, REMOVE, SUBSTITUTE
isDefault	Selezionata per default	false
displayOrder	Ordine di visualizzazione	1

Creazione di un Gruppo Varianti

Dalla Console Admin

1. Accedere a Catalogo > Gruppi Varianti > Nuovo Gruppo
2. Compilare:
   • Nome: es. Cottura Carne
   • Tipo: SINGLE (scelta singola)
   • Obbligatorio: Si
   • Min selezioni: 1, Max selezioni: 1
3. Aggiungere le opzioni:
   • Al Sangue -- priceDelta: 0
   • Media -- priceDelta: 0
   • Ben Cotta -- priceDelta: 0
4. Salvare

Esempio: Extra con Sovrapprezzo

Per un gruppo "Topping Pizza" con extra a pagamento:

1. Creare gruppo con tipo MULTIPLE, isRequired: false, maxSelection: 5
2. Aggiungere opzioni:
   • Mozzarella di Bufala -- priceDelta: 2.00, action: ADD
   • Prosciutto Crudo -- priceDelta: 1.50, action: ADD
   • Senza Olive -- priceDelta: 0, action: REMOVE

Associazione ai Prodotti

I gruppi varianti si collegano ai prodotti tramite il campo variantGroups, un array di groupId:

{
  "sku": "BISTECCA-FIORENTINA",
  "name": "Bistecca alla Fiorentina",
  "variantGroups": ["grp_cottura_carne", "grp_contorno"]
}

Quando l'operatore aggiunge il prodotto al carrello, il sistema presenta automaticamente i gruppi varianti associati. Se almeno un gruppo e isRequired: true, l'operatore non puo procedere senza completare la selezione.

Varianti Ereditate dalla Categoria

Le categorie supportano il campo defaultVariantGroups: un array di groupId applicati automaticamente a tutti i prodotti della categoria. Questo evita di configurare le stesse varianti su ogni singolo prodotto.

Ad esempio, assegnando grp_cottura_carne alla categoria Carni alla Griglia, tutti i prodotti di quella categoria erediteranno il gruppo cottura.

Azioni sugli Ingredienti (BOM)

Le opzioni con campo action diverso da NONE modificano la distinta base del prodotto:

Azione	Effetto	Campi necessari
ADD	Aggiunge ingrediente	ingredientSku, quantity, uom
REMOVE	Rimuove ingrediente	ingredientSku, quantity
SUBSTITUTE	Sostituisce un ingrediente	ingredientIdToRemove, ingredientIdToAdd, quantita

Queste modifiche si propagano al magazzino quando il modulo warehouse e attivo, decrementando le giacenze in base alla ricetta modificata.

Calcolo Prezzo Finale

Quando l'operatore seleziona le varianti, il sistema calcola il prezzo finale sommando tutti i priceDelta:

Prezzo base:  Margherita        8.00 EUR
  + Bufala:   priceDelta       +2.00 EUR
  + Crudo:    priceDelta       +1.50 EUR
  ---
  Prezzo finale:               11.50 EUR

L'azione variant-groups.applyVariantsToProduct esegue questo calcolo lato server, restituendo originalPrice, finalPrice, priceDelta e le modifiche BOM.

Validazione Selezioni

Il sistema valida automaticamente le selezioni dell'operatore:

• Se isRequired: true e minSelection: 1, almeno un'opzione deve essere selezionata
• Se maxSelection: 3, non si possono selezionare piu di 3 opzioni
• Per tipo SINGLE, maxSelection e automaticamente 1

In caso di violazione, il sistema restituisce un errore descrittivo e impedisce l'aggiunta al carrello.

Pressione Lunga in Cassa

In cassa, la pressione lunga su un tasto prodotto (CART_ADD) forza l'apertura del pannello varianti anche se il prodotto non ha gruppi obbligatori. Questo permette all'operatore di aggiungere modifiche occasionali senza rendere le varianti obbligatorie per tutti gli ordini.

FAQ

Posso usare lo stesso gruppo varianti per piu prodotti? Si. I gruppi varianti sono entita indipendenti. Lo stesso gruppo Cottura Carne puo essere associato a bistecca, hamburger e qualsiasi altro prodotto.

Come configuro taglie diverse con prezzi diversi? Creare un gruppo SINGLE con isRequired: true. Ogni opzione rappresenta una taglia con il suo priceDelta. Ad esempio: Piccola (0), Media (+1.00), Grande (+2.00).

Come gestisco "senza" un ingrediente (es. senza cipolle)? Creare un'opzione con action: REMOVE, ingredientSku corrispondente e priceDelta: 0. L'opzione apparira nella lista dei modificatori e, se il magazzino e attivo, non verranno scalate le cipolle dalla giacenza.

Le varianti appaiono sullo scontrino? Si. Le varianti selezionate vengono stampate sotto il nome del prodotto nella comanda cucina e nel preconto. La formattazione dipende dal template di stampa configurato.

Vedi Anche

• Catalogo Prodotti -- associazione variantGroups ai prodotti
• Categorie Gerarchiche -- defaultVariantGroups per categoria
• Template Stampe -- formattazione varianti sulle stampe
• Layout Cassa -- comportamento tasti con varianti