Workflow: Comision Agenți Vânzări

Module implicate: Invoices · Payments · Commission (Policy · Applicable Staff · Hierarchy · Receipt) · Sales Agent · Goals · DataPulse
Cine îl folosește: Manager Vânzări · Agenți de Vânzări · Administrator Financiar
Durata tipică: Instantaneu după plata facturii (trigger automat) + ciclu lunar pentru plata comisioanelor

Overview

Modulul Commission calculează automat comisionul datorat unui agent de vânzări în momentul în care o factură este plătită. Nu necesită nicio acțiune manuală pentru calculul propriu-zis — totul se declanșează prin hook-ul after_payment_added. Fluxul complet acoperă: configurarea politicii de comision, asignarea agenților la politici, calculul automat la plată, vizualizarea comisioanelor acumulate și plata efectivă prin emiterea unui Commission Receipt.

Atenție: Comisionul se calculează doar pe facturi standard din CRM (tblinvoices). Facturile din modulul Sales Agent (sa_sale_invoices) nu declanșează comisionul.

Diagrama fluxului

[CONFIGURARE — o singură dată]
  │
  ├── Commission Policy (tip 1–5, interval date, procent/scară)
  ├── Applicable Staff → asignare agent la politică
  ├── Hierarchy (opțional) → coordinator primește % din comisionul agentului
  └── Opțiuni generale → calculate_after_days · payment_trigger_mode
  │
  ↓
[FACTURARE]
  │
  ├── Factură creată → sale_agent setat pe factură (sau pe client/grup)
  └── Status factură: Draft → Sent
  │
  ↓
[PLATĂ FACTURĂ — trigger automat]
  │
  ├── Payment înregistrat → hook after_payment_added se declanșează
  ├── Sistem verifică: vârstă factură ≥ calculate_after_days?
  ├── Sistem verifică: payment_trigger_mode?
  │     'partial_allowed' (implicit) → orice plată > 0 generează comision
  │     'full_only' → comision doar dacă suma plăților = totalul facturii
  ├── Sistem verifică: factură eligibilă? (nu e stornată, status valid)
  └── Sistem rezolvă agentul: sale_agent pe factură → customer_admin al clientului
        → commission_salesadmin_group (grup client → agent)
  │
  ↓
[COMISION GENERAT]
  │
  ├── Rând creat în tblcommission: staffid, invoice_id, amount, paid=0
  ├── Tip 1–4: calculat imediat per factură
  └── Tip 5 (lunar/marjă): calculat de cron în ziua commission_month_close_day
  │
  ↓
[APROBARE / VIZUALIZARE]
  │
  ├── Manager → /admin/commission → vede comisioanele cu paid=0
  ├── Agent → vede propriile comisioane (permisiune commission_manage → view)
  └── Rapoarte: commission_chart · staff_monthly_dashboard
  │
  ↓
[PLATĂ COMISION]
  │
  ├── Manager creează Commission Receipt: selectează comisioane neachitate
  ├── Receipt poate fi convertit în Expense (pentru evidență contabilă)
  └── Comisioanele selectate → paid=1 în tblcommission
  │
  ↓
[COMISION PLĂTIT ✓]

Pas cu pas

1. Configurare inițială (admin)

1a. Politica de comision

Unde: /admin/commission → Commission Policy → New Policy

Există 5 tipuri de politici (commission_policy_type):

Câmpuri esențiale la creare:

Important: Dacă calculate_after_days este negativ, sistemul folosește automat 14 zile.

1b. Asignare agent la politică

Unde: /admin/commission → Applicable Staff → Add

Leagă un angajat (staffid) de o politică (commission_policy_id) prin tabelul tblcommission applicable_staff. Un agent poate fi asignat la mai multe politici cu date diferite.

Pentru comisioane de tip vendor/client: Applicable Client (se setează is_client=1 și commission_receiver_vendor_id pe fișa clientului).

1c. Ierarhie comisioane (opțional)

Unde: /admin/commission → Settings → Hierarchy

Permite unui coordinator să primească un procent din comisionul agentului din subordine:

1d. Opțiuni generale

Unde: /admin/commission → Settings → Commission General

2. Rezolvarea agentului pe factură

Când o factură este plătită, sistemul determină agentul în această ordine:

1. invoices.sale_agent — agentul setat direct pe factură
2. tblcustomer_admins.staff_id — adminul de cont al clientului (dacă sale_agent e gol)
3. tblcommission_salesadmin_group — mapare grup client → agent (dacă primele două sunt goale)

Gotcha: Dacă niciunul din cele trei nu e configurat, nu se generează comision și nu apare nicio alertă. Verificați întotdeauna că facturile au sale_agent setat sau că clienții au customer admin.

3. Calculul automat la plată

Când se înregistrează o plată (/admin/invoices/:id → Add Payment sau via API), hook-ul after_payment_added apelează Commission_model::add_commission($payment_id).

Verificări efectuate de sistem (dacă oricare eșuează, comisionul NU se generează):

Fallback cron: La fiecare commission_cron_interval_minutes minute, un job verifică facturile cu plăți care au ratat hook-ul și generează comisioanele lipsă.

Regenerare manuală (admin):

• Pe factură: butonul Regenerate Commission
• Bulk: /admin/commission → Recalculate (necesită permisiunea commission → create)

4. Comisioane de tip 5 — Marjă lunară

Diferit față de tipurile 1–4: calculul nu se face per plată, ci lunar în cron.

În ziua commission_month_close_day a lunii (implicit ziua 1), run_staff_monthly_commissions() calculează pentru luna anterioară:

• Agregă toate facturile plătite din luna respectivă per agent
• Calculează marjă netă (sales_net, avg_margin, avg_discount)
• Aplică tier-urile din staff_margin_settings JSON
• Scrie în tblcommission_staff_monthly (status: draft)
• Scrie detalii per factură în tblcommission_staff_monthly_detail

5. Vizualizare și aprobare comisioane

Unde: /admin/commission

6. Plata comisionului

Unde: /admin/commission → Commission Receipts → New Receipt

Pași:

1. Selectați comisioanele neachitate (paid=0) de inclus în plată
2. Completați: amount, paymentmode, date, note, transactionid
3. Salvați → sistemul marchează toate tblcommission selectate cu paid=1
4. Opțional: bifați Convert to Expense pentru a genera automat o cheltuială în modulul Expenses (pentru evidență contabilă)

Permisiuni necesare: commission_receipt → create + commission_receipt → view

Permisiuni necesare

Gotchas

Referințe module

• Commission — rapoarte
• Invoices — câmpul sale_agent
• Payments — trigger-ul plății
• Sales Agent — programele de discount (separate de comision)
• Goals — target-uri per agent
• DataPulse — dashboard performanță echipă