Sistema di Gestione Magazzino - Implementazione Completata

📦 Panoramica

Il sistema di magazzino è stato completamente ristrutturato per funzionare con inventari snapshot e calcolo automatico dei consumi basato sulle vendite e le ricette.

✅ Cosa è stato implementato

1. API Backend

/api/inventory/current-stock (GET)

• Recupera l’ultimo snapshot di inventario
• Calcola il consumo per ogni prodotto basandosi su:
  • Prodotti vendibili che usano l’ingrediente
  • Quantità di ingrediente nella ricetta
  • Vendite effettuate dalla data dello snapshot
  • Dimensione della confezione (conversione da grammi a confezioni)
• Restituisce scorte attuali in unità di confezione

Esempio calcolo:

Burrata (conf. 500g)
Inventario 1 dic: 10 conf
Vendite:
  - 10 Carbonare (50g burrata) = 500g = 1 conf
  - 5 Insalate (100g burrata) = 500g = 1 conf
Consumo totale: 2 conf
Scorta attuale: 10 - 2 = 8 conf

2. Redux API

currentStockApi.ts

• Query getCurrentStock: recupera scorte calcolate
• Types completi per CurrentStockItem e Stats
• Integrato nel Redux store

3. Interfaccia Utente

Pagina Magazzino (/magazzino)

Nuove funzionalità:

• Card statistiche:
  • Totale prodotti tracciati
  • Valore totale giacenze
  • Prodotti con scorte basse
  • Prodotti esauriti
• Data ultimo inventario nel header
• Tabella con colonne:
  • Prodotto e fornitore
  • Inventario iniziale (dall’ultimo snapshot)
  • Consumato (dalle vendite)
  • Scorta attuale (calcolata)
  • Dimensione confezione
  • Prezzo per confezione
  • Valore totale
  • Status con colori (alto/medio/basso/esaurito)

Componenti Creati

• current-stock-columns.tsx: Definizione colonne tabella
• current-stock-data-table.tsx: DataTable con ricerca e paginazione

4. Sistema già esistente utilizzato

• ✅ InventorySnapshot model: già esistente e funzionante
• ✅ /api/inventory/snapshots (POST/GET): creazione e recupero inventari
• ✅ /magazzino/inventario: form per creare nuovi snapshot
• ✅ /magazzino/snapshots: storico inventari

🎯 Come Funziona

Flusso Completo

1. Primo Inventario

   • Vai su /magazzino/inventario
   • Aggiungi prodotti e conta le confezioni fisiche
   • Salva lo snapshot

2. Monitoraggio Continuo

   • La pagina /magazzino mostra le scorte calcolate
   • Ogni prodotto mostra:
     • Quantità iniziale dall’inventario
     • Consumo calcolato dalle vendite
     • Scorta attuale
   • Le scorte si aggiornano automaticamente con le nuove vendite

3. Nuovo Inventario Periodico

   • Esegui un nuovo conteggio fisico
   • Crea nuovo snapshot
   • Il sistema resetta i calcoli dal nuovo punto di partenza

Logica di Calcolo

Per ogni prodotto nell’inventario:

1. Trova tutti i SellingProducts che usano l'ingrediente nella ricetta
2. Per ogni SellingProduct:
   a. Leggi quantità ingrediente nella ricetta (es: 50g)
   b. Trova vendite dalla data snapshot in salesData
   c. Calcola grammi consumati = vendite × quantità_ricetta
3. Somma tutti i grammi consumati
4. Converti in confezioni: grammi_totali / dimensione_confezione
5. Scorta attuale = quantità_inventario - confezioni_consumate

📁 File Modificati/Creati

Nuovi File

src/app/api/inventory/current-stock/route.ts
src/store/api/currentStockApi.ts
src/app/(dashboard)/magazzino/current-stock-columns.tsx
src/app/(dashboard)/magazzino/current-stock-data-table.tsx
src/components/ui/data-table.tsx
docs/WAREHOUSE_MANAGEMENT.md
docs/WAREHOUSE_IMPLEMENTATION.md (questo file)

File Modificati

src/app/(dashboard)/magazzino/page.tsx - Completamente ristrutturato
src/store/index.ts - Aggiunto currentStockApi

🔧 Requisiti Tecnici

Dati Necessari

Per il corretto funzionamento, assicurati che:

1. Prodotti (Products):

   • quantity: dimensione confezione (es: 500 per 500g)
   • buyUnit: unità di acquisto (es: “confezione 500g”)
   • price e vat: per calcolo valore

2. Prodotti Vendibili (SellingProducts):

   • recipe: array con product_id e quantity
   • salesData: array con vendite mensili

3. Inventari (InventorySnapshot):

   • Almeno uno snapshot creato
   • Items con physical_count in confezioni

Dipendenze

Nessuna nuova dipendenza richiesta. Il sistema usa:

• MongoDB (già configurato)
• Redux Toolkit (già configurato)
• TanStack Table (già in package.json)
• Lucide Icons (già in uso)

🚀 Prossimi Passi

Setup Iniziale

1. Crea il primo inventario da /magazzino/inventario
2. Verifica che i prodotti abbiano quantity impostata
3. Controlla che le ricette siano complete

Test

1. Visita /magazzino - dovresti vedere le scorte calcolate
2. Verifica che i consumi siano ragionevoli
3. Crea un secondo inventario per testare il reset

Ottimizzazioni Future

• Cache dei calcoli per performance
• Notifiche automatiche scorte basse
• Previsioni consumo basate su storico
• Export Excel inventari
• Dashboard analytics avanzata

🐛 Troubleshooting

Nessun dato visualizzato

Causa: Nessun inventario creato Soluzione: Vai su /magazzino/inventario e crea il primo snapshot

Consumo a zero per tutti i prodotti

Cause possibili:

1. Nessuna vendita dopo l’inventario
2. Ricette mancanti nei SellingProducts
3. Campo quantity non impostato nei Products

Debug:

// Verifica ricette
db.sellingproducts.find({ "recipe.product_id": ObjectId("PRODUCT_ID") });
 
// Verifica vendite
db.sellingproducts.find({}, { name: 1, salesData: 1 });
 
// Verifica quantity
db.products.find({}, { name: 1, quantity: 1, buyUnit: 1 });

Scorte negative

Causa: Più consumo di quanto registrato in inventario Comportamento: Il sistema imposta automaticamente minimo a 0 Soluzione: Esegui nuovo inventario fisico

📖 Documentazione

Per maggiori dettagli vedi:

• docs/WAREHOUSE_MANAGEMENT.md - Guida completa al sistema
• backend/models/InventorySnapshot.ts - Schema database
• src/app/api/inventory/current-stock/route.ts - Logica calcolo

💡 Best Practices

1. Frequenza Inventari:

   • Prodotti deperibili: settimanale
   • Prodotti secchi: mensile

2. Dimensioni Confezione:

   • Imposta sempre il campo quantity nei prodotti
   • Usa la stessa unità (grammi) per coerenza

3. Ricette Complete:

   • Verifica che ogni SellingProduct abbia recipe completa
   • Quantity in ricetta deve essere in grammi

4. Monitoraggio:

   • Controlla giornalmente status “basso”
   • Pianifica ordini basandoti su scorte attuali
   • Usa storico per identificare pattern

🎉 Conclusione

Il sistema di magazzino è ora completamente funzionale e basato su snapshot di inventario reali, con calcolo automatico dei consumi dalle vendite. Le scorte sono mostrate in unità di confezione per facilitare gli ordini ai fornitori.