Documentazione MMIS

Passaggi di installazione e un riferimento completo per ogni campo e funzione dell'admin, con esempi concreti — lo stesso livello di dettaglio che usiamo per assistere i clienti.

Installazione

Requisiti

Magento 2.4.x — testato su 2.4.9, compatibile con le versioni 2.4.* precedenti. PHP 8.1–8.5. Compatibile sia con il tema Luma di default sia con il tema Hyvä.

Passaggi di setup

1. Aggiungi le credenziali ricevute via email ad auth.json nella root del progetto Magento:
```
{ "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } }
```
2. composer config repositories.codingrow composer https://repo.codingrow.com
3. composer require codingrow/module-mmis
4. bin/magento module:enable Codingrow_Mmis
5. bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush
6. Incolla la chiave di licenza in Admin → Stores → Configuration → Codingrow Extensions → MMIS → License → License Key, salva, poi bin/magento cache:flush.

L'intera interfaccia di amministrazione — ogni etichetta, tooltip e guida — è disponibile in 7 lingue, selezionate automaticamente per utente admin:

Italiano English Español Français Deutsch Português Nederlands

Disinstallazione

composer remove codingrow/module-mmis poi bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush. I prodotti già importati non vengono mai toccati automaticamente — usa prima lo strumento di rollback se vuoi rimuoverli anche loro.

Guida utente

Profili di importazione

Ogni fornitore/feed da cui importi è un Profilo a sé: feed proprio, mapping proprio, pianificazione propria, impostazioni proprie — completamente indipendente da ogni altro profilo. Puoi eseguire tanti profili quanti sono i tuoi fornitori, parallelamente, sullo stesso catalogo, e ciascuno tocca solo i prodotti che ha creato lui stesso (mai un prodotto creato manualmente da un operatore, anche se condividesse lo stesso prefisso SKU).

Sorgente e formato del feed

Un profilo legge il proprio feed da una di tre sorgenti:

