productBehaviors

Introduzione

Questo sistema gestisce il budget aziendale attraverso Streams (progetti multi-anno), Versioni (snapshot per anno fiscale), e Contratti (impegni reali o stimati).

Concetti Chiave

Elemento	Descrizione	Gestione
Stream	Progetto principale (es. "Marketing Digitale") che copre uno o più anni fiscali	Input manuale
Versione	Snapshot del budget per un anno fiscale specifico e Tipo Spesa (CAPEX/OPEX)	Rolling (ogni 3 mesi)
Contratto	Impegno collegato allo stream con date inizio/fine.	Autoallocato su FY
Fattura	Pagamento effettuato per un contratto	Autoallocato su FY
Proposto (versione)	Pianificazione teorica iniziale	Input manuale
Approvato (versione)	Budget ufficiale autorizzato	Input manuale
Totale Contratti (versione)	Somma di tutti i contratti (reali + stimati) per l'anno fiscale	Calcolato
Impegnato (versione)	Somma dei contratti "Approved", "In Delivery", "Closed" per l'anno fiscale	Calcolato
Stima Residua (versione)	Quanto budget approvato resta da impegnare (Approvato - Impegnato)	Calcolato
Speso (versione)	Quanto è stato effettivamente pagato tramite fatture	Calcolato
Pagamenti Residui (versione)	Quanto dell'impegnato resta da pagare (Impegnato - Speso)	Calcolato
Previsione Chiusura (versione)	Stima finale di spesa (max(Approvato, Impegnato))	Calcolato

Esempi di Situazioni Comuni

1. Pianificazione Iniziale

• Cosa Fai: Crei uno Stream come "Marketing Digitale". Poi crei DUE versioni iniziali per FY25: una per OPEX e una per CAPEX.
• Aggiungi una Stima: Crei un contratto "Proposed" da 50.000 € (Expense Type: OPEX) per FY25.
• Risultato:
  • La versione OPEX mostra: Totale Contratti = 50.000 €, Proposto = 50.000 € (inserito manualmente), Approvato = 0 €.
  • La versione CAPEX mostra: Totale Contratti = 0 €, Proposto = 0 €.
• Perché: I budget sono segregati per tipo. Una stima OPEX non consuma budget CAPEX.

2. Approvazione del Budget (Gate Manageriale)

• Cosa Fai: Una volta discussa la pianificazione, il responsabile budget inserisce manualmente l' Importo Approvato (approved_amount) nella versione (es. 50.000 €).
• Cosa Succede: La Stima Residua si attiva: Approvato (50k) - Impegnato (0k) = 50.000 €.
• Risultato: Approvato = 50.000 €, Stima Residua = 50.000 €, Impegnato = 0 €.
• Perché: Senza un importo approvato ufficialmente, non c'è una "Stima Residua" reale su cui scalare i contratti.

3. Approvazione del Primo Contratto

• Cosa Fai:
  1. Crei un nuovo record per il primo contratto reale (da 15.000 €) e lo imposti come "Approved".
• Cosa Succede Automaticamente:
  1. Il sistema individua il contratto "Proposed" più vecchio (quello da 50.000 €).
  2. Erosione Automatica: Sottrae i 15.000 € dalla stima, riducendola a 35.000 €.
  3. L'Impegnato aumenta a 15.000 € e il Totale Contratti si mantiene coerente.
• Risultato: Approvato = 50.000 €, Totale Contratti = 50.000 € (15k reale + 35k stimato), Impegnato = 15.000 €, Stima Residua = 35.000 €.
• Perché: L'erosione automatica (FIFO - First In, First Out) evita il "doppio conteggio" e mantiene il piano di spesa allineato alla realtà senza interventi manuali ripetitivi. Se un contratto reale supera la prima stima, il sistema continuerà a ridurre le altre stime "Proposed" presenti fino a coprire l'intero importo.

4. Approvazione di Più Contratti

• Cosa Fai: Firma un altro contratto da 20.000 € (nuovo record), cambia status ad "Approved".
• Cosa Succede Automaticamente:
  1. Il sistema continua l'erogazione del contratto "Proposed" residuo (che era a 35.000 €).
  2. L'Impegnato totale sale a 35.000 € (15k + 20k).
• Azione Manuale Richiesta: Clicca il pulsante "Proposed Contracts Value Erosion" sul nuovo contratto per erodere i placeholder.
  • L'erosione sottrae i nuovi 20.000 €, riducendo la stima placeholder a 15.000 €.
• Risultato: Approvato = 50.000 €, Totale Contratti = 50.000 € (35k reali + 15k stimato residuo), Impegnato = 35.000 €, Stima Residua = 15.000 €.
• Perché: Il meccanismo garantisce che, finché ci sono stime "Proposed" disponibili, ogni nuovo contratto approvato ne consumi il budget, mantenendo il piano finanziario sempre in equilibrio.

