Laravel multi-tenant per marketplace e retail multi-brand: valutazione delle scelte architetturali

Laravel multi-tenant si applica a due problemi distinti che spesso vengono discussi come se fossero uno solo.

Un marketplace ha molti venditori indipendenti che non si fidano tra loro, utilizzi molto variabili, onboarding self-service e un unico storefront pubblico. Un gruppo retail multi-brand ha pochi tenant sotto un unico proprietario, utilizzi simili, onboarding controllato e uno storefront separato per ogni brand. Hanno in comune la parola tenant e poco altro.

Definire l’architettura corretta significa chiarire quale dei due casi si sta realizzando, perché molte scelte si ribaltano tra uno e l’altro.

Tenant Resolution: la decisione da cui dipende tutto

Come l’applicazione determina a quale tenant appartiene una richiesta. Esistono tre soluzioni pratiche, che non sono equivalenti.

• Dominio o sottodominio — brand-a.example.com, oppure domini completamente separati. È la soluzione giusta per il retail multi-brand, dove ogni brand necessita di una propria identità, visibilità SEO e certificati separati.
• Prefisso di percorso — /sellers/acme/. Semplice, economico e mantiene tutto su un unico dominio, adatto a un marketplace dove il brand principale è quello del marketplace stesso.
• Contesto utente autenticato — nessun tenant nell’URL. Corretto per applicazioni back-office, sbagliato per tutto ciò che ha uno storefront pubblico, perché lo stesso URL produce contenuti diversi per utenti diversi e la cache diventa problematica.

Risolva il tenant una sola volta, nel middleware, prima che venga eseguito qualsiasi altro componente, e lo colleghi al container. Ogni parte successiva del codice deve poter chiedere chi è il tenant corrente senza conoscere il meccanismo di risoluzione — questo consente di modificare la risposta in seguito.

Isolamento dei dati

Abbiamo analizzato i tre modelli di tenancy — schema condiviso, schema per tenant, database per tenant — e i relativi costi in il confronto tra modelli di tenancy. Qui contano le meccaniche specifiche di Laravel.

Per schema condiviso, adatto alla maggior parte dei marketplace:

• Applichi lo scoping a livello globale, non per singola query. Gli scope globali di Laravel funzionano, ma il controllo più solido è la row-level security nel database — perché uno scope globale può essere rimosso da uno sviluppatore di fretta, mentre una policy a livello di database no.
• Renda evidente la query senza tenant. Faccia sì che il modello base lanci un'eccezione quando non è presente un tenant, così un job che dimentica di impostare il contesto fallisce subito invece di leggere tutto.
• Controlli le query raw e il codice di reportistica. Le chiamate al query builder che aggirano Eloquent aggirano anche gli scope. Qui avvengono le fughe di dati.
• Indicizzi prima su tenant_id negli indici compositi, altrimenti ogni query scansiona più dati del necessario.

Per database per tenant, soluzione adatta a gruppi multi-brand con reali esigenze di separazione, le meccaniche cambiano: switch della connessione nel middleware, migrazioni per tenant che devono essere resilienti ai fallimenti parziali sull'intero parco, e prefisso di cache e coda per ogni tenant per evitare contaminazioni. Tutto questo è prassi consolidata; va automatizzato prima di avere numeri reali di tenant, non dopo.

Le code sono il punto critico della multi-tenancy

La parte che la maggior parte delle implementazioni sbaglia, e che genera gli incidenti peggiori.

1. Serializzi sempre il tenant nel job. Un job che risolve il tenant da un contesto ambientale finirà prima o poi per operare nel contesto sbagliato, e il fallimento sarà silenzioso e cross-tenant.
2. Ripristini il contesto del tenant all'inizio di ogni job e faccia fallire in modo esplicito se non è possibile stabilirlo.
3. Isole i tenant rumorosi. Un venditore che importa 200.000 prodotti non deve rallentare la conferma degli ordini degli altri tenant. Separi le code almeno per tipologia di carico, e imponga limiti di velocità per tenant dove non sono affidabili.
4. Faccia sì che i comandi schedulati iterino esplicitamente sui tenant, con isolamento dei fallimenti per tenant — i dati errati di un tenant non devono interrompere l'esecuzione per tutti.
5. Pensi ai job falliti. Una tabella dei job falliti senza contesto tenant è inutilizzabile su larga scala, e il retry alla cieca porta a scritture cross-tenant.

