Modulo Agenti & provvigioni in produzione

Provvigioni calcolate automaticamente al CONSEGNATO.

Niente più Excel a fine mese. Scaglioni per agente configurabili (range volume + canale + percentuale). Snapshot immutabile, idempotenza, report periodo + workflow pagamento.

Cosa fa il modulo

La gestione delle provvigioni agenti vinicoli in molte cantine è ancora oggi un rituale Excel di fine mese: l'amministrativo apre un foglio, scarica gli ordini consegnati, fa lookup manuale agente → cliente, applica la percentuale base (con eccezioni "ad memoriam"), totalizza per agente, prepara il bonifico.

Tempo speso: 2-4 ore/mese. Errori frequenti. Discussioni su cosa è "consegnato" e cosa no.

Loogico Vino sostituisce questo rituale con un calcolo automatico al CONSEGNATO + scaglioni configurabili + report periodo + workflow pagamento.

Scaglioni configurabili per agente

Ogni agente ha i suoi scaglioni indipendenti. Esempio per Mario Rossi (agente HoReCa Centro Italia):

Range volume	Canale	Percentuale
0 € – 500 €	`B2B_HORECA`	8%
500 € – 2.000 €	`B2B_HORECA`	10%
2.000 € – ∞	`B2B_HORECA`	12%
0 € – ∞	* (catch-all)	5%

Priorità di selezione: scaglione canale-specifico (B2B_HORECA) sopra catch-all (*). Se cambi i prezzi del catch-all, le provvigioni B2B_HORECA non sono toccate.

Hook automatico al CONSEGNATO

Prima — Excel a fine mese

· 2-4 ore/mese di lavoro amministrativo
· Lookup manuale agente → cliente da rubrica Excel
· Eccezioni applicate "ad memoriam" → discussioni
· Errori frequenti, ricalcoli quando l'agente reclama

Con Loogico — Calcolo al CONSEGNATO

5 minuti/mese: solo verifica report + bonifico
Matching automatico agente da agente_riferimento ordine
Scaglioni configurati una volta, applicati sempre uguali
Snapshot immutabile → niente discussioni

Calcolo provvigione automatico

Ordine CONSEGNATO

Workflow ordine HoReCa transita da SPEDITO a CONSEGNATO

Match agente

Service estrae agente_riferimento dal cliente, matching token-based

Seleziona scaglione

Priorità canale-specifico → catch-all in base a volume + canale

Snapshot calcolo

Record append-only: percentuale + importo immutabili, idempotenza per (agente, ordine)

// Esempio: ordine HoReCa 1.200 € passa a CONSEGNATO

VinoOrdineHorecaController::transizione($ordine, 'CONSEGNATO');
// → hook automatico:
app(VinoProvvigioneCalculatorService::class)->calcolaPerOrdine($ordine);

// 1. Match agente da cliente.agente_riferimento → "Mario Rossi"
// 2. Cerca scaglione: range_da ≤ 1.200 ≤ range_al, canale = B2B_HORECA
// 3. Trova [500-2.000, B2B_HORECA, 10%]
// 4. Calcola: 1.200 × 10% = 120 €
// 5. Crea record append-only:

VinoProvvigioneCalcolo::create([
    'agente_id' => $agente->id,
    'ordine_id' => $ordine->id,
    'periodo_da' => $ordine->data_consegna_effettiva->startOfMonth(),
    'periodo_al' => $ordine->data_consegna_effettiva->endOfMonth(),
    'importo_imponibile' => 1200.00,        // SNAPSHOT
    'percentuale_applicata' => 10.0,        // SNAPSHOT
    'importo_provvigione' => 120.00,
    'stato' => 'DA_PAGARE',
]);
// unique constraint (tenant, agente, ordine) → idempotenza

Snapshot immutabile + idempotenza

📸

Snapshot immutabile

Una volta calcolata, la provvigione non cambia. Anche se modifichi la percentuale dello scaglione successivamente, le provvigioni già calcolate mantengono il loro valore originale.

Per ricalcolare: annulla il record (stato = ANNULLATA) → ricalcola → audit log esplicito.

🔁

Idempotenza

UNIQUE (tenant, agente, ordine): stesso ordine non può generare 2 provvigioni allo stesso agente.

Se ordine ri-passa da CONSEGNATO (es. dopo annullamento), il calcolo è no-op.

Report periodo + workflow pagamento

La pagina /vino/distribuzione/provvigioni offre 2 tab: Calcoli (lista paginata con filtro periodo + stato + agente) e Report periodo (aggregato per agente).

Agente	Calcoli	Imponibile	Provvigione	Da pagare	Pagata
Mario Rossi	23	18.500 €	1.850 €	1.200 €	650 €
Lucia Bianchi	18	12.300 €	1.107 €	800 €	307 €
Giulio Verdi	12	8.900 €	712 €	712 €	0 €

Click su una riga → drill-down dei calcoli del singolo agente. Click "Pagata" su un calcolo DA_PAGARE → stato passa a PAGATA con data_pagamento registrata.

Smetti di calcolare provvigioni Excel

5 agenti reali, 50 ordini consegnati, calcolo automatico end-to-end.

Prenota demo Vino ← Tutti i moduli Vino