4b. Superare il Budget Approvato

• Cosa Fai: Firma un contratto reale da 25.000 € (nuovo record), cambia status ad "Approved".
• Cosa Succede Automaticamente:
  1. L'Impegnato aumenta di 25.000 €.
• Azione Manuale Richiesta: Clicca "Proposed Contracts Value Erosion" per erodere i placeholder rimanenti.
  • Il sistema esaurisce l'erogazione dell'ultima stima "Proposed" rimasta (15.000 €).
  • Poiché il nuovo contratto (25k) supera il placeholder residuo (15k), l'eccedenza di 10.000 € incrementa il Totale Contratti.
• Risultato: Totale Contratti = 60.000 € (35k precedenti + 25k nuovo), Impegnato = 60.000 €, Stima Residua = -10.000 €.
• Perché: Una volta esaurite tutte le stime "Proposed", ogni ulteriore contratto approvato incrementa direttamente il totale impegnato, portando la Stima Residua in negativo se si supera il budget approvato dal manager.

5. Approve & Roll (Workflow Trimestrale)

• Situazione: È finito il trimestre (es. Settembre) e devi preparare la pianificazione per il prossimo (es. Ottobre).
• Cosa Fai:
  1. Apri l'ultima versione del trimestre corrente (in stato "Draft" o "Approved").
  2. Clicca il pulsante "Approve & Roll to Next Quarter".
• Cosa Succede Automaticamente:
  1. Congelamento Corrente: La versione corrente viene bloccata in stato "Approved".
     • Nota: committed_amount viene congelato; spent_amount continua ad aggiornarsi (arriveranno ulteriori fatture).
  2. Archiviazione Precedente: Il sistema cerca la versione del trimestre precedente (stesso Bucket/Type) e, se "Approved", la passa ad "Archived".
  3. Calcolo Data: Il sistema calcola la data del prossimo trimestre (+3 mesi).
  4. Controllo FY:
     • Se il prossimo trimestre è nello stesso FY: copiamo Approvato e Proposto.
     • Se il prossimo trimestre è in un nuovo FY: resettiamo Approvato e Proposto a 0.
  5. Creazione Nuova Versione: Genera la versione successiva in stato "Draft".
  6. Ricalcolo Automatico: Aggiorna gli importi basandosi sui contratti attuali.
• Risultato:
  • Versione precedente congelata (storico).
  • Nuova versione pronta per la pianificazione ("Draft").
  • Nessun data entry manuale.

6. Retroactive Alignment (Nuovi Stream)

• Situazione: Viene approvato un nuovo Stream a metà trimestre (es. 15 Novembre).
• Regola: La versione di budget deve essere allineata allo snapshot trimestrale standard, non alla data di creazione.
• Procedura:
  1. Crea la versione con data 1° Ottobre (inizio trimestre corrente).
  2. Il sistema accetterà la data retroattiva per mantenere l'allineamento dei report.
  3. Al prossimo "Approve & Roll", si genererà regolarmente la versione di Gennaio.
• Perché: Evita la frammentazione temporale dei report (es. avere colonne "Ottobre", "Novembre", "Gennaio" nello stesso pivot).

6. Pianificazione Anticipata (FY Futuri)

• Situazione: Siamo in Luglio (FY25), e vuoi iniziare a pianificare il budget per l'anno prossimo (FY26).
• Cosa Fai: Crei una versione per FY26.
• Risultato: La versione FY26 nasce con un totale valore contratti basato sui contratti collegati a FY26.
• Perché: Permette di lavorare sulla strategia futura senza influenzare i calcoli o i saldi del budget corrente (FY25).

7. Contratto Multi-FY

• Situazione: Un contratto da 100.000 € copre due anni fiscali (es. 60k in FY25 e 40k in FY26).
• Cosa Succede: Il sistema ripartisce automaticamente l'importo tra i due anni usando l'allocazione pro-rata giornaliera.
• Risultato:
  • Nella versione FY25, l' Impegnato aumenta di 60.000 €.
  • Nella versione FY26, l' Impegnato aumenta di 40.000 €.
• Perché: Ogni versione trimestrale (Rolling) "vede" solo la quota di costo che compete a quell'anno fiscale specifico, mantenendo i bilanci annuali separati e precisi.

8. Cambiamenti di Stato ed Erosione Manuale

• Cosa Succede: Quando un contratto passa a "Approved":
  1. L' Impegnato aumenta per bloccare ufficialmente i fondi.
  2. Erosione Manuale (Pulsante): L'utente deve cliccare il pulsante "Proposed Contracts Value Erosion" per ridurre i placeholder "Proposed" più vecchi (FIFO).
  3. Il campo erosion_applied viene marcato per evitare doppia esecuzione.
