Getting Started

Mapping campi

Modello di mapping sorgente → destinazione, auto-suggest, validazione e trasformazioni.

Concetto di mapping

Un import in @pzeta/vue-importexport è strutturato in due lati:

Sorgente — le colonne del file caricato (CSV header, prima riga XLSX, chiavi JSON).
Destinazione — i campi noti dell'entità ERP target, descritti come CampoMetadato[] e ottenuti dall'endpoint GET /api/import/metadata/:risorsa/fields.

Il mapping è una collezione MappingColonna[]: una entry per ogni colonna sorgente, che indica a quale campoDestinazione la colonna deve essere associata (o stringa vuota se la colonna va ignorata).

`CampoMetadato`

interface CampoMetadato {
  nome: string
  etichetta: string
  tipo: 'string' | 'number' | 'date' | 'boolean' | 'select'
  obbligatorio: boolean
  lunghezzaMax?: number
  opzioni?: Array<{ valore: string; etichetta: string }>
  pattern?: string
  descrizione?: string
  gruppo?: string
}

Campo	Descrizione
`nome`	Identificatore tecnico del campo destinazione (es. `codicefiscale`)
`etichetta`	Label visualizzata nei `Select` di mapping
`tipo`	Tipo dato — guida la validazione lato server e l'eventuale transform
`obbligatorio`	Se `true`, deve essere mappato per poter procedere
`lunghezzaMax`	Limite caratteri (validato server-side)
`opzioni`	Valori ammessi per `tipo === 'select'` (mostrati come "Valori possibili" nella colonna Commenti)
`pattern`	Regex di validazione
`descrizione`	Mostrata nella colonna Commenti del `FieldMapper`
`gruppo`	Raggruppamento UI (usato dal `PickList` di export)

`MappingColonna`

interface MappingColonna {
  colonnaSorgente: string
  indiceSorgente: number
  campoDestinazione: string
  trasformazione?: string
  valoreDefault?: string
}

Campo	Descrizione
`colonnaSorgente`	Nome della colonna nel file (header)
`indiceSorgente`	Indice 0-based della colonna nel file
`campoDestinazione`	`nome` del `CampoMetadato` mappato — `''` significa "non mappare"
`trasformazione`	Espressione di trasformazione opzionale (es. `uppercase`, `trim`, formato data)
`valoreDefault`	Valore da usare se la cella sorgente è vuota

Solo le mapping con campoDestinazione !== '' vengono inviate alle chiamate testImport ed executeImport (filtro applicato da useFieldMapping.getActiveMappings()).

Esempio di array mapping

const mappings: MappingColonna[] = [
  { colonnaSorgente: 'Nome', indiceSorgente: 0, campoDestinazione: 'nome' },
  { colonnaSorgente: 'Cognome', indiceSorgente: 1, campoDestinazione: 'cognome' },
  { colonnaSorgente: 'Email', indiceSorgente: 2, campoDestinazione: 'email' },
  { colonnaSorgente: 'CF', indiceSorgente: 3, campoDestinazione: 'codicefiscale', trasformazione: 'uppercase' },
  { colonnaSorgente: 'Note', indiceSorgente: 4, campoDestinazione: '' }, // ignorata
]

Auto-suggest

useFieldMapping.autoSuggest() propone automaticamente un mapping al primo upload normalizzando entrambi i lati e cercando match esatti:

const sourceLower = colonnaSorgente.toLowerCase().replace(/[\s_-]/g, '')
const targetLower = campo.nome.toLowerCase().replace(/[\s_-]/g, '')
const labelLower  = campo.etichetta.toLowerCase().replace(/[\s_-]/g, '')
// match se sourceLower === targetLower || sourceLower === labelLower

Quindi Codice Fiscale, codice_fiscale, codicefiscale vengono tutti riconosciuti come codicefiscale. L'auto-match viene eseguito una volta sola al initFromColumns — i campi già mappati manualmente non vengono toccati.

Validazione mapping

useFieldMapping espone due reactive properties per la validazione:

Property	Tipo	Significato
`campiObbligatoriMancanti`	`ComputedRef<CampoMetadato[]>`	Lista campi `obbligatorio: true` non ancora mappati
`isValid`	`ComputedRef<boolean>`	`true` se nessun campo obbligatorio è mancante

Il pulsante "Avanti" del wizard (ImportWizard step 1) è disabilitato finché isValid === false. Nel frattempo, in cima al FieldMapper viene mostrato un Message severity="warn" con la lista dei campi mancanti.

Trasformazioni

Le trasformazioni sono stringhe libere il cui significato è interpretato dal microservizio import. Convenzioni tipiche:

`trasformazione`	Effetto
`uppercase`	Converte a maiuscolo
`lowercase`	Converte a minuscolo
`trim`	Rimuove spazi iniziali/finali
`date:dd/MM/yyyy`	Parsing data dal formato indicato
`number:.,`	Parsing numerico con `.` come migliaia e `,` come decimale

Sono impostabili tramite fieldMapping.updateTransform(index, trasformazione).

Valore di default

Per gestire celle vuote o assenti, valoreDefault viene usato dal microservizio quando la cella sorgente è null/undefined/''. Tipico use-case: un flag booleano che, se non valorizzato dal CSV, deve essere false.

fieldMapping.updateDefault(idx, 'false')

Installazione

Installazione, peer dependencies e setup base di @pzeta/vue-importexport.

ImportWizard

Wizard multi-step per l'importazione massiva di dati CSV/Excel/JSON.