Coupon / sconti

Modulo «Coupon / sconti»: motore promozionale per generare, distribuire, validare e tracciare codici sconto applicabili a checkout, prenotazioni, abbonamenti, fatture (#8322), ordini e-commerce, iscrizioni a corsi/eventi. Supporta sia codici a inserimento manuale dal cliente (es. `BENVENUTO10`, `ESTATE2026`) sia link magici con coupon pre-applicato (es. `https://app/checkout?coupon=AMICO20`) sia distribuzione massiva via mail #8331/SMS #8332/area cliente #8326. Modello dati: tabella `coupons` (codice univoco case-insensitive trimmed, descrizione interna admin, descrizione_pubblica mostrata a cliente al successo, tipo_sconto `percentuale`/`fisso`/`spedizione_gratuita`/`omaggio_prodotto`/`upgrade_gratuito`, valore_sconto decimale (es. 10 per 10% o 15.00 per €15), valuta_sconto default `EUR`, importo_minimo_ordine soglia carrello per applicabilità (es. usabile solo se carrello >€50), importo_massimo_sconto cap su sconto percentuale (es. -20% ma max €50 di sconto), data_inizio_validita timestamp opzionale, data_fine_validita timestamp con timezone Europe/Rome, max_utilizzi_globale intero (totale usi su tutti i clienti, null=illimitato), max_utilizzi_per_cliente intero (es. 1 per coupon una-tantum, null=illimitato), utilizzi_effettuati contatore atomico, stato `attivo`/`sospeso`/`esaurito`/`scaduto`/`archiviato`, tipo_coupon `pubblico`/`privato`/`monouso_personale`/`omaggio`/`fidelizzazione`/`recupero_carrello`/`compleanno`/`influencer_affiliato`, creator_user_id, brand_id per multi-brand, lingua_default, note_interne, metadata JSON), tabella `coupon_rules` (coupon_id, tipo_regola `prodotti_inclusi`/`prodotti_esclusi`/`categorie_incluse`/`categorie_escluse`/`clienti_inclusi`/`clienti_esclusi`/`gruppi_clienti`/`primo_acquisto`/`solo_nuovi_clienti`/`solo_clienti_storici`/`paesi_inclusi`/`paesi_esclusi`/`canali_vendita`/`combinabile_con_altri`/`giorno_settimana`/`fascia_oraria`/`stagione`, valore JSON con id/parametri della regola, operatore logico AND/OR per stratificare, priorità) per regole di applicabilità complesse, tabella `coupon_redemptions` (coupon_id, cliente_id, ordine_id/booking_id/fattura_id riferimento polimorfico, importo_sconto_applicato, importo_ordine_originale, importo_ordine_finale, data_utilizzo, stato `applicato`/`stornato`/`rifiutato_post_validazione`, ip_origine, user_agent, canale `web`/`mobile`/`pos`/`admin_manuale`/`api`, motivo_storno opzionale) per audit utilizzi, tabella `coupon_distributions` (coupon_id, destinatario_email/telefono/cliente_id, canale `email`/`sms`/`area_cliente`/`stampa_qr`/`link_pubblico`, data_invio, aperto bool, cliccato bool, riscattato bool) per tracking distribuzione, tabella `coupon_campagne` (nome, descrizione, obiettivo `acquisizione`/`riattivazione`/`retention`/`upsell`/`recupero_carrello`/`compleanno`/`evento_speciale`, budget_max_sconti, kpi_target, data_inizio, data_fine, attiva bool) per raggruppare coupon per campagna marketing. Tipi sconto: (1) percentuale fissa (es. -10% su totale carrello, -20% su prodotto X), (2) importo fisso (es. -€15 sul totale, -€5 per prodotto), (3) spedizione gratuita (azzera costo spedizione lasciando subtotale invariato), (4) prodotto omaggio (aggiunge automaticamente prodotto Y al carrello con prezzo 0 se condizione X), (5) upgrade gratuito (es. da camera standard a deluxe a parità prezzo, da abbonamento mensile a annuale), (6) BOGO buy-one-get-one (compra X paghi Y, configurabile 2x1, 3x2, ecc.), (7) sconto progressivo a soglie (es. -5% sopra €50, -10% sopra €100, -15% sopra €200), (8) sconto su seconda unità (-50% sulla seconda referenza identica), (9) cashback in wallet/punti fidelizzazione invece di sconto immediato. Regole di applicabilità: filtri «coupon usabile solo su prodotti categoria X», «non cumulabile con saldi attivi», «valido solo per nuovi clienti» (verifica `cliente.ordini_count == 0`), «valido solo per clienti VIP» (verifica `cliente.tag includes vip` o `cliente.ltv > soglia`), «valido solo nel weekend», «valido solo in primavera», «valido solo per ordini >€50», «cap massimo sconto €30», «non valido in combinazione con altri coupon attivi nel carrello», «massimo 1 utilizzo per cliente», «massimo 500 utilizzi totali poi disabilitazione automatica», «scadenza fissa il 31/12/2026», «scadenza dinamica X giorni dopo emissione» (utile per coupon di benvenuto personalizzati), engine di valutazione regole con cache risultato e short-circuit su fallimento prima regola critica. Validazione real-time in checkout: endpoint Laravel `POST /api/coupons/validate` con input (codice, carrello, cliente_id) e output (valido bool, sconto_calcolato, errore_specifico se non valido tipo `inesistente`/`scaduto`/`esaurito`/`gia_usato_da_questo_cliente`/`carrello_sotto_soglia`/`prodotti_non_ammessi`/`cliente_non_ammesso`/`combinazione_non_consentita`/`paese_non_ammesso`), validazione UI inline su input change con debounce 300ms e feedback immediato (verde+importo se valido, rosso+messaggio se non valido), pre-applicazione coupon via querystring URL (`?coupon=CODICE` decodificato e tentata applicazione automatica al primo accesso checkout con persistenza in sessione/cookie 30 giorni), tooltip educativo «hai un codice promo?» con campo nascosto espandibile per non confondere clienti senza coupon. Calcolo sconto: motore di calcolo con priorità (sconto su singola riga prodotto > sconto su categoria > sconto su totale carrello), gestione arrotondamenti centesimi (HALF_UP standard italiano), gestione IVA inclusa vs esclusa (sconto applicato su imponibile poi ricalcolo IVA per coerenza con fatturazione #8322), non-cumulabilità configurabile (un solo coupon per ordine vs combinabili con regola di precedenza vs combinabili con tetto massimo cumulativo), tracking voce «sconto coupon» separata in righe ordine/fattura per trasparenza, calcolo cashback se tipo speciale con bonifico/credito virtuale post-completamento ordine. Generazione codici: codici manuali admin scelti dall'operatore (vanity codes leggibili tipo `BENVENUTO10`, `ESTATE2026`, `AMICO20`), codici massivi auto-generati con pattern configurabile (prefisso+random N caratteri, es. `WELCOME-ABC123XYZ`, `BLACKFRIDAY-9F2K7L`), generazione batch con quantità (es. 10.000 codici monouso unici per campagna influencer), export CSV/Excel #8328 per consegna a partner, hash unicità DB-level (constraint unique su codice), regole anti-collisione su generazione random, supporto QR code generato da codice per stampa/condivisione, supporto link firmato con coupon embedded `URL::temporarySignedRoute` non manipolabile. Distribuzione: invio mail #8331 con template `coupon_benvenuto` (saluto + codice in box prominente + CTA «Usa ora» + condizioni d'uso + scadenza visibile), invio SMS #8332 per coupon urgenti/lampo (`COD: ESTATE10 -10% solo oggi, vai a x.it`), pubblicazione su area cliente #8326 (sezione «I miei coupon» con stato attivo/usato/scaduto + scadenza + CTA usa), banner sito frontend con landing page dedicata `/promo/{slug}`, pubblicazione su social media via API (Meta/Instagram), distribuzione tramite affiliate/influencer (codice personale per ogni partner con tracking conversioni e commissioni payout). Trigger automatici di emissione coupon: nuovo cliente registrato → coupon benvenuto 10% scadenza 30gg, compleanno cliente → coupon dedicato 15% scadenza 14gg, carrello abbandonato 24h → mail recupero #8331 con coupon -5% scadenza 7gg, cliente inattivo da 90 giorni → coupon riattivazione 20% scadenza 30gg, milestone fidelizzazione (es. 10° acquisto) → coupon premio, recensione lasciata su Google/Trustpilot → coupon ringraziamento, post-acquisto se importo elevato → coupon next-purchase «torna entro 60gg per -15%», post-evento prenotazione completata → coupon repeat-booking, referral amico che completa primo acquisto → coupon riconoscimento sia per referrer sia per referred. Pannello admin: lista coupon con datatable Livewire (filtri per stato/tipo/scadenza/utilizzo, sort, paginazione, ricerca codice), creazione/edit form con tutti i campi e tab regole, preview live calcolo sconto su carrello mock, dashboard KPI per ogni coupon (utilizzi, conversion rate, valore medio ordine con coupon vs senza, ROI campagna, top coupon performanti, top utilizzatori), grafico distribuzione utilizzi nel tempo (per individuare picchi e segnalare codici virali leak da forum/Telegram di coupon-hunters), action rapide (sospendi temporaneamente, archivia, duplica con nuove date, estendi scadenza in massa, esporta CSV utilizzi), bulk action su selezione (es. disattiva tutti i coupon natalizi post-Befana). Anti-abuso: rate-limiting su endpoint validate (max 10 tentativi al minuto per IP per evitare brute-force su codici corti), throttling su coupon-hunting (alert admin se stesso IP prova >50 codici diversi in 1h), restrizione a 1 coupon-per-cliente con verifica via email/CF/IP/device_fingerprint (impedire creazione account multipli per riusare coupon benvenuto), validazione email/SMS prima di emissione coupon nominali, blocklist email temporanee (10minutemail/Yopmail/...) per evitare farming coupon benvenuto, validazione codice fiscale italiano se richiesto da regola, audit log #8330 di ogni utilizzo coupon con timestamp/IP/UA/risultato per indagini post-frode, segnalazione automatica pattern sospetti (es. stesso device usa 10 coupon benvenuto con 10 account diversi → freeze account e indagine manuale). Storno e refund: integrazione con refund Stripe #8324 (se ordine pagato e poi rimborsato totalmente, marca redemption come `stornata` e ripristina utilizzo se coupon era monouso per cliente), nota credito automatica #8322 con riga coupon stornata, gestione rimborso parziale (proporzionale o full a discrezione admin). Multi-brand e multi-lingua: ogni coupon appartiene a un brand specifico con sue regole (operatore brand A non vede coupon brand B), descrizione_pubblica multilingua (`it`/`en`/`es`/`de`/`fr`) per audience internazionale, valuta sconto multipla (EUR/USD/GBP/CHF) con conversione tasso configurabile. Integrazioni: motore checkout (HSD noleggi #8324 prenotazione con caparra Stripe, e-commerce ordini, abbonamenti #8332 SMS welcome bundle, corsi/eventi, fatturazione #8322 dove sconto appare come riga negativa o nota in piedipagina, area cliente #8326 sezione «I miei coupon», audit log #8330 immutabile, mail transazionali #8331 distribuzione+notifica, SMS gateway #8332 per coupon flash, export #8328 per analisi e bilanci commercialista, datatable Livewire generica #8327, sync calendar #8325 se coupon applicabile a slot specifici, anagrafica clienti #8327 per segmentazione e regole). Comandi artisan: `php artisan coupons:scaduti` (cron giornaliero notte, marca come `scaduto` tutti i coupon con `data_fine_validita < now` e libera risorse), `php artisan coupons:emetti-compleanni` (cron giornaliero alba, scan clienti con compleanno oggi, emette coupon nominale e schedula invio mail/SMS), `php artisan coupons:recupero-carrelli` (cron orario, scan carrelli inattivi da 24h, emette coupon recupero e invia mail), `php artisan coupons:report-campagna {campagna_id}` (report PDF dettagliato con KPI per stakeholder), `php artisan coupons:purge-redemptions-vecchie --da-anni=3` (anonimizzazione per GDPR su utilizzi >3 anni mantenendo aggregati). Casi d'uso: e-commerce (Black Friday/Cyber Monday/saldi, codici influencer affiliato con commissione, codici stampa cartacea con QR per offline-to-online), prenotazioni HSD (early-bird «-15% se prenoti con 30gg di anticipo», last-minute «-20% partenza nei prossimi 7gg per riempire flotta», codici partner agenzie viaggi/hotel partner), studi medici/poliambulatori (sconto pacchetti visite, riattivazione pazienti inattivi da 12 mesi), corsi/eventi (early-bird, sconto gruppo se prenotano in N persone, codice membership), hotel/B&B (sconto soggiorni infrasettimanali, codice canale OTA-bypass per booking diretto, codice clienti ricorrenti), gestionali B2B (sconto upfront se pagamento annuale anziché mensile, sconto upgrade piano, codice partner reseller). Dashboard analytics: ROI per campagna (`(fatturato attribuito coupon - sconti erogati - costi distribuzione) / costi`), conversion rate (% coupon distribuiti effettivamente riscattati), AOV (Average Order Value) con coupon vs baseline senza coupon, customer LTV uplift attribuito a coupon di acquisizione, segmentazione utilizzatori (nuovi vs storici, premium vs price-sensitive), heatmap utilizzo per orario/giorno della settimana, embed widget dashboard #8328 per export Excel/PDF stakeholder. Differenza da semplice campo «codice sconto» hardcoded in checkout: qui motore configurabile da admin senza dev, multiplo coupon attivi simultanei con regole, tracking attribuzione, scadenze dinamiche, distribuzione multicanale. Differenza da gestionali e-commerce all-in-one (Shopify/WooCommerce coupon nativi): qui integrato custom nei flussi prodotto Footility-style con possibilità regole specifiche del dominio (es. coupon valido solo su slot weekend per #8323 disponibilità calendario, coupon valido solo su prenotazioni con caparra #8324 e non saldi). Differenza da piattaforme dedicate (Klaviyo/ActiveCampaign coupon): qui no esportazione dati clienti a terze parti, full ownership dati, prezzo zero su ricorrenze, integrazione DB diretta senza sync. Estensioni future: AI per coupon personalizzato per cliente (predict valore sconto minimo che converte vs spreco margine), gamification (gratta-e-vinci coupon, ruota della fortuna login giornaliero, missione settimanale), coupon dinamico mostrato in-app quando cliente esita su checkout (`time-on-page>30s` + `idle>5s` → popup coupon esclusivo), integrazione wallet Apple/Google con coupon in tasca scansionabili in POS fisico, codice referral bidirezionale con tracciamento multi-hop, bundle multi-coupon (es. 3 coupon utilizzabili separatamente da regalo a 3 amici), supporto criptovalute (sconto in token/NFT). Costo: 1 giorno modello dati + migration + seeder tipi sconto + regole base, 2 giorni motore validazione + calcolo sconto + integrazione checkout flussi Footility (carrello/booking/fattura), 1 giorno admin panel datatable Livewire + form CRUD coupon + tab regole + preview, 1 giorno engine regole applicabilità con cache + audit, 1 giorno distribuzione (mail/SMS/area cliente/link firmato) + tracking apertura/click/redemption, 1 giorno trigger automatici (benvenuto/compleanno/recupero/riattivazione) con cron, 1 giorno dashboard KPI + grafici utilizzi/ROI + export #8328, 0.5 giorno anti-abuso (rate-limit/throttling/audit log #8330), 0.5 giorno storno+refund integrazione #8324 e nota credito #8322, 1 giorno testing flussi (validazione, redemption concorrente con lock, scadenza, storno, bulk generation). Dipendenze: modulo carrello/checkout esistente (Footility-style), #8327 anagrafica clienti per segmentazione e regole nominali, #8331 mail transazionali per distribuzione, opzionale #8332 SMS gateway per coupon flash, #8328 export per report stakeholder, #8330 audit log per tracking utilizzi e indagini anti-frode, #8322 fatturazione per integrare riga sconto e nota credito su storno, #8324 Stripe per refund e collegamento payment_intent, #8326 area cliente per sezione «I miei coupon».