• Perché: Questo ci evita il "doppio conteggio" e mantiene il Totale Contratti sempre allineato al budget progettato originariamente.Inoltre, l'erosione manuale garantisce controllo e tracciabilità, evitando side-effects imprevisti.

9. Riconciliazione Fatture e Pagamenti

• Cosa Succede: Quando registri una fattura di 5.000 € collegata a un contratto:
  1. Il campo Speso (Spent) della versione aumenta di 5.000 €.
  2. Il campo Pagamenti Residui (Remaining Payments) diminuisce di 5.000 €, mostrandoti quanto resta ancora da pagare sugli impegni presi.
• Perché: Permette di monitorare quanto del budget "impegnato" (committed) è stato effettivamente liquidato rispetto a quanto resta ancora da pagare (remaining payments).

Monitoraggio e Analisi Strategica

Il sistema permette di "guardare" i numeri da diverse prospettive per capire come sta andando la spesa durante l'anno.

1. Le dimensioni dell'analisi

Per evitare doppioni e confusione, ogni spesa è classificata secondo quattro direttrici principali:

• Domain (Dipartimento): Chi spende? (es. IT, Marketing, HR).
• Stream (Motivo Strategico): Perché spendiamo? (es. "Cloud Infrastructure", "Consulenza Tecnica","Nuovo Sito Web"). Lo Stream definisce il "contenitore" logico della spesa.
• Budget Bucket (Il Capitolo): Cosa stiamo pagando nello specifico? (es. "Server AWS", "Supporto Manutenzione Esterna", "Contratto Dev Website 9/25").
• Tipo di Spesa (Finanza): Come viene contabilizzata? (CAPEX per investimenti in beni capitali, OPEX per spese operative correnti).

2. Monitoraggio in fase di Preparazione (Planning)

Mentre prepariamo il budget (versioni in "Draft"):

• Controlliamo il Proposto totale per Domain, Stream, Budget Bucket e Tipo di Spesa.
• Verifichiamo se i contratti "Proposed" (le stime) coprono tutto il piano o se mancano pezzi.
• Analizziamo lo storico delle versioni degli anni fiscali precedenti per vedere se le stime per l'anno prossimo sono realistiche.

3. Monitoraggio in corso d'anno (Execution)

Una volta approvato il budget, usiamo i report per monitorare due "verità" diverse ma collegate:

• Approvato vs. Impegnato (Controllo Spesa): Confrontiamo quanto il business ha autorizzato spendere con quanto abbiamo già contrattualizzato. Se l'Impegnato supera l'Approvato, la Stima Residua diventa negativa: è un errore bloccante che va sanato o aumentando il budget o riducendo i contratti.
• Proposto vs. Approvato (Gestione Aspettative): Il Proposto rappresenta la previsione reale del team ("quello che ci serve davvero"). Se il Proposto è stabilmente più alto dell'Approvato, stiamo informando il business che il budget autorizzato non è sufficiente a coprire le necessità operative. Questo evita di "cadere dalle nuvole" a fine anno: la differenza (delta) è un rischio finanziario già dichiarato.
• Stato di Avanzamento: Vediamo quanto dell'Impegnato è già diventato Speso tramite le fatture.
• Previsione di Chiusura (Forecasting): Poiché l' Approvato è il valore ufficiale autorizzato dal business, la previsione di chiusura è data dal valore maggiore tra il budget autorizzato (Approvato) e il valore dei contratti impegnati (Impegnato).
  • Finché Impegnato <= Approvato, la previsione di chiusura resta l' Approvato (ci aspettiamo di saturare il budget autorizzato).
  • Se Impegnato > Approvato, la realtà ha superato l'autorizzazione: la previsione di chiusura segue il valore reale dei contratti impegnati, segnalando lo sforamento.

4. Evitare le Ridondanze

Uno Stream ben definito evita di "duplicare" i costi. Ad esempio, se lo Stream è "Manutenzione Sistemi", non dovrebbero esserci costi di manutenzione sparsi in altri Stream. Se un Budget Bucket (es. "Consulenza X") serve a più scopi, va collegato allo Stream prevalente o diviso in due capitoli distinti.

Casi Speciali

• Senza Stime: Se non ci sono contratti stimati ("Proposed"), l'Impegnato resta 0 e la Stima Residua è uguale all'intero Budget Approvato.
• Più Stime: Se hai più contratti "Proposed", il sistema li consuma in ordine cronologico (dal più vecchio al più recente) man mano che approvi contratti reali.
• Versione Senza Contratti: totale valore contratti = 0 €, Proposto = 0 € (indicato manualmente, in ogni caso), Approvato = 0 €, Impegnato = 0 €, Stima Residua = 0 €.
• Storico: I numeri indicati manualmente delle versioni passate (approvate o chiuse) servono come riferimento; la Stima Residua della versione corrente riflette sempre lo stato di salute attuale del budget per quell'anno.

