Gestione Categorie e Sottocategorie Prodotti

Panoramica

Il sistema di categorie prodotto è ora completamente gestibile tramite database. Gli utenti possono creare, modificare e disattivare categorie e sottocategorie tramite l’interfaccia di amministrazione.

Struttura Database

Modello: ProductCategory

{
  _id: ObjectId,
  name: string,              // Nome interno (es: "Food", "Beverage")
  displayName: string,       // Nome visualizzato (es: "Alimenti", "Bevande")
  description?: string,      // Descrizione della categoria
  subcategories: [           // Array di sottocategorie
    {
      name: string,
      isActive: boolean
    }
  ],
  isActive: boolean,         // Se la categoria è attiva
  allowsSubcategories: boolean, // Se permette sottocategorie
  tenant_id: ObjectId,       // Multi-tenant
  createdAt: Date,
  updatedAt: Date
}

Funzionalità

1. Inizializzazione Categorie

Al primo accesso, l’utente può inizializzare le categorie di default:

• Food (Alimenti)
• Beverage (Bevande)
• Attrezzature - con 8 sottocategorie
• Materie di consumo
• Altro - con 15 sottocategorie

Percorso: /impostazioni/categorie-prodotto

2. Gestione Categorie

L’interfaccia permette di:

• ✅ Creare nuove categorie
• ✅ Modificare categorie esistenti
• ✅ Attivare/Disattivare categorie
• ✅ Gestire sottocategorie
• ✅ Visualizzare in modo espandibile le categorie con sottocategorie

3. Gestione Sottocategorie

Per categorie che supportano sottocategorie:

• ✅ Aggiungere nuove sottocategorie
• ✅ Rimuovere sottocategorie
• ✅ Attivare/Disattivare sottocategorie
• ✅ Le sottocategorie inattive non sono visibili nei selettori

4. Utilizzo nei Prodotti

Quando modifichi un prodotto:

1. Seleziona la categoria principale dal menu a tendina
2. Se la categoria supporta sottocategorie, appare automaticamente il campo sottocategoria
3. Puoi selezionare una sottocategoria o lasciare vuoto

API Endpoints

GET /api/product-categories

Recupera tutte le categorie per il tenant corrente.

Query Parameters:

• id - ID categoria specifica
• includeInactive - Include categorie disattivate (default: false)

POST /api/product-categories

Crea una nuova categoria.

Body:

{
  "name": "NuovaCategoria",
  "displayName": "Nuova Categoria",
  "description": "Descrizione...",
  "allowsSubcategories": true,
  "subcategories": [{ "name": "Sottocategoria 1", "isActive": true }],
  "isActive": true
}

PUT /api/product-categories

Aggiorna una categoria esistente.

Body:

{
  "_id": "categoryId",
  "displayName": "Nome Aggiornato",
  ...
}

DELETE /api/product-categories?id={id}

Disattiva una categoria (soft delete).

POST /api/product-categories/seed

Inizializza le categorie di default per il tenant corrente.

Script di Migrazione

Per inizializzare le categorie per tenant esistenti:

node scripts/seed-product-categories.js

Lo script:

• Trova tutti i tenant nel database
• Verifica se hanno già categorie
• Crea le categorie di default solo per tenant senza categorie
• Fornisce un report dettagliato

Componenti

CategorySubcategorySelector

Componente intelligente per la selezione di categoria e sottocategoria.

Props:

{
  category?: string;
  subcategory?: string;
  onCategoryChange: (category: string) => void;
  onSubcategoryChange: (subcategory: string | undefined) => void;
  disabled?: boolean;
}

Caratteristiche:

• Carica dinamicamente le categorie dal database
• Mostra sottocategorie solo per categorie che le supportano
• Reset automatico sottocategoria quando si cambia categoria
• Loading state durante il caricamento

CategoryBadge

Badge colorato per visualizzare categoria e sottocategoria.

Props:

{
  category?: string;
  subcategory?: string;
  showSubcategory?: boolean;
}

Workflow Utente

Primo Accesso

1. Vai su Impostazioni → Categorie Prodotto
2. Clicca su “Inizializza Categorie”
3. Le categorie di default vengono create

Personalizzazione

1. Vai su Impostazioni → Categorie Prodotto
2. Clicca su ✏️ per modificare una categoria esistente
3. Oppure clicca su ”+ Nuova Categoria”
4. Configura:
   • Nome interno e nome visualizzato
   • Descrizione (opzionale)
   • Se permette sottocategorie
   • Aggiungi/rimuovi sottocategorie
   • Stato attivo/disattivo

Utilizzo nei Prodotti

1. Apri un prodotto in Prodotti Importati
2. Nella sezione “Gestione prodotto”
3. Seleziona categoria e sottocategoria
4. Salva le modifiche

Note Tecniche

• Multi-tenant: Ogni tenant ha le sue categorie
• Soft Delete: Le categorie eliminate vengono solo disattivate
• Validazione: Indice unico su (name, tenant_id)
• Performance: Indici su tenant_id e isActive
• Backward Compatible: I prodotti con categorie hardcoded continuano a funzionare

Categorie Default

Attrezzature (8 sottocategorie)

• Attrezzature per cucina
• Attrezzature per sala
• Attrezzature per bar
• Attrezzature per miscelazione
• Attrezzature per pasticceria
• Piccola attrezzatura
• Stoviglie e posateria
• Bicchieri e cristalleria

Altro (15 sottocategorie)

• Energia elettrica
• Gas
• Acqua
• Spese contabili
• Consulenze
• Servizi di pulizia
• Manutenzione
• Affitto e canoni
• Assicurazioni
• Marketing e pubblicità
• Telecomunicazioni
• Software e abbonamenti
• Materiale di cancelleria
• Smaltimento rifiuti
• Altro (generico)