Portale Affiliati Multi-Lingua Real-Time

Il Contesto

Il progetto e stato realizzato per il programma di affiliazione di una societa di trading con operativita internazionale. Gli affiliati - introducing broker, partner di marketing e creator - portano nuovi clienti alla piattaforma e vengono remunerati in base ai volumi generati. Per ragioni di riservatezza il nome della societa, le commissioni applicate e i nomi degli affiliati non vengono divulgati.

Un affiliato vive di un'unica domanda, ripetuta ogni giorno: quanto ho generato e quanto mi spetta? Il pubblico e distribuito su piu paesi e parla lingue diverse, ma si aspetta la stessa cosa: un dato preciso, aggiornato e leggibile, senza dover scrivere a un account manager per averlo. Questo fissa fin dall'inizio due vincoli di prodotto: trasparenza del dato e autonomia dell'affiliato.

Il Problema

Senza un portale dedicato, un programma di affiliazione si regge su report manuali e scambi di email. Tre criticita concrete, definite con il team all'avvio:

• I dati arrivano in ritardo e a richiesta: l'affiliato chiede un report, qualcuno lo prepara, il numero e gia vecchio. Il ritardo erode la fiducia, perche chi non vede i propri numeri sospetta di guadagnare meno di quanto dovrebbe.
• La barriera linguistica frena l'espansione internazionale: un portale in una sola lingua taglia fuori interi mercati. La traduzione non puo essere un'aggiunta posticcia a fine progetto, va trattata come requisito architetturale fin dalla prima riga.
• I numeri grezzi non bastano: una tabella di transazioni non dice nulla a colpo d'occhio. Serve la visualizzazione - trend nel tempo, confronto tra periodi, ripartizione per fonte - perche l'affiliato capisca dove e come sta performando.

Sopra a tutto questo, il vincolo trasversale: il portale doveva essere self-service davvero. Ogni report scaricato in autonomia e una email in meno per il back office e un affiliato in piu che si fida del programma.

La Soluzione

L'architettura separa nettamente il frontend del portale, che deve essere veloce, internazionalizzato e gradevole da usare, dal backend dei dati, che deve aggregare le statistiche di affiliazione e servirle gia pronte per il consumo.

Frontend Nuxt 3

Il portale e costruito in Nuxt 3 con Vue 3: il rendering server-side garantisce un primo caricamento rapido e contenuti indicizzabili, mentre la navigazione successiva resta fluida come una SPA. Lo stato applicativo - sessione, filtri attivi, lingua selezionata - vive in Pinia, lo store ufficiale di Vue, che mantiene un'unica fonte di verita lato client senza la verbosita di soluzioni piu pesanti.

UI, multilingua e grafici

L'interfaccia combina i componenti pronti di PrimeVue - tabelle ordinabili e filtrabili, date picker, dialog - con un layout costruito in Tailwind per la coerenza visiva. Il supporto multilingua e gestito con i18n, con le stringhe esternalizzate in file di traduzione e cambio lingua a caldo, senza ricaricare la pagina. Le statistiche prendono forma con Chart.js: trend di conversione, andamento delle commissioni e ripartizione per fonte diventano grafici leggibili a colpo d'occhio.

Backend NestJS e Prisma

Il backend e un servizio NestJS che espone le API di reportistica e possiede la logica di aggregazione: raccoglie gli eventi di affiliazione, li consolida per affiliato e per periodo, e li serve gia calcolati cosi che il frontend non debba mai elaborare numeri grezzi. L'accesso ai dati passa per Prisma, che con il suo schema tipizzato garantisce query sicure e migrazioni controllate, riducendo la classe di bug piu insidiosa in un sistema che maneggia commissioni: il dato sbagliato servito come giusto.

Tecnologie Chiave

Lo stack privilegia un frontend moderno e produttivo, con TypeScript condiviso tra client e server per ridurre il context switch, e un accesso ai dati tipizzato dove la correttezza dei numeri non e negoziabile.

Il Risultato

Il portale e stato consegnato come prodotto completo: un'area self-service dove ogni affiliato consulta in autonomia le proprie performance, in tempo reale e nella propria lingua. Questi sono gli esiti chiave del progetto.

Gli indicatori riportati sono indicativi e stimati, su progetto soggetto a riservatezza: descrivono capacita tecniche effettivamente rilasciate, non commissioni, volumi o cifre commerciali, che non vengono divulgate.

Sfide Tecniche

1. Statistiche in tempo reale senza far elaborare numeri grezzi al client

Mostrare statistiche aggiornate e tabelle filtrabili senza appesantire il browser e una tensione classica delle dashboard data-heavy. Se il frontend riceve righe grezze e le aggrega da solo, su dataset grandi l'interfaccia si impalla; se il backend ricalcola tutto a ogni richiesta, le API rallentano. La soluzione e stata spostare l'aggregazione lato backend NestJS: gli eventi di affiliazione vengono consolidati per affiliato e per periodo e serviti gia pronti, mentre il frontend si limita a richiedere la vista che gli serve e a renderizzarla con PrimeVue e Chart.js. Il client resta reattivo anche con molti dati, perche non fa mai il lavoro pesante.

2. Multilingua come requisito architetturale, non come patch finale

L'errore piu comune e trattare la traduzione come l'ultimo task: stringhe hard-coded sparse nel codice che a fine progetto vanno cacciate una per una. L'internazionalizzazione e stata invece impostata fin dall'inizio con i18n, con tutte le stringhe esternalizzate in file di traduzione, formattazione di numeri e date sensibile alla lingua e cambio lingua a caldo gestito via Pinia, senza ricaricare la pagina. Aggiungere un nuovo mercato significa cosi aggiungere un file di traduzione, non riaprire il codice dell'interfaccia.

Il filo conduttore di entrambe le sfide e lo stesso principio: la complessita va spinta dove fa meno male. L'aggregazione sta sul backend, l'internazionalizzazione sta nella configurazione, e l'interfaccia resta leggera e pronta a scalare su nuovi mercati.