Documentazione tecnica

Che cosa documenta questa pagina

Il tracciato CSV base è un perimetro ristretto e deliberato. Serve a verificare una cosa sola su punti reali: che una sequenza ricalcolata risulti più corta di quella caricata, e che il confronto sia leggibile riga per riga.

Due distinzioni vanno tenute ferme per tutta la pagina. Il catalogo delle 34 famiglie descrive il perimetro tecnico generale del motore e non costituisce lo schema del CSV base — il catalogo è descritto in Vincoli. E soprattutto: le capacità del catalogo tecnico generale non vengono attivate automaticamente dal caricamento di un CSV.

Il file non viene richiesto in autonomia dal sito: viene richiesto successivamente, dentro il perimetro concordato, dopo la qualificazione.

Formato CSV

Nel percorso CSV base verificato l'ingresso è esclusivamente un file CSV tabellare con intestazioni riconoscibili. Non esiste un percorso di creazione analisi da payload JSON, e XLSX, XLS e PDF non sono formati di ingresso. Le coordinate sono la forma più affidabile: gli indirizzi seguono un ramo separato, descritto più sotto.

name,lat,lon,stop_type
Deposito,42.5636,12.6427,depot_start
Cliente 1,42.5700,12.6500,customer
Cliente 2,42.5600,12.6300,customer
Deposito,42.5636,12.6427,depot_end

Quattro fermate, deposito iniziale e finale dichiarati, coordinate dei due depositi identiche. Il ruolo è portato da stop_type, non dal nome.

Tre dettagli strutturali che evitano il rifiuto del file: il separatore è la virgola (il punto e virgola non è previsto in questo percorso); serve una riga di intestazione con almeno tre colonne, senza intestazioni duplicate; tutte le righe devono avere lo stesso numero di colonne dell'intestazione. I valori tra virgolette seguono le convenzioni CSV usuali, e le virgolette non bilanciate provocano il rifiuto dell'input.

Colonne del tracciato base

Queste sono le colonne che partecipano alla costruzione della topologia nel percorso CSV base verificato.

Colonne del tracciato CSV base

Colonna	Obbligatoria	Formato	Funzione effettiva	Condizione di rifiuto
name	sì	testo, max 120 caratteri	Identifica la fermata nel confronto	Assente o oltre la lunghezza massima
lat	sì sul ramo a coordinate	numero decimale, punto o virgola	Geometria della fermata	Assente o fuori intervallo
lon	sì sul ramo a coordinate	numero decimale, punto o virgola	Geometria della fermata	Assente o fuori intervallo
stop_type	sì per le due righe di deposito	depot_start · depot_end	Dichiara il ruolo di deposito iniziale e finale	Deposito non dichiarato, o deposito in posizione intermedia
stop_id	no	testo	Identità della fermata nel giro	Identificativi duplicati
indirizzo, civico, comune, cap, provincia	alternative alle coordinate	testo	Ramo a indirizzi, con i limiti descritti in Da indirizzi	Riga non risolta: resta segnalata

Le intestazioni sono riconosciute anche in italiano: cliente, nome, latitudine, longitudine e varianti equivalenti.

Campi avanzati: rifiutati, non ignorati

Il percorso CSV base non applica automaticamente i vincoli avanzati del catalogo. La presenza di campi che esprimono finestre temporali, domanda o capacità, tempi di servizio, costi, durata massima, coppie ritiro-consegna, consegne frazionate, backhaul, turni, pause, priorità o altre famiglie non supportate provoca il rifiuto dell'input prima del calcolo: tali dati non vengono ignorati e non vengono usati per produrre un risultato parziale.

I dati inviati al calcolo dal percorso base contengono soltanto identità e posizione della fermata nella matrice delle distanze. Non esiste una modalità intermedia in cui un campo avanzato entra a metà.

Questo limite appartiene al percorso CSV base e non riduce il catalogo tecnico generale del motore. I requisiti avanzati devono essere qualificati e configurati separatamente nel perimetro del pilota. Il catalogo è descritto qui: le 34 famiglie canoniche →

Deposito e struttura del giro

Nel percorso CSV base il giro deve contenere almeno tre fermate ed essere rappresentato come giro chiuso con un solo deposito. La prima riga deve essere dichiarata come deposito iniziale e l'ultima come deposito finale; le due righe devono riportare le stesse coordinate.

Il contratto pubblico è quello dell'esempio: stop_type=depot_start sulla prima riga, stop_type=depot_end sull'ultima.

Un giro aperto, depositi intermedi, depositi multipli o un deposito non dichiarato causano il rifiuto dell'input. Non esiste un ripiego che accetta il file e calcola comunque.