Problemi specifici dei marketplace

Problemi che un gruppo multi-brand non deve mai affrontare:

• Pagamenti e incassi suddivisi. Un ordine che coinvolge tre venditori è un solo pagamento e tre incassi, con commissioni, rimborsi, chargeback e imposte attribuiti correttamente. Di solito è il problema di dominio più complesso e riguarda la finanza, non l'ingegneria.
• Onboarding e verifica dei venditori. Il self-service implica input non affidabili su larga scala — controlli di identità, verifica bancaria, screening antifrode.
• Controllo qualità. Dati prodotto, immagini e prezzi arrivano da migliaia di fonti senza uno standard condiviso. Chi gestisce la qualità del catalogo determina l'esperienza cliente.
• Pianificazione equa. Ogni risorsa condivisa — code, indicizzazione della ricerca, limiti di velocità API, generazione report — necessita di una policy di equità, altrimenti il tenant più grande consuma tutta la piattaforma.
• Analytics lato venditore che devono essere veloci, isolati e incapaci di rivelare dati di altri venditori.

Abbiamo già realizzato questa architettura — il marketplace multi-vendor di Scout Arabia e PriceGuru operano entrambi in questo modo, su stack diversi ma con problemi strutturali identici. Cambia la piattaforma commerce; la riconciliazione dei pagamenti resta.

Problemi tipici dei gruppi multi-brand

L'insieme inverso:

• Catalogo condiviso con override per brand. Un prodotto, venduto da tre brand, a tre prezzi, con tre descrizioni, e una modifica al prodotto base deve propagarsi in modo prevedibile.
• Reportistica consolidata tra brand, mentre ogni brand vede solo i propri dati.
• Identità cliente condivisa — o volutamente no. Prima di tutto è una questione legale, poi tecnica, e varia a seconda della giurisdizione.
• Tematizzazione per brand che non diventi cinque codebase. La disciplina consiste in una libreria di componenti condivisa con token di brand, non in template duplicati.
• Inventario condiviso tra brand, che può essere un grande vantaggio o una fonte di conflitti continui a seconda di come opera l'azienda.

Cosa decidere prima di scrivere codice

1. Un utente può appartenere a più tenant? Adattare questo scenario a un modello di autenticazione che non lo prevedeva è uno dei refactoring più complessi.
2. L'identificatore del tenant è pubblico? Una volta che compare in URL e API, i clienti lo utilizzano e non è più possibile modificarlo liberamente.
3. Dove risiede la configurazione per tenant — nei dati del tenant o in un registro centrale? Entrambe le soluzioni funzionano; mescolarle no.
4. Cosa succede quando i tenant si fondono o si dividono? Evento raro e complesso. I marketplace si acquisiscono tra loro; i gruppi brand si ristrutturano.
5. Come lascia un tenant? L'esportazione completa e la cancellazione totale sono obblighi contrattuali in molti mercati, ed è molto più difficile aggiungerli dopo.

Questo è il lavoro che il nostro team Laravel svolge prima dell'avvio di un progetto, all'interno della nostra più ampia pratica su piattaforma Laravel. Per i gruppi retail la struttura multi-brand è la più comune; per le piattaforme di logistica e finanza si avvicina di più al modello marketplace.

Definire il modello correttamente, prima di tutto

La risoluzione del tenant, l'isolamento e il contesto delle code sono decisioni rapide ma costose da cambiare. Analizzeremo la sua soluzione rispetto all'architettura che sta realmente costruendo. Contatti il nostro team; rispondiamo entro un giorno lavorativo.