Provvigioni agenti vino: scaglioni configurabili e calcolo automatico al CONSEGNATO

Niente più Excel di fine mese. Provvigioni agenti calcolate al CONSEGNATO con snapshot immutabile, scaglioni per range volume e canale, report periodo per pagamento.

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.

Modello dati

Tre tabelle dedicate:

vino_agenti
├─ codice_agente (univoco)
├─ nome, cognome, email, telefono
├─ partita_iva (per fattura agente)
├─ data_inizio_collaborazione
└─ attivo (boolean)

vino_provvigioni_scaglioni
├─ agente_id (FK)
├─ range_volume_da, range_volume_al
├─ canale (B2B_HORECA / B2C_WEB / null = catch-all)
├─ percentuale_applicata
└─ priorita (per tie-break tra scaglioni overlapping)

vino_provvigioni_calcoli (append-only, snapshot immutabile)
├─ agente_id, ordine_id (FK)
├─ periodo_da, periodo_al
├─ importo_imponibile (snapshot)
├─ percentuale_applicata (snapshot al momento del calcolo)
├─ importo_provvigione
├─ stato (DA_PAGARE / PAGATA / ANNULLATA)
├─ data_pagamento (nullable)
└─ unique constraint (tenant, agente, ordine) → idempotenza

Il unique su (tenant, agente, ordine) garantisce che lo stesso ordine non possa generare 2 provvigioni allo stesso agente — anche se l’ordine viene riapertoo passa più volte da CONSEGNATO.

Scaglioni configurabili per agente

Ogni agente ha i suoi scaglioni. 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%

Quando un ordine HoReCa da 1.200 € passa a CONSEGNATO, il calcolatore:

Cerca scaglione agente_id = mario_rossi con range_da ≤ 1.200 ≤ range_al
Priorità canale-specifico (B2B_HORECA) sopra catch-all (*)
Trova: [500-2.000, B2B_HORECA, 10%]
Calcola: 1.200 × 10% = 120 €
Registra calcolo in append-only

Per un ordine B2C_WEB da 800 €, lo stesso agente prenderebbe il catch-all 5% → 40 €.

Hook automatico al CONSEGNATO

Nel VinoOrdineHorecaController.transizione() quando lo stato cambia in CONSEGNATO:

public function transizione(Request $req, $id)
{
    $ordine = VinoOrdineHoreca::findOrFail($id);
    $ordine->stato = $req->stato;
    $ordine->save();

    // Hook provvigione: best-effort, non blocca
    if ($ordine->stato === 'CONSEGNATO') {
        try {
            app(VinoProvvigioneCalculatorService::class)
                ->calcolaPerOrdine($ordine);
        } catch (\Throwable $e) {
            \Log::warning('provvigione_calcolo_fallito', [
                'ordine_id' => $ordine->id,
                'error' => $e->getMessage(),
            ]);
        }
    }

    return response()->json($ordine->fresh());
}

Il best-effort evita che un errore di matching agente blocchi il workflow ordine. Se il calcolo fallisce, l’amministrativo vede l’ordine senza provvigione associata e può lanciare il calcolo manualmente.

Snapshot immutabile

Il punto cruciale: una volta calcolata, la provvigione non cambia. Anche se l’amministratore modifica la percentuale dello scaglione successivamente, le provvigioni già calcolate mantengono il loro valore originale.

Questo perché il record vino_provvigioni_calcoli salva la percentuale_applicata come snapshot al momento del calcolo. Ogni modifica successiva non retroattiva.

Se serve ricalcolare (es. errore evidente nello scaglione iniziale), si annulla il record (stato = ANNULLATA) e si ricalcola — visibile in audit log come correzione esplicita.

Report periodo

/vino/distribuzione/provvigioni ha 2 tab:

Tab “Calcoli”

Lista paginata di tutti i calcoli del periodo selezionato. Ogni riga: agente, ordine, importo imponibile, percentuale applicata, provvigione, stato. Bottone “Pagata” per cambiare lo stato di una provvigione DA_PAGARE.

Tab “Report periodo”

Aggregazione per agente nel periodo:

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.

Pagamento provvigione

Quando paghi l’agente con bonifico, click “Pagata” sui calcoli inclusi nel pagamento. Lo stato passa a PAGATA e si registra data_pagamento. L’agente vede solo il “Da pagare” residuo nel proprio report.

Cosa cambia per la tua cantina

✓ Calcolo automatico al CONSEGNATO, niente Excel a fine mese ✓ Scaglioni per agente (non un’unica percentuale globale) ✓ Snapshot immutabile — niente discussioni su cosa è cambiato ✓ Report periodo con drill-down per agente ✓ Workflow pagamento esplicito con audit log ✓ Idempotenza — un ordine = una provvigione per agente, sempre

Tempo amministrativo per provvigioni agenti: passa da 2-4 ore/mese a 5 minuti (controllo report + pagamento bonifici).

Esplora edition Vino →