Il nome della fermata non viene usato per dedurre il ruolo di deposito. Chiamare una riga «Deposito finale» o «Rientro deposito» non sostituisce la dichiarazione in stop_type.

Da indirizzi

Nel ramo basato su indirizzi il tentativo di risoluzione può utilizzare una cache locale. L'interrogazione di un provider online richiede un'abilitazione esplicita. Le righe non risolte restano segnalate per revisione e non vengono trasformate in un punto approssimativo.

Questa funzione non costituisce un servizio pubblico generale di geocodifica e non certifica il punto di consegna, il numero civico o l'accessibilità reale. Se lavori su punti nuovi, le coordinate restano la strada affidabile.

cliente,indirizzo,civico,comune,cap,provincia
Cliente Roma,Via Roma,12,Roma,00100,RM

Output e consegna

Il percorso CSV base crea un record interno nell'ambiente locale o controllato. Report standard, viste applicative, export tecnici e record interni sono superfici differenti. Il repository corrente non consente di documentare come operativo un flusso pubblico end-to-end di esportazione.

Gli eventuali formati e campi di consegna vengono definiti nel perimetro concordato del pilota; questa pagina non garantisce che uno stesso campo sia presente in ogni superficie.

Nel merito, il confronto è sempre fra due sequenze sugli stessi punti: quella caricata e quella ricalcolata. Nel report concordato possono comparire, come categorie possibili e non come campi garantiti dal percorso base: distinzione fra baseline e scenario; ordini sottoposti, serviti, non serviti, esclusi o non fattibili; metriche del provider di distanze; warning; assunzioni; limiti.

Provider richiesto, provider effettivo, ripiego, configurazione e vincoli compaiono soltanto nelle superfici e nei campi che li prevedono. Su che cosa esiste e che cosa no lato integrazioni, vedi Integrazioni.

Esiti ed errori

Il percorso CSV base rifiuta l'input prima del calcolo quando la struttura, la topologia o i campi dichiarano elementi non supportati. Un input rifiutato non viene presentato come risultato valido.

Il rifiuto dell'input deve restare distinto da altri esiti che appartengono a superfici e momenti diversi: warning, dati insufficienti, ordini non serviti, soluzione parziale ammessa, istanza non fattibile. Un file rifiutato dal tracciato non significa che il problema operativo sia infattibile: significa che quel file non è rappresentabile nel percorso base.

Sul ramo a indirizzi il comportamento è diverso: le righe che non trovano corrispondenza restano segnalate per revisione.

Una distinzione che conviene tenere ferma. Quelli descritti qui sono stati di esecuzione del calcolo — com'è andata la singola elaborazione: input rifiutato, warning, ordini non serviti, soluzione parziale, istanza non fattibile, dati insufficienti. Non sono le quattro categorie con cui viene presentato l'esito del pilota (miglioramento tecnico misurato, nessun miglioramento significativo, scenario non fattibile, dati insufficienti), descritte in Come funziona. Un'esecuzione può produrre warning e restare pienamente utilizzabile nel confronto.

I codici interni non sono pubblicati in questa pagina: non esiste un'interfaccia programmatica pubblica di cui possano costituire il contratto.

Limiti dichiarati

Senza attenuazioni.

• Campi avanzati non supportati dal tracciato base. Finestre temporali, domanda o capacità e tempi di servizio non sono supportati dal percorso CSV base: la loro presenza provoca il rifiuto dell'input. vehicle_id non abilita una flotta; più veicoli distinti provocano il rifiuto.
• Nessuna applicazione automatica delle 34 famiglie. Il caricamento di un CSV non attiva il catalogo del motore.
• Ricerca euristica, nessun ottimo globale. Nessun minimo assoluto dichiarato, nessun miglioramento garantito, nessun risparmio economico garantito.
• Percorrenza calcolata ≠ percorrenza osservata. Il routing calcolato resta distinto da ciò che accade su strada.
• Geocoding non certificante. Nessuna precisione garantita al numero civico, nessuna copertura garantita, nessuna certificazione del punto di consegna o dell'accessibilità.
• Esiti possibili oltre al risultato. Warning, dati insufficienti e non fattibilità sono esiti previsti.
• Nessuna interfaccia di produzione. Niente API pubblica versionata, webhook, connettori gestionali, telemetria in tempo reale o traffico live.

Questi limiti descrivono esclusivamente il tracciato CSV base. Non costituiscono una negazione delle capacità tecniche presenti nel catalogo generale del motore.

Per come vengono prodotti e verificati i numeri, vedi Il metodo. Per il perimetro di ciò che non viene promesso, vedi Cosa non è.