Sorgente	Cosa configuri
URL (default)	Un link HTTP/HTTPS diretto. Supporta in modo trasparente feed compressi `.zip` (rilevati dalla firma del file, non dall'estensione).
File system Magento	Un percorso dentro l'installazione Magento (es. `var/import/feed.csv`) — utile se il fornitore deposita file via SFTP in una cartella che controlli.
Server FTP	Host + utente + password (salvata cifrata) — il modulo si connette e scarica il file da solo.

Sono supportati tre formati di feed: CSV (delimitatore configurabile: virgola, punto e virgola o tab), XML (indichi quale elemento ripetuto rappresenta un prodotto) e JSON (array di oggetti).

Mapping delle colonne

Sei campi sono sempre richiesti (Nome prodotto, Prezzo, Quantità/Stock, Peso, EAN, Marca) — ciascuno ha la propria riga con colonna sorgente, valore di default e trasformazione. Oltre a questi sei, puoi aggiungere quante righe di mapping libere vuoi, verso qualunque attributo Magento reale (non solo un elenco fisso di campi storici) — inclusi attributi personalizzati creati da te.

Esempio — un feed fornitore ha una colonna prezzo_base per il prezzo e peso_kg per il peso: mappa "Prezzo" → colonna sorgente prezzo_base, "Peso" → colonna sorgente peso_kg. Il nome della colonna non conta mai, conta solo su quale colonna punti ciascuna riga.

Trasformazioni e funzioni di testo

Ogni riga di mapping ha un tipo di "Trasformazione":

Trasformazione	Cosa fa
Nessuna	Copia diretta del valore della colonna sorgente.
Valore statico	Ignora la colonna sorgente, usa sempre il testo fisso digitato in "Valore".
Template di testo	Testo libero con segnaposto `{NomeColonna}` — vedi funzioni sotto.
Cerca e sostituisci	Ricerca senza distinzione tra maiuscole/minuscole nel valore della colonna sorgente, sostituito con il tuo testo (esattamente come digitato).
Formula matematica	Un'espressione autonoma — vedi Formule matematiche più sotto.

Dentro un Template di testo, oltre al semplice segnaposto {NomeColonna}, sono disponibili sette funzioni (solo per campi di testo):

Funzione	Effetto	Esempio
`ucase{Colonna}`	TUTTO MAIUSCOLO	`ucase{Marca}` → "ACME"
`lcase{Colonna}`	tutto minuscolo	`lcase{Marca}` → "acme"
`proper{Colonna}`	Iniziale Maiuscola Per Ogni Parola	`proper{nome}` → "barra rossa" → "Barra Rossa"
`trim{Colonna}`	Rimuove gli spazi iniziali/finali	—
`left{Colonna,N}`	Primi N caratteri	`left{SKU,5}`
`val{Colonna}`	Normalizza un numero in formato europeo ("1.234,56") nel formato standard ("1234.56"), senza arrotondare i decimali	—
`replace{Colonna,'cerca','nuovo'}`	Cerca/sostituisce solo dentro quel valore (ricerca case-insensitive), usabile dentro un template più ampio	`replace{nome,'Rif.','Riferimento'}`

Esempio combinato — template {ucase{Marca}} - {proper{nome}} su una riga dove Marca="acme" e nome="barra rossa" produce "ACME - Barra Rossa". Un nome di funzione scritto male resta visibile invariato nell'output invece di sparire silenziosamente, così un errore di battitura si nota sempre.

Formule matematiche

Solo per campi numerici (Prezzo, Peso, Quantità, o un attributo personalizzato numerico): un'espressione autonoma con segnaposto {NomeColonna}, i quattro operatori base (+ - * /) e le parentesi — nient'altro (nessuna funzione, nessun confronto). Il risultato viene sempre arrotondato a un massimo di 2 decimali.

Esempio — "Prezzo" con formula {Prezzo B2B} * 1.30 applica un ricarico del 30% sul prezzo all'ingrosso del fornitore. ({prezzo} + {costo_spedizione}) / 1.22 aggiunge la spedizione e poi rimuove il 22% di IVA per ottenere un prezzo netto.

Sostituzione testo su più campi

Una regola di cerca-e-sostituisci che può agire su più colonne grezze del feed contemporaneamente, eseguita prima ancora che inizi il mapping. Ripulire una colonna alla sorgente si propaga a ogni riga di mapping che la legge — invece di ripetere la stessa correzione su ogni campo derivato separatamente.

Esempio — colonne "Titolo_prodotto, Descrizione_HTML" (due campi insieme), cerca "CODICEFORNITORE ", sostituisci con niente → rimuove un prefisso fornitore da entrambe le colonne grezze in un colpo solo, così "Nome prodotto" e "Descrizione", se mappati da quelle colonne, arrivano già puliti.

Filtri di importazione (Gruppi/Regole)

Ogni riga del feed attraversa tre filtri, sempre in quest'ordine — un filtro successivo vede solo le righe sopravvissute a quello precedente:

Categorie feed consentite — sempre per prima. Una categoria non in elenco scarta la riga qui, prima ancora che un Gruppo venga considerato.
Gruppi/Regole — opzionale. Se nessun Gruppo è configurato, ogni riga sopravvissuta al passo 1 passa inalterata. Se esiste almeno un Gruppo, passano solo le righe catturate da un Gruppo — le righe non catturate da nessun Gruppo vengono scartate (diverso da "nessun filtro").
Categoria di destinazione del Gruppo — se impostata dentro il Gruppo che ha catturato la riga, sostituisce interamente il percorso categoria; se lasciata vuota, si usa il percorso categoria del feed così com'è.

Esempio — categorie consentite = "Casa e Giardino, Articoli Sportivi"; un Gruppo "Solo sedie" con regola "nome contiene sedia" e categoria di destinazione "Arredamento/Sedie". Una riga "Sedia da ufficio" nella categoria feed "Casa e Giardino > Sedie" supera il passo 1, viene catturata al passo 2 e finisce sotto "Default Category/Arredamento/Sedie" — non sotto "Casa e Giardino/Sedie" come suggerirebbe il feed da solo.

Nota: non appena esiste un Gruppo, gli articoli non catturati da nessuna Regola vengono scartati del tutto. Per importare comunque "tutto il resto", aggiungi un secondo Gruppo, a priorità più bassa, con una regola che intercetta genericamente le righe rimanenti.

Categorie

L'albero categorie viene creato automaticamente dal percorso categoria di ciascun prodotto nel feed — non serve pre-creare le categorie in Magento. L'impostazione "Categoria padre" permette di annidare l'intero albero categorie di un profilo sotto una radice condivisa, utile quando più profili condividono lo stesso catalogo e vuoi tenere i loro alberi categorie visivamente separati. Le categorie che restano vuote (es. dopo che un fornitore dismette un'intera linea prodotto) si ripuliscono con un click o da CLI.

Galleria immagini

