Categorie Gerarchiche (Materialized Path)

Le categorie organizzano i prodotti in una struttura ad albero. Il sistema utilizza il pattern Materialized Path: ogni categoria memorizza il percorso completo dalla radice, permettendo query efficienti sull'albero senza join ricorsivi.

Concetti Fondamentali

Ogni categoria possiede i seguenti campi chiave:

Campo	Descrizione	Esempio
categoryId	Identificativo slug univoco	birre_artigianali
name	Nome visualizzato	Birre Artigianali
path	Percorso completo dalla radice	/bevande/birre/birre_artigianali
level	Profondita nell'albero (0 = radice)	2
parentId	categoryId del genitore	birre
order	Ordine di visualizzazione tra fratelli	1

Il categoryId viene generato automaticamente dal nome come slug (minuscolo, spazi sostituiti da underscore, max 50 caratteri). Puo anche essere specificato manualmente.

Esempio di albero

Cibo (path: /cibo, level: 0)
  Pizze (path: /cibo/pizze, level: 1)
    Classiche (path: /cibo/pizze/classiche, level: 2)
    Speciali (path: /cibo/pizze/speciali, level: 2)
  Antipasti (path: /cibo/antipasti, level: 1)
Bevande (path: /bevande, level: 0)
  Birre (path: /bevande/birre, level: 1)

Creazione Categorie

Categoria Radice

1. Dalla console admin, accedere a Catalogo > Categorie > Nuova Categoria
2. Compilare:
   • Nome: es. Bevande
   • parentId: lasciare vuoto per una categoria radice
3. Il sistema calcola automaticamente path: /bevande e level: 0

Sotto-categoria

1. Cliccare Nuova Categoria
2. Compilare:
   • Nome: es. Birre Artigianali
   • parentId: selezionare birre dal dropdown
3. Il sistema calcola path: /bevande/birre/birre_artigianali e level: 2

Campi opzionali

• description: descrizione della categoria
• icon: nome icona Material (es. local_bar)
• color: colore esadecimale (es. #FF9800)
• mediaId: immagine della categoria
• displayInMenu: visibilita nel menu (default: true)
• excludeFromFoodCost: esclude i prodotti dal calcolo food cost
• defaultVariantGroups: gruppi varianti applicati automaticamente ai prodotti della categoria

Assegnazione Prodotti

I prodotti vengono assegnati a categorie tramite il campo categoryId, che corrisponde allo slug della categoria. Un prodotto appartiene a una sola categoria (tipicamente una foglia dell'albero).

Prodotto: "Margherita"
  categoryId: "classiche"
  -> appartiene a Cibo > Pizze > Classiche

suggerimento

Assegnare i prodotti alle categorie foglia (livello piu basso). La ricerca per categoria padre espande automaticamente ai figli.

Filtro Gerarchico dei Prodotti

Quando si filtra per una categoria padre, il sistema espande la ricerca a tutti i discendenti usando il path:

1. L'utente seleziona Pizze (categoryId: pizze)
2. Il backend cerca la categoria e ottiene path: /cibo/pizze
3. Cerca tutti i discendenti con path che inizia per /cibo/pizze/
4. Costruisce un filtro $in con tutti i categoryId trovati: ['pizze', 'classiche', 'speciali']
5. Restituisce i prodotti di tutte e tre le categorie

Questo avviene automaticamente nell'azione products.list quando si passa il parametro categoryId.

Spostamento Categorie

Per riorganizzare l'albero, si utilizza l'azione categories.move:

1. Specificare categoryId della categoria da spostare
2. Specificare newParentId del nuovo genitore (o omettere per portarla a radice)
3. Il sistema aggiorna il path e il level della categoria e di tutti i suoi discendenti

attenzione

Lo spostamento di una categoria con molti discendenti aggiorna tutti i documenti figli singolarmente. Per alberi molto profondi, pianificare l'operazione in orari di bassa attivita.

Visualizzazione ad Albero

L'azione categories.getTree restituisce la struttura nidificata completa, utile per i dropdown della console admin e per la navigazione in cassa:

[
  {
    "categoryId": "bevande",
    "name": "Bevande",
    "path": "/bevande",
    "level": 0,
    "children": [
      {
        "categoryId": "birre",
        "name": "Birre",
        "path": "/bevande/birre",
        "level": 1,
        "children": []
      }
    ]
  }
]

Nella console admin, il dropdown categorie utilizza una lista piatta (categoriesFlat) con indentazione visiva tramite il prefisso -- per ogni livello di profondita.

Visibilita per App e Kiosk

Le categorie supportano flag di visibilita aggiuntivi per i canali digitali:

• visibleOnApp: visibilita nell'app cliente per ordini online
• appOrder: ordine specifico per l'app (puo differire dall'ordine in cassa)
• displayInKiosk: visibilita sui totem self-service

Questi flag si gestiscono in blocco tramite le azioni categories.setAppVisibility e categories.updateAppOrder.

FAQ

Quanti livelli di profondita posso creare? Non c'e un limite tecnico alla profondita, ma si consiglia di non superare 3-4 livelli per mantenere la navigazione intuitiva in cassa e nell'app.

Posso eliminare una categoria con prodotti assegnati? La disattivazione (active: false) e preferibile all'eliminazione. I prodotti assegnati alla categoria non verranno piu filtrabili tramite essa, ma restano nel catalogo.

Come sincronizzo le categorie con le casse? L'endpoint categories.syncDown supporta il delta sync: passando lastSync vengono scaricate solo le categorie modificate dopo quella data.

Vedi Anche

• Catalogo Prodotti -- creazione e gestione articoli
• Varianti e Modificatori -- gruppi varianti ereditati dalle categorie
• Layout Cassa -- organizzazione prodotti per pagine nel layout