📖 Introduzione

Panoramica del sistema Fastsign Calcolo Provvigioni

Fastsign CP e' il sistema per il calcolo automatico delle provvigioni mensili dei contractor Fastsign. L'applicazione consente di:

• Definire regole di calcolo per ogni voce canvas (servizio) di ciascuna sub-agenzia
• Configurare soglie, modificatori di prezzo e bonus
• Lanciare il calcolo automatico delle provvigioni per un mese specifico
• Visualizzare un'anteprima dettagliata dei risultati
• Gestire il ciclo di vita delle fatture (dalla bozza al pagamento)
• Monitorare i margini di profitto per contractor e sub
• Analizzare i gettoni medi confrontando incassato vs riconosciuto con delta per contractor/sub/mese
• Eseguire simulazioni what-if per prevedere l'impatto di modifiche alle regole

Architettura di base

L'applicazione e' composta da una singola pagina HTML che comunica con un backend basato su n8n workflows. I dati sono salvati in MySQL e le regole vengono cachate in Redis per prestazioni ottimali.

Struttura della navigazione

L'interfaccia e' organizzata in 11 sezioni accessibili dalla barra di navigazione superiore, piu' una sidebar laterale per la selezione di contractor e sub-agenzia.

🔐 Login e Autenticazione

Come accedere al sistema

All'apertura dell'applicazione viene mostrata la schermata di login. Per accedere:

1. Inserisci il tuo indirizzo email nel campo "Email"
2. Inserisci la tua password nel campo "Password"
3. Clicca il pulsante "Entra" oppure premi Invio

Logout

Per uscire dal sistema, clicca sulla chip utente in alto a destra nella barra di navigazione (mostra le tue iniziali e il nome). Un click effettua il logout immediato e mostra la schermata di login.

🧭 Navigazione

Come muoversi nell'applicazione

La barra di navigazione superiore (topbar) e' sempre visibile e contiene:

Elementi della topbar

• Logo "fastsign" — identifica l'applicazione
• 🏠 Dashboard — accesso rapido alla dashboard KPI con panoramica del sistema
• Gruppi di sezioni — i pulsanti sono organizzati in tre gruppi separati da linee verticali:
  • Operativo — Regole, Bonus, Calcola, Anteprima (lavoro quotidiano)
  • Analisi — Margini, Gettoni Medi, Simulazione (analisi dati)
  • Admin — Config, Fatture, Inviti, Non Mappati (configurazione e gestione)
• 🔍 Search globale — campo di ricerca rapida per trovare contractor, sub, regole e bonus (vedi sezione dedicata)
• 📖 Manuale — apre questo manuale in una nuova scheda
• 🌙 / ☀️ — toggle tema chiaro/scuro
• Chip utente — mostra iniziali e nome, cliccando si effettua il logout

📂 Sidebar Contractor / Sub

Seleziona il contractor e la sub-agenzia su cui lavorare

La sidebar sinistra mostra l'elenco di tutti i contractor con le rispettive sub-agenzie (sub) organizzate ad albero.

Filtro e navigazione

• Campo filtro — in cima alla sidebar. Digitando si filtrano in tempo reale sia i contractor che le sub. Solo le voci che contengono il testo cercato restano visibili; i gruppi senza risultati vengono nascosti automaticamente. I gruppi con risultati vengono espansi automaticamente per mostrare le sub che corrispondono
• ▴ Comprimi tutti — chiude tutti i gruppi contractor con un solo click
• ▾ Espandi tutti — apre tutti i gruppi contractor con un solo click
• Espandi/comprimi singolo — cliccando sul nome del contractor (freccia ▾ / ▸)
• Seleziona una sub — cliccando sul suo nome, la riga si evidenzia in blu. La selezione viene usata da Regole, Bonus e altre sezioni
• Persistenza — lo stato di espansione/compressione viene salvato nella sessione del browser

🔍 Search Globale

Trova velocemente qualsiasi elemento nel sistema

Il campo di ricerca globale si trova nella barra di navigazione superiore, tra i pulsanti di sezione e il link al manuale. Permette di cercare in tempo reale su tutti i dati caricati nell'applicazione senza dover navigare manualmente tra le sezioni.

Cosa si puo' cercare

• Contractor (contractor) — cerca per nome contractor. Click naviga alla sezione Config
• Sub-agenzia (sub) — cerca per nome sub. Mostra il percorso contractor > sub
• Regole service (service) — cerca per service_name. Click naviga alla sezione Regole
• Regole virtual (virtual) — cerca per service_name delle regole virtuali
• Bonus (bonus) — cerca per descrizione del bonus

