MagoRevisited/README.md

Mago4 Demo - ERP Gestionale

Demo funzionante di un gestionale ERP ispirato a Mago4, realizzato con Python FastAPI.

🎯 Caratteristiche

• Interfaccia fedele a Mago4 — header blu, sidebar a moduli, menu a card con breadcrumb e tab, form documento con tab laterali e griglia righe
• Cruscotto aziendale orientato alle scadenze: banner allerta, KPI pagamenti/incassi scaduti, scadenze imminenti, Cose da Fare (paga/sollecita/ordina/conferma), previsione di cassa a 30 giorni, controllo fido clienti
• Anagrafiche — Clienti, Fornitori, Articoli (con P.IVA, codice fiscale, UM, IVA)
• Vendite — Ordini Cliente e Fatturazione: Fatture Immediate, DDT, Note di Credito, ProForma con calcolo imponibile/IVA/totale e stati documento (bozza → stampato → emesso)
• Acquisti — Ordini Fornitore
• Amministrazione — Scadenzario (partite aperte): incassi/pagamenti con data scadenza, stato (scaduta/in scadenza/aperta/saldata), registrazione incasso/pagamento, previsione di cassa
• Logistica/Magazzino — Movimenti di magazzino con causali carico/scarico che aggiornano realmente le giacenze, Causali (DebitCreditSign), Giacenze e valorizzazione
• API REST completamente documentata (Swagger su /docs)
• Database in-memoria con logica di business (facilmente migrabile a SQL)

Moduli ispirati al codice sorgente Mago4

La struttura dati e le funzionalità sono modellate sulle tabelle reali di Mago4:

• Fatturazione: MA_SaleDoc (InvoiceMng) — tipi documento, righe con sconto/IVA, stati Printed/Issued/PostedToInventory
• Magazzino: MA_InventoryEntries + MA_InventoryReasons (Inventory) — movimenti con causali e segno carico/scarico che aggiornano MA_ItemsBalances
• Scadenzario: MA_PyblsRcvbls + Details (AP_AR) — partite con InstallmentDate, Amount, DebitCreditSign, flag Closed/Collected

🚀 Quick Start

1. Installare dipendenze

pip install -r requirements.txt

2. Avviare l'applicazione

python main.py

L'app sarà disponibile su: http://127.0.0.1:8000

3. Accedere alle sezioni

• Dashboard: http://127.0.0.1:8000/
• API Docs: http://127.0.0.1:8000/docs
• Clienti: http://127.0.0.1:8000/customers
• Fornitori: http://127.0.0.1:8000/suppliers
• Articoli: http://127.0.0.1:8000/products
• Ordini Vendita: http://127.0.0.1:8000/sales-orders
• Ordini Acquisto: http://127.0.0.1:8000/purchase-orders
• Magazzino: http://127.0.0.1:8000/warehouse

📁 Struttura del Progetto

mago4-demo/
├── main.py                    # FastAPI app principale
├── models.py                  # Modelli dati (Pydantic)
├── database.py                # Database in-memoria
├── requirements.txt           # Dipendenze Python
├── templates/                 # Template HTML (Jinja2)
│   ├── base.html             # Layout con sidebar
│   ├── dashboard.html        # Dashboard KPI
│   ├── customers.html        # Gestione clienti
│   ├── suppliers.html        # Gestione fornitori
│   ├── products.html         # Catalogo articoli
│   ├── sales_orders.html     # Ordini vendita
│   ├── purchase_orders.html  # Ordini acquisto
│   └── warehouse.html        # Magazzino
└── static/                    # Assets frontend
    ├── css/style.css         # Stili (colori Mago4)
    └── js/app.js             # Funzionalità JS

🎨 Design & Colori (ispirato a Mago4)

• Blu: #1976D2 (Azioni, statistiche)
• Arancione: #F57C00 (Avvisi, acquisti)
• Verde: #388E3C (Conferme, OK)
• Rosso: #D32F2F (Errori, sottosorta)

📊 Dati Inclusi

• 4 Clienti: Acme, TechFlow, European Logistics, Alpine Manufacturing
• 3 Fornitori: Global Components, Asia Electronics, Nordic Materials
• 5 Articoli: Widget, Connectors, Brackets, Bearings, Control Module
• 3 Ordini Vendita: SO-2024-0001/0002/0003
• 3 Ordini Acquisto: PO-2024-0001/0002/0003

🔌 API REST

Tutti gli endpoint sono auto-documentati su /docs (Swagger UI)

Principali endpoint:

• GET/POST /api/customers
• GET/POST /api/suppliers
• GET/POST /api/products
• GET/POST /api/sales-orders
• GET/POST /api/purchase-orders
• GET /api/warehouse/stats
• GET /api/info

🔄 Migrazione a SQL

Pronto per SQLAlchemy + SQL Server/PostgreSQL:

pip install sqlalchemy sqlmodel

Sostituire database.py con modelli SQLModel e aggiungere connection string.

⚙️ Tech Stack

• Backend: FastAPI (async Python)
• Template: Jinja2
• Validazione: Pydantic
• DB Demo: In-memoria (list)
• Frontend: HTML5 + CSS3 + JavaScript vanilla
• Icons: Material Design Icons
• Font: Roboto (Google Fonts)

⚠️ Note

• Demo con dati fittizi in-memoria
• Per produzione: aggiungere auth, DB reale, validazione completa, HTTPS
• Facilmente estendibile con nuovi moduli