10. Allocazione Fatture su FY (Cash Outflow)

Per garantire che lo "Speso" mostrato in una versione di budget sia coerente con l'anno fiscale di riferimento, le fatture vengono allocate automaticamente agli anni fiscali:

• Competenza Temporale: Una fattura viene suddivisa tra gli anni fiscali tramite la sotto-form invoice_fy_allocation.
• Automatismo con Periodo di Servizio: Se la fattura riporta service_start_date e service_end_date, il sistema applica lo split pro-rata giornaliero tra i FY (stesso algoritmo dei contratti).
• Automatismo per Data Fattura (Fallback): In assenza di periodi di servizio, il 100% dell'importo viene attribuito all'anno fiscale della invoice_date.
• Rideterminazione Speso: La metrica spent_amount della Budget Version si aggiorna automaticamente sommando le quote di competenza dei contratti del Bucket.

11. Ricalcolo Automatico delle Metriche

Il sistema garantisce che i totali della versione di budget (Impegnato, Speso, ecc.) siano sempre allineati con i cambiamenti apportati ai singoli contratti o fatture attraverso un meccanismo di sincronizzazione:

• Sincronizzazione Automatica: Una procedura notturna controlla se i contratti o le fatture sono stati modificati dall'ultima volta che la versione è stata aggiornata e, in caso positivo, ricalcola i totali.
• Sincronizzazione Manuale: In qualsiasi momento, è possibile forzare l'aggiornamento immediato utilizzando il pulsante "Recalculate Selected Versions" presente nei report delle Budget Versions.

Questo assicura che, anche dopo caricamenti massivi di dati (es. importazione di nuovi contratti da Excel), le metriche finanziarie rimangano accurate senza dover riaprire ogni singola versione.

Note Tecniche

• Input Manuali: Proposto e Approvato gestiti dal responsabile budget.
• Calcoli Automatici: Impegnato, Stima Residua, Speso calcolati dal sistema.
• Test: Coerenza verificata tramite scenari Gherkin in tests.md.
• Struttura Dati: Vedi schema.md per field names e tipi.

Mappa Visiva delle Metriche

┌─────────────────────────────────────────────────────────────────┐
│                         BUDGET METRICS                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  PROPOSED (manual)     ─┐                                       │
│                         │  → Delta Strategy (Proposto vs App.)  │
│  APPROVED (manual)     ─┘                                       │
│       │                                                         │
│       │ remaining_estimate = approved - committed               │
│       ▼                                                         │
│  COMMITTED (auto)      ─┐                                       │
│       │                 │  → closing_forecast = max(A, C)       │
│       │                 │                                       │
│       │ remaining_payments = committed - spent                  │
│       ▼                                                         │
│  SPENT (auto)          ─┘                                       │
│       │                                                         │
│       │ residual = approved - spent                             │
│       ▼                                                         │
│  (Cash outflow)                                                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Legenda:

• remaining_estimate: Quanto budget approvato resta da impegnare
• remaining_payments: Quanto dell'impegnato resta da pagare
• residual: Quanto del budget approvato resta dopo i pagamenti
• closing_forecast: Previsione di chiusura (segue la realtà se supera il budget)

12. Controller Reporting Pack (v3)

Il sistema offre un "Controller Cockpit" strutturato su tre livelli per diversi stakeholder:

A. Executive Overview (Health Check)

Target: CFO

• KPI: Budget Totale, % Impegnato (Gauge), Varianza Forecast (Overrun risk).
• Burn-down Chart: Confronto visuale tra curve di Budget cumulativo, Impegnato e Speso.

B. Strategic Analysis (Trends)

Target: Strategic Planning

• Strategic Pivot: Analisi evolutiva multi-dimensionale (Stream > Bucket > Expense Type) sugli anni fiscali.
• Domande chiave: "Come sta evolvendo la spesa IT rispetto al Marketing anno su anno?"

C. Operational Control (Vendor & Contracts)

Target: Procurement / Ops Controller

• Vendor Performance: Analisi spesa per fornitore.
• Savings Hunter: Identificazione di contratti chiusi con residui di budget da rilasciare.
• Zombie Contracts: Identificazione contratti "In Delivery" ma latenti (no fatture > 6 mesi).

Note su Intercompany (Net Cost)

Design archiviato in specs/recharge_logic_v1.md In scenari multi-entity, il sistema potrà gestire logiche di "Recharge" (Riaddebito) per distinguere il costo Lordo (Cash Out) dal costo Netto (P&L effettiva), supportando flussi di passthrough e reverse charge (es. Country -> International -> Others).