Come usare la search

1. Clicca sul campo 🔍 nella topbar (o inizia a digitare — il campo si espande automaticamente da 180px a 260px)
2. Digita almeno 2 caratteri — i risultati appaiono istantaneamente in un dropdown
3. Ogni risultato mostra un tag colorato con il tipo (contractor, sub, service, virtual, bonus) e il percorso gerarchico
4. Clicca su un risultato per navigare direttamente alla sezione pertinente
5. Clicca fuori dal dropdown o cancella il testo per chiudere i risultati

🏠 Dashboard KPI

Panoramica KPI e stato del sistema a colpo d'occhio

La Dashboard e' accessibile tramite il pulsante 🏠 nella topbar ed e' la vista ideale per avere una panoramica immediata della situazione mensile. Mostra indicatori chiave di performance (KPI), alert operativi, ranking contractor e grafici.

Filtro mese

In alto a destra della sezione, un selettore mese (formato YYYY-MM) e il pulsante "Aggiorna" permettono di caricare i dati per il periodo desiderato. Al primo accesso viene pre-selezionato il mese corrente.

Card riassuntive

Quattro card mostrano i KPI principali del mese selezionato:

Dettaglio delle card

• Totale Incassato — somma degli importo_fatturazione di tutti i contratti del mese, incluso il surcharge BLUENERGY (+45€/pezzo sull'indiretta). Il sottotitolo mostra il gettone medio incassato per pezzo
• Totale Riconosciuto — somma dei calculated_price da invoice_details (anteprime/fatture). Il sottotitolo mostra il gettone medio riconosciuto per pezzo
• Margine — differenza tra incassato e riconosciuto. Colorato in verde se positivo, rosso se negativo. Il sottotitolo mostra la percentuale sul fatturato
• Produzione — totale pezzi prodotti nel mese. Il sottotitolo mostra il numero di contratti distinti

Alert operativi

Sotto le card KPI, un pannello alert mostra le situazioni che richiedono attenzione:

• ⏰ Regole in scadenza — numero di regole con valid_to entro i prossimi 30 giorni. Colore ambra
• ⚠️ Voci non mappate — numero di voci canvas senza regola associata (dal badge Non Mappati). Colore rosso

Ranking contractor e grafici

La parte inferiore della dashboard e' divisa in due colonne:

Ranking Contractor per Margine (colonna sinistra)

Tabella ordinata per margine decrescente con le colonne: Contractor, Incassato, Riconosciuto, Margine (€), Margine (%). Permette di identificare immediatamente i contractor piu' profittevoli e quelli critici.

Grafico a barre — Margine per Contractor (colonna destra)

Grafico a barre affiancate che confronta visivamente Incassato (blu) vs Riconosciuto (viola) per ogni contractor. L'asse Y mostra i valori in migliaia di euro (€k). Realizzato con Chart.js.

Grafico a ciambella — Distribuzione Pezzi

Sotto al ranking, un grafico donut mostra la distribuzione percentuale dei pezzi prodotti per contractor, con legenda a destra. Ogni contractor ha un colore univoco.

📏 Regole

Definisci come calcolare le provvigioni per ogni voce canvas

La sezione Regole e' il cuore del sistema. Ogni regola definisce come calcolare la provvigione per una specifica voce canvas (servizio) di una sub-agenzia.

Panoramica della sezione

Badge delle regole

Filtri temporali

Le pillole in alto filtrano le regole in base alla loro validita':

• 🟢 Attive — regole valide oggi (valid_from ≤ oggi < valid_to)
• 🔵 Future — regole che entreranno in vigore in futuro
• 🔴 Scadute — regole la cui validita' e' terminata
• Tutte — mostra tutte le regole senza filtro

Creare una nuova regola

1. Seleziona un contractor e sub dalla sidebar
2. Clicca "+ Nuova Regola"
3. Compila i campi nel modale che si apre
4. Clicca "Salva Regola"

Campi del modale regola

• Contractor — seleziona il contractor (pre-compilato se selezionato dalla sidebar)
• Sub — seleziona la sub-agenzia (dipende dal contractor scelto)
• Service Name — nome della voce canvas (es. EE_RESIDENZIALE_DOMESTICO)
• Tipo — service (voce canvas) o virtual (commissione non legata a canvas)
• Base Price — prezzo base opzionale, usato come riferimento per il calcolo DUAL/SINGLE
• Max Single Value — valore massimo per considerare il contratto SINGLE (opzionale)
• Dipende da — solo per regole virtual: condizioni separate da virgola con prefissi opzionali *: (storico) e !: (esclusione). Vedi sintassi completa
• Metric Key — solo per scope global: chiave della metrica da valutare
• Valid From — data di inizio validita'
• Valid To — data di fine validita' (default: 2038-01-01)

Soglie (Tier)

Ogni regola puo' avere una o piu' soglie (tier) che definiscono il prezzo in base a intervalli di valori.

Per aggiungere una soglia, espandi una regola cliccandoci sopra, poi clicca "+ Aggiungi Soglia".

Campi della soglia

• Tipo calcolo — fixed (prezzo fisso) o variable (valore canvas passato direttamente)
• Scope — local (confronta valore singolo contratto) o global (confronta metrica globale)
• Min — valore minimo dell'intervallo
• Max — valore massimo dell'intervallo
• Modified Price — prezzo da applicare (solo per tipo fixed)

Modificatori di prezzo

Un modificatore applica una formula di aggiustamento al prezzo calcolato dalla soglia. Ogni regola puo' avere al massimo un modificatore.

Per aggiungere un modificatore, espandi la regola e clicca "+ Aggiungi Modificatore".

Campi del modificatore

• Formula — espressione JS (es. base_price * value)
• Valore — il numero usato nella formula (es. 1.15 per +15%)
• Arrotondamento — none, round, floor, ceil

Regole Virtual e sintassi depends_on

Le regole di tipo virtual generano voci di calcolo non presenti nel canvas del contractor. Vengono iniettate automaticamente dal sistema quando le condizioni specificate nel campo Dipende da (depends_on) sono soddisfatte.

Quando usare una regola virtual

• Commissioni aggiuntive da riconoscere alla sub quando una specifica voce canvas e' presente (es. +25€ per ogni contratto con PRECHECK)
• Storni virtuali di voci che il contractor non storna esplicitamente nel canvas (es. storno RID quando viene stornato il PRECHECK)
• Qualsiasi compenso che dipende dalla presenza di altre voci ma non ha una corrispondente voce canvas diretta

Campi specifici delle regole virtual

• Tipo — deve essere virtual
• Service Name — il nome con cui la voce apparira' nell'anteprima e nei calcoli (es. STORNO VIRTUAL RID SU DECORRENZA POWER)
• Base Price — il valore che viene iniettato come canvas value (positivo per compensi, negativo per storni)
• Dipende da — le condizioni che devono essere soddisfatte per iniettare la voce (vedi sintassi sotto)

Sintassi del campo depends_on

Il campo depends_on supporta tre tipi di condizioni, separati da virgola. Ogni condizione viene identificata dal suo prefisso:

Tutte e tre le tipologie di condizione devono essere soddisfatte contemporaneamente (AND tra i gruppi). All'interno dello stesso gruppo, la logica e':

• Condizioni senza prefisso: basta che almeno una sia vera (OR)
• Condizioni *:: devono essere tutte vere (AND)
• Condizioni !:: devono essere tutte vere, cioe' nessuna chiave elencata deve essere presente (AND)

Esempio pratico: storno virtual RID

Scenario: Bluenergy storna il PRECHECK POWER ma non storna mai il RID SU DECORRENZA POWER nel canvas. Si vuole generare automaticamente uno storno RID quando il PRECHECK viene stornato, ma solo se il RID era stato effettivamente pagato in un mese precedente.

Questa regola si attiva solo quando tutte e tre le condizioni sono soddisfatte:

1. Il canvas del mese corrente contiene STORNO PRECHECK 180 GG - DOMESTICO POWER (il trigger)
2. In qualsiasi mese della storia canvas del contratto esiste RID SU DECORRENZA POWER (verifica che il RID sia stato effettivamente pagato)
3. Il canvas del mese corrente NON contiene STORNO RID SU DECORRENZA POWER (evita duplicazione se Bluenergy storna il RID direttamente)

Esempio pratico: compenso aggiuntivo per voce canvas

Scenario: si vuole riconoscere 25€ extra alla sub per ogni contratto che ha la voce PRECHECK 180 GG - DOMESTICO POWER.

Campo max_single_value per forzare SINGLE

Sulle regole storno con modificatore ×2, la detection DUAL/SINGLE puo' interferire con il calcolo. Se il canvas dello storno ha un valore pari al prezzo DUAL originale (es. -80 con unit price 40), il sistema lo interpreta come DUAL e raddoppia prima del modificatore, causando un addebito doppio.

Per risolvere, impostare max_single_value = 9999 sulla regola storno. Il sistema usera' la logica: se |canvasValue| > max_single_value allora DUAL, altrimenti SINGLE. Con 9999, il risultato e' sempre SINGLE, lasciando al modificatore il compito di raddoppiare correttamente.

Timeline regole

La vista Timeline fornisce una rappresentazione visuale Gantt-like della validita' temporale di tutte le regole della sub selezionata, permettendo di identificare a colpo d'occhio sovrapposizioni, buchi e regole in scadenza.

Come accedere

1. Seleziona un contractor e una sub dalla sidebar
2. Nella sezione Regole, clicca il pulsante "📅 Timeline" in alto a destra (accanto a "Nuova Regola")
3. La vista lista viene sostituita dalla timeline. Clicca di nuovo "📅 Timeline" per tornare alla lista

Come leggere la timeline

• Asse verticale — ogni riga corrisponde a una regola, identificata dal service_name
• Asse orizzontale — mesi, con un range di ±6 mesi rispetto alla data odierna (13 mesi totali)
• Colore della barra — identifica il tipo e lo scope della regola a colpo d'occhio:
  • Blu pieno — regola service con scope local. E' il tipo piu' comune: il valore del singolo contratto viene confrontato con le soglie min/max
  • Viola pieno — regola service con scope global. Una metrica globale (es. percentuale SDD) determina in quale soglia ricade il contratto. Esempio tipico: le regole "Incentivo Mensile SDD" di Plenitude che hanno 3 soglie basate sulla percentuale di attivazione SDD
  • Rosa/fucsia — regola virtual. Genera voci non presenti nel canvas (compensi aggiuntivi, storni virtuali). Il colore corrisponde al badge virtual usato nella vista lista
  • Grigio tratteggiato — regola soppressa. Ha un modificatore con value = 0 (formula base_price * 0), quindi il risultato e' sempre €0. La voce canvas esiste ma viene annullata. Nella vista lista appare con il badge 🚫 soppressa
• Badge multi-soglia — se una regola ha piu' di una soglia (tier), sulla barra compare un badge come 3T che indica il numero di soglie configurate. Questo e' particolarmente utile per le regole con scope global dove il numero di tier determina la granularita' degli scaglioni (es. SDD 55-65% → €15, 65-85% → €22, 85-100% → €30)
• Opacita' — le regole attive (in corso) hanno opacita' piena (100%). Le regole scadute o future hanno opacita' ridotta (40%), per distinguerle visivamente senza rimuoverle dalla vista

Tooltip interattivo

Passando il mouse su una riga della timeline (sia sul nome che sulla barra), viene mostrato un tooltip HTML ricco e colorato che segue il cursore e riassume l'intera configurazione della regola in modo strutturato e visualmente chiaro.

Il tooltip e' composto da sezioni distinte, ognuna con colorazione dedicata:

• Titolo — nome della regola colorato per tipo (blu = service, rosa = virtual) + badge arrotondato con lo stato: ATTIVA FUTURA SCADUTA
• Tipo e scope — badge colorati: service / virtual e global se applicabile
• Validita' — date in formato monospaced
• Base price / Max single / Depends on — mostrati solo se configurati
• Soglie — ogni tier su riga separata con sfondo grigio, badge fixed/variable e local/global, range min→max e prezzo in blu a destra
• Modificatore — formula, moltiplicatore evidenziato in blu, badge arrotondamento (se presente) in viola. Le regole soppresse (×0) mostrano il modificatore in grigio

Click per modifica rapida

Cliccando su qualsiasi riga della timeline (nome o barra) si apre direttamente il modale di modifica della regola, permettendo di editarla senza dover tornare alla vista lista e cercarla manualmente.

Copia, Incolla e Duplica regole

Copia/Incolla singola regola

1. Clicca l'icona 📋 accanto alla regola da copiare — la regola viene salvata negli appunti interni
2. Naviga alla sub di destinazione (selezionandola dalla sidebar)
3. Clicca "📋 Incolla regola" — la regola viene creata nella nuova sub

Duplica tutte le regole su un'altra sub

1. Seleziona la sub sorgente dalla sidebar
2. Clicca "⧉ Duplica su altra sub"
3. Nel modale, seleziona la sub destinazione
4. Opzionalmente, spunta "Sovrascrivi regole esistenti"
5. Clicca "⧉ Duplica"

Espandere una regola

Clicca su una regola per espanderla e visualizzare i dettagli:

• Soglie — tabella con tutti i tier definiti
• Modificatore — formula di aggiustamento prezzo (se presente)
• Dipende da — per regole virtual, condizioni con sintassi *: e !: (dettagli)
• Metrica globale — per scope global, la chiave della metrica

🎁 Bonus

Gestisci bonus e penalita' per le sub-agenzie

I bonus sono importi aggiuntivi (positivi o negativi) che vengono aggiunti al calcolo delle provvigioni. Possono essere flat (importo fisso) o basati sul numero di pezzi (contratti).

Creare un nuovo bonus

1. Clicca "+ Nuovo Bonus"
2. Compila i campi nel modale
3. Clicca "Salva Bonus"

Campi del modale bonus

• Contractor — seleziona il contractor
• Sub — seleziona la sub
• Descrizione — testo descrittivo (es. "Bonus qualita' Q1")
• Formula:
  • flat — importo fisso indipendente dal numero di pezzi
  • pezzi * importo — l'importo viene moltiplicato per il numero di contratti nel mese
• Importo — valore in euro (positivo per bonus, negativo per penalita')
• Min pezzi — numero minimo di contratti richiesto per attivare il bonus (opzionale)
• Max pezzi — numero massimo di contratti (opzionale)
• Valid From / Valid To — periodo di validita'

▶️ Calcola

Lancia il calcolo automatico delle provvigioni

Questa sezione consente di avviare il workflow di calcolo che applica tutte le regole, soglie, modificatori e bonus ai contratti del mese selezionato.

Come avviare un calcolo

1. Seleziona il mese di competenza (es. 2026-03)
2. Seleziona il contractor dal menu a tendina
3. Seleziona una o piu' sub-agenzie (Ctrl+Click per selezione multipla, oppure clicca "Seleziona tutte")
4. Clicca "▶ Avvia Calcolo"

Monitoraggio del progresso

Durante il calcolo, viene mostrata una barra di progresso in tempo reale con:

• Step corrente — nome della fase in esecuzione
• Percentuale — avanzamento complessivo
• Conteggio contratti — es. "125/300 contratti (42%)"
• Log messaggi — dettaglio delle operazioni con timestamp

Al termine del calcolo, compaiono due pulsanti:

• 🔍 Vai all'Anteprima — passa direttamente alla sezione Anteprima per vedere i risultati
• ↩ Nuovo Calcolo — resetta il form per un nuovo calcolo

Gestione Cache Redis

Il sistema utilizza una cache Redis per velocizzare i calcoli. Se modifichi regole, soglie o modificatori, potresti dover invalidare la cache prima di ricalcolare.

• 🗑️ Svuota Cache — invalida la cache solo per il contractor/sub/mese selezionato
• 🔥 Flush Tutta — invalida tutta la cache Redis (tutte le chiavi fastsign:*)

👁️ Anteprima

Visualizza i risultati del calcolo provvigioni

La sezione Anteprima mostra i risultati calcolati, raggruppati per contractor → sub.

Filtri

Struttura dei risultati

Per ogni coppia contractor/sub, l'anteprima mostra:

Dettaglio per riga

Cliccando su "▶ Dettaglio contratti" sotto ogni card anteprima, si espande la tabella con il dettaglio riga per riga di ogni contratto calcolato:

• Codice contratto
• Data creazione (created_at)
• POD/PDR
• Log ID
• Voce canvas
• Tipo — Canvas, Storno, Bonus
• Prezzo calcolato — colorato in verde (positivo) o rosso (negativo)
• Debug — dettagli del calcolo (regola applicata, moltiplicatore, ecc.)

Evidenziazione voci senza regola

Quando una voce canvas non ha una regola associata (service_name non presente in invoice_rules), la riga viene evidenziata con massima visibilita':

L'evidenziazione comprende:

• Sfondo rosso chiaro su tutta la riga (12% opacita')
• Bordo sinistro rosso spesso (3px) per visibilita' anche scorrendo velocemente
• Badge rosso lampeggiante ⚠ NESSUNA REGOLA nella colonna calcolo, con animazione pulse che alterna opacita' ogni 1.5 secondi

Contratti pagati e stornati nella stessa competenza (canvas zero)

Quando un contratto viene pagato e stornato dal contractor nella stessa competenza, tutte le voci canvas risultano a € 0.00. Questi contratti appaiono nel dettaglio con il debug canvas zero (pagato+stornato) per indicare che il valore zero non e' un errore ma il risultato di una compensazione nella stessa fattura.

Questi contratti sono importanti per la sub perche' documentano l'avvenuto pagamento e storno, anche se il saldo netto e' zero. Vengono inclusi sia nel dettaglio contratti che nell'export Excel per Sub.

Esportazione

• 📄 Genera PDF — apre la finestra di stampa del browser (puoi salvare come PDF). Le righe soppresse (€0) vengono automaticamente nascoste in stampa
• 📥 Excel per Sub — esporta i dati in formato CSV apribile con Excel. Include le righe canvas zero (pagato+stornato) per dare visibilita' alla sub. Esclude le righe soppresse (modificatore ×0) che la sub non deve vedere. La distinzione avviene tramite il campo calcolo_debug: se contiene canvas zero senza [mod:] viene incluso, altrimenti viene escluso

⚙️ Config

Gestione contractor, sub-agenzie e contatti

La sezione Config mostra una vista ad albero gerarchica di tutti i contractor con le relative sub-agenzie.

Gestione Contractor

Creare un nuovo contractor

1. Clicca "+ Nuovo Contractor"
2. Inserisci il nome del contractor
3. Clicca "Salva"

Azioni sul contractor

• ✏️ Modifica nome — rinomina il contractor
• ⏸ / ▶ Abilita/Disabilita — disattiva un contractor (non apparira' nei calcoli). Badge: attivo o disabilitato
• 💳 Split Payment — attiva/disattiva il regime di split payment. Badge: split payment o IVA standard

Gestione Sub-Agenzie

Ogni contractor puo' avere piu' sub-agenzie collegate. Per aggiungere una sub:

1. Espandi il contractor nell'albero
2. Clicca "+ Aggiungi Sub" sotto il contractor
3. Seleziona una sub esistente dal menu o crea una nuova sub
4. Clicca "Aggiungi"

Per scollegare una sub da un contractor, clicca "✕ Scollega".

Contatti Sub-Agenzia

Ogni sub-agenzia puo' avere informazioni di contatto associate:

• 🏢 Ragione Sociale
• 📧 Email
• 📱 Cellulare

Per modificare i contatti, clicca "✏️ Contatti" accanto alla sub nell'albero config. I dati vengono mostrati come tag colorati nella vista ad albero.

🧾 Fatture

Gestisci il ciclo di vita delle fatture

La sezione Fatture consente di monitorare e gestire lo stato delle fatture generate dal calcolo provvigioni.

Filtri

• Mese — filtra per mese di competenza (o "Tutti")
• Stato — filtra per stato della fattura (o "Tutti")

Ciclo di vita della fattura

Ogni fattura attraversa i seguenti stati in ordine:

Transizioni di stato

• ▶ Avanza — porta la fattura allo stato successivo
• ◀ Retrocedi — riporta la fattura allo stato precedente
• Dallo stato "Pagata" non e' possibile retrocedere (stato finale)

Modifica fattura

Cliccando ✏️ si apre un modale per modificare:

• Stato — selezione diretta dello stato
• Numero fattura — numero identificativo
• Data fattura
• Note — annotazioni libere
• PDF Fattura — caricamento del file PDF (drag & drop supportato)

📥 Inviti / Import Fatturato

Controlla lo stato degli import e carica i dati mancanti

La sezione Inviti mostra una matrice di checklist che indica, per ogni contractor e mese, se il fatturato e' stato importato correttamente.

Legenda

Caricare un fatturato mancante

1. Individua la cella ↑ carica nella matrice
2. Cliccaci sopra — si apre il modale di upload
3. Trascina il file nella zona di drop oppure clicca per selezionarlo
4. Formati accettati: .xlsx, .xls, .csv
5. Clicca "Carica" per avviare l'importazione

Matrice Sub-Agenzia

Sotto la matrice contractor, c'e' una seconda matrice che mostra il dettaglio per sub-agenzia. Puoi filtrarla per contractor specifico. Mostra il conteggio dei record importati per ogni sub/mese.

⚠️ Non Mappati

Voci canvas senza regola di calcolo associata

Questa sezione mostra le voci canvas trovate nei contratti che non hanno una regola di calcolo corrispondente. Finche' una voce non e' mappata, non verra' calcolata nel provvigionamento.

Filtri

• Mese — filtra per mese di rilevamento
• Contractor — filtra per contractor
• 🔄 — aggiorna i dati

Azioni disponibili

• 📋 Regola — apre il modale di creazione regola con il service_name pre-compilato dalla voce canvas. Devi solo completare i restanti campi (soglia, prezzo, ecc.)
• ✕ Ignora — rimuove la voce dalla lista (la segna come ignorata). Usalo per voci canvas che non devono generare provvigioni

📊 Margini

Analisi di redditivita' per contractor e sub

La sezione Margini fornisce una visione aggregata della redditivita' per ciascun contractor e sub-agenzia.

Come usarla

1. Seleziona il mese di riferimento
2. Clicca "Carica"

Dati visualizzati

Riepilogo per Contractor

Colonne della tabella

• Incassato / Ricavo — totale fatturato dal contractor (canvas value)
• Costo Sub — totale provvigioni da pagare alla sub
• Margine — differenza tra ricavo e costo
• Margine % — percentuale di margine (verde se positivo, rosso se negativo)
• Entrata (IVA) — ricavo + IVA 22%
• Uscita (IVA) — costo + IVA 22%
• Cashflow — differenza tra entrata e uscita

🔬 Simulazione What-If

Testa modifiche alle regole senza impattare i dati reali

La sezione Simulazione consente di modificare virtualmente le regole di calcolo e vederne l'effetto in tempo reale, senza alterare i dati nel database. E' uno strumento potente per:

• Prevedere l'impatto di variazioni di prezzo
• Testare nuove soglie prima di applicarle
• Analizzare scenari "what-if" per la negoziazione
• Stimare margini con configurazioni diverse

Come avviare una simulazione

1. Seleziona mese, contractor e sub
2. Clicca "▶ Carica dati" — vengono scaricati contratti e regole
3. Modifica le regole nella tabella interattiva
4. I risultati si ricalcolano automaticamente ad ogni modifica

Tabella regole modificabile

Campi modificabili

• ☑ Checkbox — abilita/disabilita la regola nella simulazione (opacita' ridotta = disabilitata)
• Calcolo — dropdown per cambiare tra fixed e variable
• Base Price — modifica il prezzo base
• Modified Price — modifica il prezzo della soglia
• Mod. Valore — modifica il valore del modificatore
• Arrotondamento — dropdown: none, round, floor, ceil

Modifica quantita' pezzi

Nei risultati della simulazione, puoi modificare le quantita' (pezzi) per ogni voce canvas. Questo consente di simulare scenari con volumi diversi senza alterare i dati reali.

Ricalcolo e export

• 🔄 Ricalcola — forza un ricalcolo manuale (di solito automatico)
• 📥 Esporta CSV — scarica i risultati della simulazione in formato CSV

💰 Gettoni Medi

Confronto gettone incassato vs riconosciuto per contractor / sub / mese

La sezione Gettoni Medi confronta due prospettive fondamentali per ogni combinazione contractor/sub/mese:

• Gettone Incassato — quanto Soloweb ha effettivamente incassato dal contractor per pezzo, calcolato come SUM(importo_fatturazione + surcharge) / SUM(pezzi). Per BLUENERGY viene aggiunto un surcharge di +45€/pezzo sull'indiretta
• Gettone Riconosciuto — quanto Soloweb ha riconosciuto alla sub-agenzia per pezzo, calcolato dalla somma dei calculated_price in invoice_details (dati dall'anteprima/fattura) diviso per i pezzi
• Delta Gettone — la differenza tra incassato e riconosciuto, che rappresenta il margine di Soloweb per pezzo. Positivo (verde) = margine, negativo (rosso) = perdita

Questo confronto e' fondamentale per:

• Verificare la marginalita' — capire se il rapporto tra incassato e riconosciuto e' sostenibile
• Confrontare le sub-agenzie — identificare dove il delta e' piu' favorevole o critico
• Analizzare i trend temporali — filtrando per range di mesi e' possibile osservare come variano i gettoni e il delta nel tempo
• Confrontare produzione indiretta e diretta — con l'opzione SOLOWEB si possono confrontare i gettoni medi delle sub con quelli della produzione diretta

Filtri disponibili

La barra dei filtri si trova nella parte superiore della sezione e consente di restringere i dati visualizzati:

• Contractor — seleziona un singolo contractor o lascia "Tutti" per vedere tutti i contractor attivi. La lista e' popolata automaticamente dalla sidebar
• Sub — seleziona una specifica sub-agenzia. Disponibile solo dopo aver scelto un contractor. Lascia "Tutte" per vedere tutte le sub del contractor selezionato
• Da mese / A mese — definiscono un intervallo temporale. I mesi si riferiscono alla created_at del contratto (data di inserimento nel sistema). Se entrambi sono vuoti, vengono mostrati tutti i mesi disponibili. E' possibile impostare solo uno dei due per un filtro aperto
• Includi produzione diretta (SOLOWEB) — checkbox che, se attivata, aggiunge una seconda tabella con i gettoni medi della produzione diretta (contratti gestiti internamente con agenzia = SOLOWEB dalla tabella backoffice)

Dopo aver impostato i filtri desiderati, clicca il pulsante "Carica" in alto a destra per eseguire la query e visualizzare i risultati.

Risultati e tabelle

I risultati vengono mostrati in una tabella raggruppata per contractor, con una riga per ogni combinazione di sub-agenzia e mese.

Tabella Gettoni Medi — Sub

Colonne della tabella

• Contractor — il cliente/fornitore (es. Alpha Energia, BLUENERGY)
• Sub — la sub-agenzia che ha prodotto i contratti
• Mese — il mese di creazione dei contratti, in formato YYYY_MM
• Contratti — il numero totale di contratti con importo di fatturazione valido (maggiore di zero)
• Pezzi — la somma dei pezzi dei contratti. Un contratto DUAL conta 2 pezzi, un SINGLE conta 1
• Tot Incassato — la somma degli importi di fatturazione, con surcharge BLUENERGY (+45€/pezzo sull'indiretta). Rappresenta quanto Soloweb ha effettivamente incassato dal contractor
• Gett. Incassato — il gettone medio incassato: Tot Incassato / Pezzi
• Tot Riconosciuto — la somma dei calculated_price da invoice_details (anteprima/fattura). Rappresenta quanto Soloweb ha riconosciuto alla sub. Se il calcolo non e' stato ancora eseguito per quel mese, il valore sara' 0
• Gett. Riconosciuto — il gettone medio riconosciuto: Tot Riconosciuto / Pezzi
• Δ Gettone — la differenza tra gettone incassato e riconosciuto per pezzo. Colorato in verde se positivo (margine) o in rosso se negativo (perdita)

La tabella include due livelli di subtotali:

• Subtotale per contractor — riga con sfondo grigio che mostra i totali e le medie complessive per quel contractor
• Totale Generale — riga evidenziata in blu in fondo alla tabella con il riepilogo globale

Produzione diretta (SOLOWEB)

Attivando la checkbox "Includi produzione diretta (SOLOWEB)", sotto alla tabella delle sub viene visualizzata una seconda tabella dedicata alla produzione diretta, cioe' i contratti gestiti internamente dall'agenzia SOLOWEB.

Tabella Gettoni Medi — Produzione Diretta (SOLOWEB)

La tabella della produzione diretta ha una struttura simile ma semplificata:

• Non ha la colonna Sub (la produzione diretta non passa per sub-agenzie)
• I dati provengono dalla tabella backoffice (non backoffice_subs) filtrata per agenzia = 'SOLOWEB'
• Il filtro Contractor si applica anche a questa tabella; il filtro Sub no (non pertinente)
• I filtri temporali Da mese / A mese si applicano anche alla produzione diretta

🎨 Tema Chiaro / Scuro

Personalizza l'aspetto dell'applicazione

L'applicazione supporta due temi:

• 🌙 Tema scuro (default) — sfondo scuro, ideale per ambienti con poca luce
• ☀️ Tema chiaro — sfondo chiaro, migliore leggibilita' in ambienti luminosi

Per cambiare tema, clicca il pulsante 🌙 / ☀️ nella barra di navigazione in alto a destra. La preferenza viene salvata nel browser.

📚 Glossario

Terminologia utilizzata nell'applicazione

Contractor	Fornitore di energia/gas che commissiona la vendita tramite sub-agenzie
Sub / Sub-Agenzia	Agenzia che vende i contratti per conto del contractor e percepisce le provvigioni
Voce Canvas	Identificativo del tipo di servizio/contratto nel sistema canvas (es. EE_RESIDENZIALE_DOMESTICO)
Regola	Definisce come calcolare la provvigione per una specifica voce canvas di una sub
Soglia / Tier	Intervallo di valori (min/max) con un prezzo associato. Le regole possono avere piu' soglie
Modificatore	Formula di aggiustamento applicata dopo la soglia (es. +15% su base price)
DUAL / SINGLE	Moltiplicatore: DUAL (×2) se il valore canvas supera il prezzo unitario, altrimenti SINGLE (×1)
Billing Month	Mese di competenza della fattura (usato per bonus e metriche)
created_at	Data di creazione del contratto in backoffice_subs (usata per il matching delle regole)
Split Payment	Regime fiscale in cui l'IVA viene versata direttamente all'erario dal committente
Storno	Rettifica negativa di una provvigione precedentemente calcolata
POD / PDR	Identificativi univoci del punto di fornitura (POD = energia elettrica, PDR = gas)
Cache Redis	Memoria temporanea (TTL 2h) che velocizza il calcolo evitando query ripetute al database