Mappa un numero qualsiasi di colonne del feed verso i ruoli immagine (base / small / thumbnail / gallery) — una singola colonna può servire più ruoli contemporaneamente. Le immagini scaricate vengono opzionalmente compresse (ridimensionate se più larghe di 1200px, ricompresse in JPEG qualità 85, mantenute solo se il risultato è effettivamente più leggero) con concorrenza configurabile e un watchdog per lo spazio disco che sospende i download — mai i dati prodotto — se lo spazio libero scarseggia.

Prodotti configurable (varianti)

Le righe del feed che condividono lo stesso valore in una "colonna gruppo/padre" diventano varianti di un unico prodotto configurable. Un numero qualsiasi di attributi può variare contemporaneamente — misura, colore e un terzo attributo insieme, ad esempio — a ciascuno basta la propria riga di mapping con una colonna che dà un valore diverso per ogni variante.

Esempio reale — una linea di prodotto "Curva a 90°" che varia per gradi (90°/45°), misura tubo (10/20/30/40) e materiale (rame/tdm): mappa tutte e tre le colonne feed sui rispettivi attributi Magento, seleziona tutti e tre in "Attributi variante", e il prodotto padre mostra tre menu a tendina indipendenti sulla sua pagina — verificato end-to-end con 16 combinazioni di varianti simultanee.

Nota: l'attributo variante deve già esistere in Magento come vero attributo Dropdown, con scope "Per sito" (non Globale — un attributo globale non può mai variare tra le varianti, un requisito nativo di Magento), e assegnato al set di attributi del prodotto. I prodotti Bundle non sono supportati.

Prodotti grouped

Concettualmente diverso dal configurable: nessun attributo variante, nessuna colonna gruppo — solo un collegamento diretto tra un "contenitore" padre e un numero qualsiasi di prodotti semplici che restano completamente indipendenti (prezzo, stock e pagina navigabile propri), utile quando un fornitore vende sia i singoli componenti separatamente sia un kit che li mostra insieme con un selettore di quantità per ciascuno.

Esempio — "Kit Trapano" composto da 3 articoli venduti anche singolarmente: sulle righe figlie (trapano, batteria, caricabatterie), mappa "Grouped: SKU padre" verso una colonna con valore "KIT-TRAPANO"; sulla riga che rappresenta il kit stesso, mappa "Grouped: SKU figli" (puramente descrittivo) per marcarla come contenitore. Risultato: una pagina "Kit Trapano" che elenca tutti e tre i componenti con i propri selettori di quantità, e ciascun componente ha comunque la propria pagina prodotto individuale.

Gestione dello stock

Gli aggiornamenti stock possono essere assoluti (sostituiscono il valore) o relativi (sommano/sottraggono rispetto alla quantità attuale) — utile per fornitori il cui feed riporta variazioni invece di totali. Backorder e "gestisci stock" seguono la configurazione del profilo, non un'unica impostazione globale.

Anteprima e file di output

Due modi per vedere cosa scriverebbe davvero un sync sul catalogo — solo i campi mappati, mai i filtri categoria/vendibilità/Gruppo (il campione è parziale di proposito):

Anteprima	Riflette i valori attuali del form, anche non salvati — cliccala mentre modifichi per vedere subito l'effetto, senza toccare il profilo.
Scarica file di output	Usa l'ultima configurazione salvata e produce un file JSON scaricabile.

Pianificazione e notifiche

Ogni profilo ha una propria pianificazione cron (da ogni 15 minuti a una volta al giorno, o un'espressione cron personalizzata) sia per il sync completo del catalogo sia per uno più leggero solo stock/prezzi. Le notifiche email (successo/attenzione/errore critico) si configurano per profilo, così fornitori diversi possono avere policy di alert diverse sullo stesso negozio.

Ciclo di vita del prodotto: niente sparisce a sorpresa

Un prodotto che scompare dal feed, o viene escluso da un filtro, viene sempre prima disabilitato — mai eliminato — e si riabilita da solo automaticamente se riappare in un sync successivo. L'eliminazione definitiva è un'impostazione separata, opzionale (disattivata di default): solo un prodotto rimasto disabilitato per più di un numero configurabile di giorni viene effettivamente eliminato, e solo allora.

Comandi CLI

Ogni azione è disponibile anche da riga di comando (utile per cron, o per un primo import molto grande via SSH): eseguire il sync di un profilo, esportare/importare la configurazione di un profilo, annullare tutto ciò che un profilo ha mai importato, ripulire categorie orfane e altro — ciascuno con un'anteprima dry-run di default dove distruttivo.