Il simulatore WMS Agile è un ambiente di simulazione discreta event-driven che replica l'intera operatività di un magazzino enterprise — incluse le interazioni 4PL multi-tenant — all'interno del browser, senza alcun backend dedicato alla simulazione.
| Modulo | File | Responsabilità | Thread |
|---|---|---|---|
| SimEngine | simulator.js | Motore eventi, stato simulazione, emit | Worker |
| SimData | simulator-data.js + S2-S7 | Dati statici: SKU, clienti, fornitori, SLA profiles | Worker |
| SimUI | simulator-ui.js | Rendering cockpit, gaming, toast, mappa | Main |
| SimRecorder | simulator-recorder.js | Frame capture event-driven, replay slider, AI | Main |
| SimIDB | simulator-idb.js | IndexedDB API call logger, latency stats | Main |
| SimCoverage | simulator-coverage.js | Feature tracker 69 funzionalità | Main |
| SimWorkerInit | sim-worker-init.js | Bridge main↔worker, postMessage protocol | Main |
| SimWorker | sim-worker.js | Worker entry point, stub browser API | Worker |
| SimSetup | simulator-setup.js | Login, init ambiente, overlay step 1-3 | Main |
| SimScenarios | simulator-scenarios.js | Catalogo scenari, factory per S1-S7 | Main |
| WarehouseMap | warehouse-map.js | SVG planimetria interattiva, layer, zone | Main |
simulator-ui.js deve essere caricato per ultimo perché al momento del suo caricamento chiama SimUI.start() che si aspetta tutti gli altri moduli già disponibili. Alterare l'ordine causa errori ReferenceError: SimEngine is not defined o simili.
All'avvio, il simulatore mostra un overlay di configurazione a 3 step prima di entrare nel cockpit. Questo overlay consente di scegliere scenario, modalità e funzionalità avanzate.
Griglia di card (una per scenario S1-S7). Ogni card mostra nome, settore industriale e numero di facility/tenant. Cliccando una card si avanza allo step 2.
Continua la sessione precedente. Recupera token JWT da sessionStorage, stato simulazione da localStorage.
Consigliato per demo continuative o simulazioni lunghe (>1 ora).
Cancella tutti i dati del tenant demo e ri-inizializza da zero: ordini, stock, missioni, alert.
Usare prima di una demo con pubblico per avere dati puliti.
| Opzione | Default | Descrizione |
|---|---|---|
| Audit Trail | OFF | Abilita SimRecorder: pulsante REC nell'header, cattura frame per ogni evento, replay + AI summary |
| Snapshot AI | OFF | Auto-screenshot cockpit su eventi critici (bug, stock_low, sla_breach…) con upload a Claude Vision |
| Mission Planner | ON | Dispatcher automatico missioni AGV: crea missioni FEFO e stock-pick senza intervento manuale |
| UOM Packaging | ON | Unità di misura avanzate (pallet, cartone, pz) nelle transazioni inbound/outbound |
| Calendar | OFF | Integrazione calendar-ms per festività 12 paesi — blocca appuntamenti su giorni non lavorativi |
| Durata (giorni) | 90 | Numero di giorni simulati al termine dei quali la simulazione si ferma automaticamente |
| Zona header | Componenti | Funzione |
|---|---|---|
| Sinistra | Logo + Titolo + Nome scenario | Identità visiva, scenario attivo |
| Facility tabs | A · B · C · D · E | Switcha la vista sulla facility selezionata. Ogni tab mostra i KPI della facility (es. A=NORD, B=SUD, C=PHARMA GDP, D=ECOMM, E=RETURNS) |
| Speed controls | 1× 2× 5× 10× 25× 50× 100× | Moltiplicatore velocità simulazione. 50× = 1 giorno simulato ogni ~28 min reali |
| ▶ / ⏸ | PLAY / PAUSA | Avvia o congela il motore. Lo stato viene preservato |
| Destra — pulsanti | 🕐 Orologio · ⭐ Score · COV · REC · REPLAY · SNAP · CLR · RESET · INJECT | Vedi sotto |
Sotto l'header, una barra orizzontale mostra il flusso operativo in tempo reale con 5 stage e frecce animate:
Ogni stage mostra un dot pulsante (evento in corso), un delta "+1" animato e il contatore cumulativo della sessione.
Planimetria interattiva del magazzino con 12 zone colorate per tipo (receiving, storage, picking, packing, shipping, quarantine, returns).
Layer chips — selezionabili via bottoni sopra la mappa:
FLOW — frecce animate dei flussi merceTRAIL — scia percorsi AGV recentiHEAT — heatmap occupazione bin (rosso = pieno)MISS — posizione missioni attive in corsoSCAN — flash scanner su eventi barcodeAMB — overlay temperatura ambiente (cold chain)Click su zona → drilldown panel a destra con dettaglio: bin count, occupazione %, temperatura, missioni in zona.
Un pannello slide-in da destra che appare quando si clicca una zona sulla mappa SVG. Mostra dettaglio zona: bin disponibili, % occupazione, temperatura attuale, elenco missioni in quella zona, ultimi movimenti.
Il pannello inferiore occupa ~30% dell'altezza cockpit ed è suddiviso in 5 tab ridimensionabili tramite drag verticale.
Event log in tempo reale. Ogni riga ha un colore per livello:
info — eventi ordinari (ordine creato, missione avviata)success — completamenti positivi (spedizione OK, wave 100%)warning — situazioni da monitorare (stock basso, SLA a rischio)error — anomalie (bug rilevato, scadenza FEFO)critical — emergenze (guasto equipment, customs hold)Buffer circolare: max 500 entry, le più vecchie vengono eliminate automaticamente per evitare memory leak su run lunghi. Bottone CLR per svuotare.
Lista dettagliata delle missioni AGV con: tipo, stato, agente assegnato, bin origine/destinazione, percentuale completamento.
Bottoni stress test (utili in demo per mostrare resilienza operativa):
Dopo un guasto si può osservare: toast rosso "Equipment breakdown", KPI OEE% che scende, missioni riassegnate ad altri AGV, alert critico nel log.
Lista dei discrepanze rilevate automaticamente dal motore di simulazione — es. stock spedito senza wave associata, missione completata su bin errato, quantità FEFO non rispettata.
Ogni bug mostra: expected vs got, severity (warning / error / critical), timestamp simulato.
Il contatore bug nell'header si incrementa e cambia colore (arancione → rosso) al superamento di soglie.
Confronto Budget vs Venduto vs Spedito per SKU. Ogni prodotto ha una barra tricolore:
Mostra visivamente gap di fulfillment (venduto > spedito = arretrato) e gap commerciale (venduto < budget = sotto-performance).
Pannello a due colonne:
Feed degli eventi di audit dal backend reale (GET /api/audit/search). Filtrabile per tipo entità e azione. Mostra: chi ha fatto cosa, quando, su quale record.
Statistiche SimIDB in tempo reale: top 10 endpoint per latenza media, numero totale chiamate, tasso errori. Si aggiorna ad ogni apertura del tab.
infrastructure/test-simulator-apis.sh ma in modalità live e continua: ogni API call del simulatore viene misurata e aggregata automaticamente.
Il simulatore include 7 scenari progressivi (S1-S7) + un ottavo scenario speciale CUSTOM per dati reali. Ogni scenario è costruito sopra il precedente. S1 è il "motore base"; ogni scenario successivo aggiunge un layer di complessità senza rompere la "Giostra" sottostante.
Il cuore del simulatore è un ciclo a 4 fasi auto-alimentanti:
I KPI sono distribuiti su 3 griglie nel cockpit, visibili in base allo scenario attivo. Ogni KPI ha soglie di colore (verde/arancione/rosso) per visual management immediato.
| KPI | S1 | S2 | S3 | Unità | Soglia OK | Soglia Warning | Soglia Critica |
|---|---|---|---|---|---|---|---|
| 📦 Ordini spediti | ✓ | ✓ | ✓ | count | — | — | — |
| 🤖 Missioni robot | ✓ | ✓ | ✓ | count | — | — | — |
| 🚛 Camion ricevuti | ✓ | ✓ | ✓ | count | — | — | — |
| ⚠️ Alert attivi | ✓ | ✓ | ✓ | count | 0 | 1-3 | >3 |
| 🎯 Precisione pick | ✓ | ✓ | ✓ | % | ≥99% | 97-99% | <97% |
| 🐛 Bug rilevati | ✓ | ✓ | ✓ | count | 0 | 1-2 | >2 |
| ⏱️ SLA Compliance | — | ✓ | ✓ | % | ≥95% | 80-95% | <80% |
| ⚡ Equipment OEE | — | ✓ | ✓ | % | ≥85% | 70-85% | <70% |
| 💶 4PL Fatturato | — | ✓ | ✓ | € cum. | — | — | — |
| 🔴 In manutenzione | — | ✓ | ✓ | count | 0 | 1 | ≥2 |
| ↩️ Resi processati | — | ✓ | ✓ | count | — | — | — |
| 🚚 Carrier Pickup | — | ✓ | ✓ | count | — | — | — |
| 🔗 Filiera™ Attivi | — | — | ✓ | count | — | — | — |
| 👷 Labour KPI | — | — | ✓ | % | ≥80% | 60-80% | <60% |
| 🏗️ Yard Utilization | — | — | ✓ | % | <85% | 85-95% | ≥95% |
| 📦 Carton Utilization | — | — | ✓ | % | ≥75% | 50-75% | <50% |
| 🤖 WCS Dispatched | — | — | ✓ | count | — | — | — |
| 📄 EDI Received | — | — | ✓ | count | — | — | — |
| 📄 EDI Processed | — | — | ✓ | % | ≥95% | 80-95% | <80% |
✓ = KPI visibile in quel scenario · — = non disponibile
Il simulatore include un sistema di gamification che trasforma la demo in un'esperienza coinvolgente: achievement sbloccabili, combo multiplier, streaks e un punteggio cumulativo.
Ogni 3 missioni AGV completate consecutive senza errori viene mostrato un banner COMBO con moltiplicatore crescente:
Un bug nel tab BUG azzera la streak corrente.
Il punteggio nell'header si incrementa ad ogni evento positivo con un pop float animato (+10, +25, +50 punti a seconda dell'evento). Il punteggio è puramente visivo: dimostra all'audience il livello di "salute operativa" del magazzino.
SimRecorder è il sistema di registrazione e replay delle sessioni di simulazione. A differenza dei recorder time-based (un frame ogni N secondi), SimRecorder cattura un frame per ogni evento significativo del motore.
Ogni frame contiene:
idx — indice progressivot — timestamp simulato (ms)eventType — tipo evento (es. wave_completed)eventLabel — etichetta human-readablelevel — info / warning / error / criticalkpi — snapshot di tutti i KPI al momentoscore — punteggio correnteeq — stato equipment (OEE, breakdown)Apribile con il bottone REPLAY nell'header. Mostra:
Il pannello replay include un bottone "Analisi AI" che invia la sessione a Claude:
/api/ai/chat con prompt: "Analizza questa sessione del simulatore WMS e dammi insight sulle performance operative"Il bottone Export JSON scarica tutti i frame come wms-sim-session-{timestamp}.json per analisi offline o caricamento in BI tool.
SimIDB è il logger delle chiamate API fatte dal simulatore verso il backend WMS. Usa IndexedDB (non localStorage) per stare fuori dall'heap V8 — essenziale per sessioni lunghe senza OOM.
wms-sim-idbcalls{
method: "GET",
path: "/api/missions/:id",
status: 200,
latencyMs: 47,
ts: 1709123456789
}
I path con ID variabili vengono normalizzati per permettere statistiche aggregate:
| Path reale | Path normalizzato |
|---|---|
/api/missions/123 | /api/missions/:id |
/api/products/456 | /api/products/:id |
/api/outbound/orders/TRK-001 | /api/outbound/orders/:id |
| Metodo | Descrizione |
|---|---|
SimIDB.logCall(method, path, status, latencyMs) | Logga una chiamata API |
SimIDB.getCalls(limit) | Ultime N chiamate ordinate per timestamp |
SimIDB.getStats() | Statistiche aggregate: top endpoint, latency avg, error rate |
SimIDB.clearCalls() | Svuota il database |
SimIDB.countCalls() | Numero totale entry correnti |
SimIDB.init() | Inizializzazione async (chiamata automaticamente al caricamento) |
Il tab AUDIT mostra 3 card KPI da SimIDB:
Sotto le card: barchart dei top 10 endpoint per latenza media, utile per identificare colli di bottiglia del backend durante la demo.
Ogni chiamata della funzione api() nel simulatore logga automaticamente il risultato:
const _t0 = Date.now(); const res = await fetch(url, opts); SimIDB.logCall(method, path, res.status, Date.now() - _t0);
SimCoverage traccia in tempo reale quante delle 69 funzionalità WMS vengono esercitate durante una sessione di simulazione. È uno strumento pensato per dimostrare la breadth funzionale del sistema a prospect e manager.
SimCoverage.trackEvent(featureId) viene chiamato0/69 → 35/69 → 69/69| Categoria | Feature | Esempi |
|---|---|---|
| Inbound | 8 | Purchase Order, Receiving, QC, Put-away, FEFO, LPN, SSCC, Deconsolidation |
| Outbound | 10 | Sales Order, Wave Planning, Picking, Packing, Labelling, Carrier, Tracking, Return |
| Inventory | 8 | Stock Level, Lot Control, Serial, UOM, Bin Management, Cycle Count, Adjustment |
| Warehouse | 9 | Zone Management, Slotting, AGV Missions, Dock Scheduling, Operator, NCR, Sensor |
| 4PL / Multi-tenant | 7 | Tenant Isolation, 4PL Billing, SLA Profiles, Filiera™, Network Orders, EDI |
| AI / Analytics | 8 | AI Chat, Forecast, Demand Planning, Snapshot Vision, SSE Realtime, KPI Dashboard |
| Compliance | 6 | Audit Trail, GDPR, Cold Chain GDP, Cartonization, WCS, Calendar |
| Integration | 6 | Webhook e-commerce, TMS, REST API, JWT Auth, Multi-lingua, PWA mobile |
| Gaming / UX | 7 | Achievements, Combo, Score, SimRecorder, SimIDB, SimCoverage, Mappa SVG |
Il SimEngine (simulator.js) gira dentro un Web Worker (sim-worker.js), separato dal thread UI principale. Questo risolve un problema critico per demo lunghe: il timer throttling di Chrome.
Chrome riduce la frequenza dei timer (setTimeout, setInterval) nei tab non attivi a max 1Hz (invece dei normali 60Hz). Per un simulatore a 100× questo significa che il tempo simulato si ferma quasi completamente quando l'utente guarda un altro tab.
Con una simulazione di 90 giorni a 50×, il throttling faceva perdere ore di tempo simulato in pochi secondi di tab switching.
I Web Workers non sono soggetti al timer throttling. Il motore SimEngine gira nel Worker e continua a calcolare il tempo simulato alla velocità corretta indipendentemente da quale tab è visibile.
I Web Workers non hanno accesso a window, localStorage, sessionStorage. Il file sim-worker.js include stub per permettere a simulator.js (scritto per il browser) di girare nel Worker:
// Alias window → self
if (typeof window === 'undefined') self.window = self;
// localStorage stub (con sync al main thread)
const _lsData = {};
self.localStorage = {
getItem: (k) => _lsData[k] ?? null,
setItem: (k, v) => {
_lsData[k] = String(v);
self.postMessage({ type: '_ls_sync', key: k, val: v });
},
};
| Tipo messaggio | Payload | Effetto |
|---|---|---|
init | scenario, options | Inizializza SimEngine con lo scenario scelto |
start | — | Avvia il motore |
pause | — | Congela il motore (stato preservato) |
resume | — | Riprende dalla pausa |
setSpeed | multiplier (1-100) | Cambia velocità simulazione |
reset | — | Reset completo stato motore |
getState | id | Risponde con state_response (tutti i KPI) |
getLog | id | Risponde con log_response (ultimi eventi) |
getBugs | id | Risponde con bugs_response |
Il simulatore può catturare screenshot automatici del cockpit e inviarli a Claude per analisi visiva. Funzionalità abilitata dallo step 3 del setup (opzione "Snapshot AI").
html2canvas renderizza l'intero div #sim-cockpit (mappa SVG + pannelli + KPI) in un canvas HTML5/api/ai/snapshot con il PNG + metadati (scenario, KPI correnti, evento trigger)Uno snapshot viene catturato automaticamente (senza premere SNAP) per 8 tipi di eventi:
app/uploads/sim-snaps/ sul serverIl bottone SNAP 📸 nell'header cattura uno snapshot manuale in qualsiasi momento, utile per salvare un momento interessante durante una demo.
Quando sia Audit Trail che Snapshot AI sono attivi, ogni snapshot manuale viene anche salvato come frame in SimRecorder (con eventType: 'manual_snap'), così appare nel replay slider.
Il simulatore è parte integrante della strategia di test a 5 livelli di WMS Agile. In particolare, il tab AUDIT del simulatore implementa il test L4 in modalità live e continua.
| Livello | Script esterno | Equivalente nel simulatore |
|---|---|---|
| L1 Smoke | infrastructure/test-smoke.sh |
Header indicators: se i servizi sono down il simulatore non fa login e mostra errore visivo. Non sostituisce L1 ma dà feedback immediato. |
| L2 E2E | infrastructure/test-e2e.sh |
Ogni run del simulatore esegue de-facto un ciclo WMS completo (inbound → wave → pick → outbound). Non misura exit code ma esercita gli stessi path. |
| L3 PHPUnit | infrastructure/test-phpunit.sh |
❌ Non integrabile (richiede PHP + Docker). Solo via SSH. |
| L4 SimAPIs | infrastructure/test-simulator-apis.sh |
✅ Completamente integrato nel tab AUDIT via SimIDB. Ogni API call del simulatore viene misurata con latenza reale e aggregata per endpoint. |
| L5 Playwright | infrastructure/test-ui.sh |
❌ Non integrabile (browser che controlla un browser). |
| Stress Test | infrastructure/test-stress.sh |
⚠️ Parzialmente: i bottoni "🚻 Pausa Ops" e "🔧 Guasto" nel tab MISSIONI simulano scenari di carico. Per stress concorrente reale usare lo script esterno. |
./infrastructure/test-master.sh https://wms.agile.software # Variabili opzionali: WMS_SKIP_L3=1 ./infrastructure/test-master.sh # Salta PHPUnit WMS_VERBOSE=1 ./infrastructure/test-master.sh # Output completo WMS_SKIP_L5=1 ./infrastructure/test-master.sh # Salta Playwright
Genera un report HTML in /tmp/wms-test-report-{data}.html con risultati per livello, log e badge PASS/FAIL.
I tre girono in parallelo con & per massimizzare la velocità.
Se L1 fallisce viene emesso warning ma L2/L5 continuano.
Il file .gitea/workflows/wms-tests.yml esegue tutti i livelli ad ogni push su main o develop:
| Job CI | Livello | Dipendenza |
|---|---|---|
| smoke | L1 | — |
| phpunit-outbound | L3 | — |
| phpunit-inventory | L3 | — |
| phpunit-inbound | L3 | — |
| e2e | L2 | smoke |
| simulator-apis | L4 | smoke |
| playwright-ui | L5 | smoke |
| summary | — | tutti (if: always) |
Per analizzare le performance API dopo una demo, è possibile esportare i dati SimIDB:
// Nel browser console durante/dopo la demo:
const data = await SimIDB.getCalls(5000);
const blob = new Blob([JSON.stringify(data, null, 2)], {type:'application/json'});
const a = document.createElement('a');
a.href = URL.createObjectURL(blob);
a.download = 'wms-api-calls-' + Date.now() + '.json';
a.click();
Il Setup Wizard è una pagina standalone che guida utenti e prospect in 7 passi attraverso la configurazione e il lancio del simulatore. Accessibile da: wms.agile.software/sim-wizard.html
Animazione SVG "La Giostra", 5 feature card. Il prospect capisce immediatamente cosa fa il simulatore prima ancora di configurarlo.
Griglia S1–S7 + card CUSTOM "Dati Personalizzati". Selezionando CUSTOM si sblocca il passo 3. Scenari predefiniti saltano direttamente al passo 4.
Dropzone CSV (products / customers / suppliers) con PapaParse client-side + preview prime 5 righe. In alternativa: singolo file JSON. Template CSV scaricabili inline. Salvataggio server-side con ID univoco (POST /api/ai/sim-dataset).
Verifica automatica in parallelo (Promise.allSettled, timeout 6s) di 7 microservizi: auth, inventory, warehouse, inbound, outbound, report, ai. Indicatore ● verde/rosso per servizio. Warning se offline, non blocca il lancio.
Velocità: 1× / 5× / 10× / 25× / 50× / 100×. Durata: slider 7–365 giorni (default 90). Toggle: Audit Trail, Snapshot AI, Mission Planner (AGV).
Lista dataset server-side del tenant (GET /api/ai/sim-datasets). Card con nome, #prodotti/#clienti/#fornitori, data upload. Selezione dataset esistente invece di ricaricare il file.
Summary completo configurazione. Pulsante ▶ LANCIA SIMULAZIONE → redirect a simulator.html?scenario=CUSTOM&autolaunch=1&speed=50&days=90. I dati custom vengono salvati in sessionStorage e il simulatore si avvia automaticamente senza passare per il modal di selezione.
| Meccanismo | Dettaglio |
|---|---|
| URL params | ?scenario=CUSTOM&autolaunch=1&speed=50&days=90 |
| sessionStorage | wms_wizard_dataset → JSON {products, customers, suppliers}wms_wizard_speed → velocità selezionata (consumed + removed on use) |
| simulator.html init() | Legge URL params, chiama selectScenario('CUSTOM'), poi launch() dopo 250ms |
| SimScenario.load('CUSTOM') | Legge sessionStorage, fa override di window.SimData.PRODUCTS/CUSTOMERS/SUPPLIERS |
| Dataset API | POST/GET/DELETE /api/ai/sim-dataset(s), max 10 per tenant, FIFO rotation |
| Bind mount | /var/www/wms-agile/app/uploads → container wms-ai-ms (persistenza tra rebuild) |
WMS Agile · Guida Simulatore v3.1 · Marzo 2026
▶ Apri Simulatore · 🪄 Setup Wizard · Guida Funzionale · Playbook Demo · Gap SAP EWM
© 2026 Agile Technology S.r.l. — P.IVA 07776161213 · Privacy & Legal