Lane: relazione tecnica

00 Oggetto, destinatari, metodo

È scritto per chi deve giudicare la solidità tecnica di un sistema, non per chi deve usarlo: l'uso è descritto nei manuali operativi del servizio. Qui si risponde a domande diverse: su cosa poggia, chi possiede i dati, cosa succede quando qualcosa si rompe, quanto regge, come si esce.

Il documento non contiene la parte economica, che è oggetto separato, né impegni contrattuali o livelli di servizio: quelli si definiscono, se c'è interesse, in un secondo momento e sui parametri dell'ente. Contiene invece, al capitolo 14, i limiti noti del sistema. Sono dichiarati di proposito: un sistema in esercizio da poche settimane che non avesse limiti sarebbe un sistema descritto male.

L'appendice A entra nel dettaglio del motore del bus a chiamata: formulazione del problema, funzione di costo, decisioni architetturali con le alternative scartate, misure con le procedure per riprodurle.

Tutti i numeri riportati sono misurati sul codice e sulla configurazione in esercizio alla data del documento, non stimati. Le misure dell'appendice riportano ciascuna la propria data.

Indice

01 Perimetro funzionale

Lane è una piattaforma unica che gestisce più servizi di mobilità sullo stesso impianto: stessa anagrafica, stesso motore di autorizzazioni, stessa contabilità, stesse app. I servizi non sono prodotti separati messi vicini, sono configurazioni dello stesso sistema. Questo ha una conseguenza pratica per l'ente: il bus a chiamata non è un prototipo isolato, è un servizio dentro un impianto che già porta traffico reale su altri fronti.

Servizi attivi

Chi usa il sistema

Il cittadino

Dall'app sul telefono, oppure telefonando alla centrale, che prenota per lui.

Il conducente

Dall'app sul telefono: turno, incarichi, salite e discese, chiusura.

La centrale dell'azienda

Dalla consolle operatore, da computer: mappa in tempo reale, richieste, prenotazioni telefoniche, regole del servizio, numeri, esportazioni.

Lane

Dal pannello di amministrazione: configurazione della piattaforma, aree di servizio, listini, anagrafiche, contabilità fra le parti.

I quattro ruoli hanno interfacce separate e permessi separati. Un operatore vede e governa solo i propri mezzi, i propri conducenti, le proprie corse e i propri numeri: non ha visibilità su quelli di altri operatori. L'isolamento è imposto dal server a ogni richiesta, non dalla schermata.

02 Architettura del sistema

Vista d'insieme

Componenti e versioni

Dimensione del sistema

Non è una misura di qualità, ma di ordine di grandezza: serve a capire di che cosa si parla quando si dice "piattaforma".

Due scelte di fondo, e perché

Il server decide, l'app obbedisce

Nessuna regola vive dentro l'app. Il passaggio di stato di una corsa è validato da una macchina a stati sul server, che conosce quali transizioni sono lecite per ogni tipo di servizio: una corsa non può passare a "passeggero sceso" se non risulta salito, un conducente non può dichiarare un'assenza del cliente se il server non vede che era sul posto e ha atteso i minuti previsti. Questo rende il sistema robusto agli errori delle app e alle manomissioni, e permette di correggere una regola aggiornando il server, senza aspettare che tutti abbiano aggiornato il telefono.

Un motore sostituibile

L'algoritmo che abbina passeggeri e mezzi è isolato dietro un contratto interno. Oggi è una euristica di inserimento; domani può diventare un algoritmo diverso, più sofisticato, senza toccare il resto del sistema. La stessa disciplina vale per il motore stradale e per il gateway di pagamento. Non è un dettaglio estetico: è ciò che rende la piattaforma aggiornabile senza riscritture.

03 Le tre interfacce

Consolle operatore, da computer

È il posto di lavoro della centrale. Non è una vista in sola lettura: da qui si governa il servizio.

• Dispatch. Mappa dei mezzi in tempo reale, richieste in arrivo, coda, stato di ogni passeggero. Permette di prenotare per chi telefona, forzare un'assegnazione, segnare una salita o una discesa al posto del conducente, mettere in pausa un mezzo, riassegnare un mezzo in emergenza creando il turno da remoto.
• Leve. Le regole del motore, modificabili dalla centrale: attesa massima, deviazione massima, durata massima a bordo, sosta alla fermata, anticipo di prenotazione. Ogni leva ha un valore globale e un valore proprio dell'operatore.
• Fermate, mezzi, orari, turni. Anagrafiche del servizio e calendario di apertura.
• Numeri. Cruscotto delle prestazioni con confronto fra periodi, pagina di ribilanciamento e uno strumento di simulazione che risponde alla domanda "cosa succede se aggiungo un mezzo, o se stringo l'attesa massima".
• Dati. Esportazione delle corse e delle ore di servizio in formato aperto, e rapporto mensile in PDF.

App del cittadino

Disponibile per iOS e Android. Accesso con numero di telefono verificato o con account Google; non richiede la creazione di una password. Mostra solo i servizi effettivamente disponibili nel punto in cui si trova l'utente, secondo le aree di servizio configurate. Per il bus a chiamata: ricerca della fermata più vicina con distanza e minuti a piedi, prenotazione immediata o anticipata, seguito del mezzo in avvicinamento, avvisi di cambio orario. Sei lingue.

App del conducente

Disponibile per iOS e Android, in lingua italiana. Gestisce il turno, riceve gli incarichi, guida il conducente passo per passo nelle salite e nelle discese, conferma le salite con un codice, invia la posizione al sistema. Il conducente aziendale non modifica il proprio profilo: le credenziali le imposta la centrale, e questo evita che un'azienda perda il controllo dei propri accessi.

04 Il motore del bus a chiamata

È la parte del sistema che decide, ogni volta che qualcuno prenota, quale mezzo lo prende, in che ordine e insieme a chi. È anche la parte più delicata: un servizio di questo tipo si giudica sul tempo di attesa e sulla lunghezza del viaggio, e sono entrambi conseguenze di questa decisione.

Il problema

Un taxi è semplice: un'auto, un cliente, da A a B. Un bus a chiamata condiviso è un problema diverso, noto in letteratura come dial-a-ride: più passeggeri sullo stesso mezzo, ognuno con origine e destinazione proprie, vincoli di attesa e di durata da rispettare per ciascuno, e la necessità di rispondere in tempo reale. È un problema di ottimizzazione combinatoria che non si risolve in forma esatta nei tempi di una richiesta web: si risolve bene con euristiche.

Come decide, passo per passo

1. Raccoglie i candidati Prende i mezzi dello stesso operatore, in turno, con i piani di viaggio già assegnati.
2. Prova ogni inserimento possibile Per ogni mezzo, prova a infilare la salita e la discesa del nuovo passeggero in ogni posizione del percorso già previsto. Non ne prova alcune: le prova tutte.
3. Scarta ciò che viola i vincoli Capienza del mezzo compresi i posti per carrozzina, attesa massima del nuovo passeggero, attesa e durata di viaggio già promesse a chi è già a bordo o già assegnato, allungamento massimo del percorso.
4. Sceglie il costo minimo Fra le combinazioni valide sceglie quella che aggiunge meno tempo complessivo. Meno tempo aggiunto significa meno chilometri, meno consumo e più capacità residua per le richieste successive.
5. Se non entra da nessuna parte, apre un giro nuovo Manda un mezzo libero. Se non ci sono mezzi liberi, la richiesta resta in coda e viene ripresa al primo giro di ri-ottimizzazione utile.

Le leve: il compromesso è una scelta politica, non tecnica

Il motore non stabilisce da sé che cosa sia accettabile. I vincoli sono parametri, visibili e modificabili dalla centrale, con effetto immediato sulle decisioni successive.

Il senso di questa architettura è che il compromesso fra comodità per il cittadino e costo per l'ente diventa esplicito e misurabile. Stringere le leve migliora il servizio percepito e richiede più mezzi; allargarle riduce il costo e peggiora l'esperienza. Con lo strumento di simulazione la centrale vede l'effetto prima di applicarlo, sulla domanda reale già registrata.

Il servizio si corregge da solo, ogni minuto

Due dettagli che dicono come è scritto il sistema

La pulizia notturna non cancella niente. Chiude gli stati e scrive un evento con il motivo. Lo storico resta integro e le statistiche restano oneste: se una richiesta è scaduta, nei numeri del mese risulta scaduta, non sparisce. Non tocca mai un passeggero risultante a bordo, né una prenotazione futura, né uno stato già definitivo. Eseguita due volte di fila non cambia nulla.

La calibrazione degli orari è volutamente prudente. Interviene solo con un campione minimo, e il fattore correttivo è limitato entro una banda stretta. Un algoritmo che si auto-corregge senza freni, su pochi dati, è un algoritmo che a un certo punto promette orari assurdi.

05 Il motore stradale

Per decidere bene servono i minuti veri su strada vera. A San Marino questo pesa più che altrove: su un territorio in pendenza due fermate vicine in linea d'aria possono essere lontane in auto, per via di tornanti, sensi unici e dislivelli. Una stima puramente geometrica, qui, sbaglia in modo sistematico.

Installato in casa, non a consumo

Il motore stradale è GraphHopper, software libero, installato sul nostro server come servizio di sistema. Non è un servizio esterno a pagamento per chiamata. Tre conseguenze concrete:

• Il costo delle interrogazioni è zero, quindi il motore può permettersi di farne quante ne servono.
• Nessun indirizzo, nessuna coordinata e nessun percorso dei cittadini esce dal nostro server per essere calcolato.
• Non esiste un fornitore che possa cambiare condizioni, limitare le chiamate o dismettere il servizio.

Tarato sul minibus e sul territorio

Il profilo di percorrenza di serie di un motore stradale presume un'auto alla velocità consentita su ogni strada: sulle strade collinari sammarinesi dà tempi troppo brevi. Il profilo in uso è tarato per il minibus su 120 coppie di fermate confrontate con i tempi di Google Maps. Sulle 101 coppie in cui i due sistemi percorrono le stesse strade lo scarto medio per coppia è sceso dal 20,6% al 10,1%, e la somma dei tempi coincide. Nelle altre 19 i due sistemi scelgono strade diverse e il confronto non è significativo.

La tabella dei tempi fra le fermate

Le fermate sono un insieme finito e stabile. Perciò i tempi fra ogni coppia di fermate sono calcolati una volta sola e conservati: 239.610 tratte, corrispondenti alle circa 490 fermate caricate. Il motore, mentre decide, non interroga mai la rete: legge una tabella. È la ragione per cui il dispatch risponde in tempi da interfaccia e non da elaborazione.

Cosa succede se il motore stradale si ferma

Il servizio non si ferma. Nell'ordine:

1. La tabella dei tempi resta valida e continua a servire tutte le coppie di fermate già calcolate, che a regime sono tutte.
2. Per una coppia non ancora in tabella si usa una stima geometrica tarata sui tempi reali del motore stradale: velocità e allungamento medi diversi per fascia di distanza, perché sulle tratte brevi contano tornanti e ripartenze e su quelle lunghe si viaggia. La stima è accurata, non prudente, e in una parte dei casi sottostima: è documentato nel codice.
3. Il servizio di sistema riparte da solo in caso di caduta, e la sentinella lascia traccia nel registro.

Questa è una scelta di progetto ricorrente nel sistema e vale la pena esplicitarla: degradare, non fermarsi. Quando una dipendenza esterna viene meno, il sistema perde qualità, non funzione.

06 Dati: cosa, dove, di chi

Per un ente pubblico questa è la sezione che conta più di tutte. La risposta breve: i dati del servizio sono dell'ente, stanno in Unione Europea, sono esportabili in formato aperto in qualsiasi momento senza chiedere nulla a noi.

Dove sta cosa

La separazione è voluta e va letta così: in Firebase non c'è anagrafica. Ci sono dati volatili di posizione e di stato. I dati personali stanno nella base dati, dietro autenticazione, sul nostro server.

Il dato di esercizio è dell'ente

Nella consolle, senza passare da noi e senza richiesta formale, l'operatore esporta:

• l'elenco completo delle richieste del servizio, in CSV, con gli stessi filtri della pagina;
• le ore di servizio dei mezzi, in CSV, mese per mese;
• un rapporto mensile in PDF, pronto da protocollare;
• l'elenco delle corse dell'azienda, in CSV.

Sono formati aperti, leggibili da qualunque foglio di calcolo o sistema informativo. Non c'è alcun passaggio che richieda la nostra collaborazione. Il capitolo 15 spiega cosa succede in caso di interruzione del rapporto.

Conservazione

Lo storico di esercizio non ha oggi una cancellazione automatica: le corse restano. Le cancellazioni automatiche previste riguardano dati accessori e sono selettive: le registrazioni di conducenti rimaste incomplete oltre sette giorni vengono rimosse insieme ai loro documenti; i gettoni di accesso scaduti vengono eliminati ogni cinque minuti; i registri tecnici vengono ruotati.

Trasferimenti fuori dall'Unione Europea

La base dati, i documenti caricati e il motore stradale risiedono su un server dedicato in Germania. I servizi accessori di Google, ossia il tempo reale e le mappe, e il servizio di notifiche push sono fornitori con infrastruttura anche extraeuropea: attraverso di loro transitano posizioni dei mezzi, identificativi tecnici dei dispositivi e testo delle notifiche, non l'anagrafica. La collocazione esatta di questi servizi va dichiarata nel registro dei trattamenti dell'ente: siamo in grado di fornire il dettaglio, ed è un adempimento da fare, non una formalità da rimandare.

07 Sicurezza

Accesso

Cittadino

Numero di telefono verificato dal fornitore di identità, oppure account Google. Nessuna password da ricordare, nessuna password da rubare.

Conducente

Numero e password aziendale, impostata dalla centrale. Il conducente non modifica il proprio profilo.

Centrale operatore

Credenziali proprie, sessione protetta, ogni richiesta verificata da un controllo che impone l'isolamento fra operatori.

Pannello Lane

Credenziali proprie, con ruoli e permessi granulari verificati sul server a ogni azione.

Le app comunicano con il server tramite gettoni personali a scadenza, non con credenziali memorizzate. I gettoni scaduti vengono eliminati automaticamente.

La parte in tempo reale

È il punto che merita più attenzione, perché è quello che in molti sistemi resta aperto. Le regole di accesso ai dati in tempo reale sono state chiuse e verificate in esercizio. In sintesi:

• accedono, in lettura e in scrittura, solo utenti autenticati: nessun accesso anonimo dalla rete è consentito;
• non è possibile elencare le corse: si accede solo a una corsa specifica conoscendone l'identificativo, che è casuale e non indovinabile. Questo chiude la possibilità di raccogliere in blocco i contatti dei clienti;
• la cancellazione dai client è vietata: non è possibile svuotare dati dall'esterno;
• le posizioni dei mezzi accettano solo dati formalmente validi;
• il backend opera con credenziali amministrative proprie e non passa da queste regole, quindi irrigidire i client non degrada il funzionamento del sistema.

Le regole sono versionate nel codice sorgente insieme al resto: sono ricostruibili e ispezionabili, non una configurazione lasciata in una console.

Server e trasporto

• Traffico esclusivamente su HTTPS, certificato a rinnovo automatico.
• Accesso al server solo con chiave crittografica; autenticazione con password disabilitata.
• Filtro di rete attivo, con apertura limitata ai soli servizi pubblici necessari; il motore stradale e la base dati non sono raggiungibili dall'esterno.
• Protezione automatica contro i tentativi ripetuti di accesso.
• Segreti e chiavi non presenti nel codice sorgente: vivono solo sul server e nei gestori di credenziali.

Una scelta meno ovvia: nessuna dipendenza esterna nelle pagine

Il pannello e la consolle non caricano alcuna libreria da fornitori esterni: tutto il materiale necessario è servito dal nostro server. La decisione è nata da un problema di prestazioni, ma l'effetto più importante è un altro: la centrale non dipende dalla disponibilità di fornitori terzi per aprire una pagina, e nessun fornitore esterno osserva chi apre quale schermata. Le sole eccezioni sono le mappe e gli strumenti di pagamento, che per loro natura sono servizi remoti.

08 Continuità del servizio

Cosa è automatico oggi

Comportamento in caso di guasto

La centrale ha sempre una via manuale

È un principio di progetto, non un ripiego. In ogni punto in cui il sistema decide da solo, la centrale può intervenire a mano: prenotare per chi telefona, assegnare d'autorità una richiesta a un mezzo, segnare una salita o una discesa al posto del conducente, mettere in pausa un mezzo, riassegnare un mezzo in emergenza creando il turno da remoto, annullare una richiesta con un motivo tracciato. Un servizio pubblico non può dipendere dal fatto che l'automatismo abbia sempre ragione.

09 Capacità e prestazioni

Come è costruita la velocità

La reattività del dispatch non è un effetto della potenza del server, ma di due scelte precise. La prima: durante una decisione il motore non interroga mai la rete, legge la tabella dei tempi. La seconda: configurazioni, rotte e pagine sono precompilate, quindi il costo fisso di ogni richiesta è quasi azzerato.

Il costo del ciclo di ri-ottimizzazione è tenuto piatto anche in condizioni di saturazione prolungata: quando la coda non riesce a essere smaltita, il ciclo si ferma dopo un numero fisso di tentativi consecutivi senza esito, invece di riprovare all'infinito. È una protezione introdotta dopo aver misurato un caso reale di domanda doppia, non una precauzione teorica.

Dimensionamento

Il sistema è dimensionato per il territorio sammarinese. Una simulazione di capacità condotta sul motore vero ha indicato, con quattro mezzi e le leve impostate sui valori di allora, un tetto dell'ordine di alcune centinaia di corse al giorno. Il numero dipende interamente da quanti mezzi sono in turno e da come sono regolate le leve: è esattamente la domanda a cui risponde lo strumento di simulazione della consolle, che lavora sulla domanda reale già registrata e non su ipotesi.

10 Verifica e non-regressione

La domanda giusta non è "avete testato", è "come fate a sapere che una modifica di oggi non rompe il servizio di domani".

L'autodiagnosi del motore

Esiste un comando che fa girare il motore vero su scenari deterministici, dentro una transazione che viene annullata alla fine: nessun residuo nella base dati, nessuna notifica inviata. Controlla tre cose:

1. Non-regressione Ogni assegnazione, ordine delle tappe e orario promesso deve restare identico a un riferimento registrato. Qualunque modifica che cambi il comportamento su scenari normali viene individuata prima di arrivare in esercizio.
2. Invarianti fisici La capienza non può essere superata, la salita deve precedere la discesa, un orario promesso non può essere nel passato. Valgono sempre, anche in assenza di riferimento.
3. Coerenza fra motore e simulatore La stessa domanda posta al motore e allo strumento di simulazione deve dare gli stessi numeri. Impedisce che la pagina mostrata alla centrale e il comportamento reale divergano nel tempo.

Collaudi end-to-end

Le funzioni sono verificate con collaudi completi sul sistema in esercizio, condotti con elenchi di controllo scritti prima e con esito registrato punto per punto: ciclo di vita della corsa taxi, ciclo del giro commissioni con il relativo conto, impianto amministrativo. Sono collaudi su ambiente reale, non su simulazioni.

11 Trasparenza e controllo dell'ente

Un servizio pubblico deve poter essere controllato da chi lo paga e osservato da chi lo usa. Sono due esigenze diverse e il sistema le tiene separate.

Verso il cittadino

Esiste una pagina pubblica di trasparenza del servizio, raggiungibile senza alcun accesso, che espone l'andamento reale. Non è una vetrina: è il riconoscimento che, per un servizio pagato con risorse pubbliche, i numeri sono di chi lo finanzia.

Verso l'ente

• Cruscotto delle prestazioni con confronto fra periodi e segnalazioni quando un indicatore si allontana dai valori attesi.
• Registro delle ore di servizio per mezzo e per mese, calcolato dai turni effettivi e non dichiarato: è il dato che l'ente vede prima di qualunque conteggio economico.
• Storia completa di ogni richiesta: ogni cambio di stato lascia un evento datato con il motivo. Un reclamo si ricostruisce, non si interpreta.
• Esportazioni in formato aperto e rapporto mensile in PDF, come al capitolo 06.

Una scelta sul linguaggio

Nelle schermate destinate alla centrale e ai cittadini non compaiono sigle tecniche, e i cruscotti numerici sono accompagnati da una spiegazione in lingua corrente. Al cittadino, inoltre, non viene mai comunicato un tempo di attesa calcolato al minuto, ma una fascia. Un orario preciso che poi slitta produce più danno di una fascia onesta rispettata: è una regola di prodotto che abbiamo scelto e che manteniamo anche quando il dato preciso sarebbe disponibile.

12 Integrazioni

La piattaforma espone già oggi una interfaccia applicativa strutturata, quella che usano le due app: 151 punti di accesso autenticati e versionati. La stessa interfaccia è la base naturale per un collegamento con i sistemi dell'ente.

Le tre voci non presenti sono indicate come tali di proposito. Sono lavori possibili, non funzioni esistenti, e vanno valutate per quello che sono.

13 Manutenzione ed evoluzione

Chi ci mette le mani

Lo sviluppo e la manutenzione sono di Titano Dev Studio. Il codice è interamente versionato in un repository con la storia completa delle modifiche: ogni intervento è tracciato, datato e reversibile. La configurazione dei server e le procedure di rilascio sono documentate nel repository stesso.

Come si rilascia

I rilasci sono incrementali e non richiedono la sospensione del servizio. La sequenza è fissa: aggiornamento del codice, applicazione delle evoluzioni della base dati, rigenerazione delle cache, riavvio dei processi in coda. Le evoluzioni della base dati sono descritte in file versionati e applicate in ordine: lo stato della base dati è ricostruibile da zero.

Aggiornamento delle app

Le app si aggiornano attraverso i negozi. Il sistema è progettato perché questo non sia un vincolo operativo: poiché le regole vivono sul server, una modifica di regola ha effetto immediato su tutti, anche su chi non ha ancora aggiornato. Le app si aggiornano quando cambia quello che si vede o si tocca, non quando cambia una regola.

Pagamenti

Il servizio di bus a chiamata, nella configurazione attuale, non movimenta denaro. La piattaforma, per gli altri servizi, ha invece un impianto di pagamento digitale completo, costruito con un principio: esiste un punto unico del sistema in cui nasce un pagamento, qualunque sia il modo in cui la carta viene raccolta. Il pagamento in viaggio è un blocco dell'importo, non un addebito: se la corsa si annulla il blocco si scioglie e non c'è alcun rimborso da gestire. I rimborsi, quando servono, avvengono sempre in forma di credito riutilizzabile.

L'attivazione commerciale dei pagamenti dipende da una decisione societaria e normativa ancora aperta, indipendente da questa valutazione. Lo scriviamo perché fa parte dello stato reale del sistema.

14 Limiti noti e punti aperti

Questo capitolo elenca ciò che oggi non c'è o non regge. È la parte del documento che consigliamo di leggere per prima, e ogni voce ha accanto quello che serve per chiuderla.

Infrastruttura su nodo singolo

Tutto gira su un server dedicato. Non c'è ridondanza: un guasto grave della macchina ferma il servizio fino al ripristino, e il ripristino richiede la ricostruzione del server e il riversamento delle copie. È il limite più rilevante del sistema allo stato attuale. Un esercizio con obblighi di continuità richiede un secondo nodo e un tempo di ripristino concordato: è un intervento infrastrutturale noto e dimensionabile, e va messo sul tavolo insieme ai livelli di servizio.

Copie di sicurezza sulla stessa macchina

Le copie automatiche della base dati e dei documenti risiedono sullo stesso server. Proteggono dall'errore umano e dal danno logico, non dalla perdita della macchina. La copia fuori sede è il primo intervento da fare e ha costo e complessità modesti: lo indichiamo come lavoro da pianificare, non come opzione.

Copertura di test automatici ridotta

Come descritto al capitolo 10: la rete di sicurezza copre il motore, non ogni funzione periferica.

Dipendenza da fornitori terzi

Il tempo reale e le notifiche poggiano su servizi di Google e su un fornitore di notifiche. Il sistema degrada in modo controllato se vengono meno, come descritto al capitolo 08, ma la dipendenza esiste e va dichiarata. Il motore stradale, che è la dipendenza più critica per il bus a chiamata, è invece installato in casa proprio per non averne una.

App non ancora pubbliche

Le due app sono distribuite tramite i canali di prova dei negozi. La pubblicazione aperta è una decisione di tempi.

Adempimenti sulla protezione dei dati da completare

Prima di un esercizio reale vanno formalizzati: titolarità e responsabilità del trattamento, finalità e base giuridica, tempi di conservazione dello storico, informativa ai cittadini, registro dei trattamenti con il dettaglio dei fornitori. Il sistema è in grado di applicare le regole che l'ente stabilisce; le regole, oggi, non sono state stabilite.

Fuori dal perimetro di questo documento

• Il modello economico del servizio, oggetto separato.
• I livelli di servizio e le penali, da definire con l'ente dopo la valutazione tecnica.
• Il carpooling fra privati, capacità presente ma disattivata e priva di un modello di sostenibilità.

15 Reversibilità e uscita

Un ente non deve firmare nulla che non sappia come disfare. Per questo la posizione è scritta qui, prima di qualunque trattativa.

1. I dati di esercizio sono dell'ente, e sono già nelle sue mani Richieste, ore di servizio, corse e rapporti si esportano in formato aperto dalla consolle, in qualsiasi momento, senza passare da noi. Non serve aspettare la fine di un rapporto per averne copia: si può fare ogni mese.
2. Il dato di configurazione è riproducibile Fermate, orari, mezzi, leve e turni sono dati strutturati esportabili e reimportabili in un altro sistema.
3. In caso di interruzione, consegna completa Copia integrale della base dati in formato standard e dei documenti caricati, con lo schema documentato. Nessun formato proprietario, nessuna chiave che trattenga i dati.
4. Nessun blocco tecnologico Il sistema poggia su tecnologie diffuse e su software libero. Non c'è alcun componente che solo noi possiamo far funzionare.

Quello che non è reversibile è il software: resta di Titano Dev Studio. La distinzione è quella normale fra i dati, che sono dell'ente, e lo strumento, che è del fornitore. Qualunque ipotesi diversa, dalla licenza d'uso perpetua alla consegna del codice sorgente, è materia di trattativa e va detta prima, non dopo.

16 Glossario

Backend

La parte del sistema che gira sul server e contiene tutte le regole. Le app sono finestre su di esso.

API

L'insieme dei punti attraverso cui un programma esterno, o un'app, chiede qualcosa al server in modo ordinato e autenticato.

Dial-a-ride

Il nome tecnico del problema del bus a chiamata condiviso: più passeggeri sullo stesso mezzo, ognuno con partenza, destinazione e vincoli propri.

Euristica di inserimento

Metodo che, invece di cercare la soluzione perfetta (impossibile nei tempi utili), prova tutte le posizioni in cui un passeggero può essere inserito nei giri esistenti e sceglie la migliore fra quelle ammissibili.

Leva

Parametro del motore modificabile dalla centrale: attesa massima, allungamento massimo, capienza e simili.

Giro

Il piano di viaggio di un mezzo: la sequenza ordinata di salite e discese che deve eseguire.

Matrice dei tempi

Tabella precalcolata dei minuti e dei chilometri fra ogni coppia di fermate. Permette al motore di decidere senza interrogare la rete.

Degradazione controllata

Criterio per cui, quando un componente esterno viene meno, il sistema perde precisione ma continua a funzionare.

Migrazione

File versionato che descrive una modifica della base dati. L'insieme delle migrazioni permette di ricostruire la base dati da zero.

Idempotente

Operazione che, ripetuta, non produce effetti ulteriori. Requisito delle procedure automatiche notturne.

A Il motore del bus a chiamata in dettaglio

Questa appendice è per chi deve valutare l'algoritmo e le scelte che lo circondano. Riprende e aggiorna la relazione di architettura di agosto 2026, che sostituisce.

A.1 Classe del problema

L'assegnazione è un problema di raccolta e consegna con finestre temporali e vincoli di capacità, noto in letteratura come pickup and delivery problem with time windows, nella variante dinamica: le richieste arrivano mentre i mezzi sono in servizio con passeggeri a bordo. È un problema NP-difficile, e le decisioni già eseguite, cioè i passeggeri saliti, non sono revocabili: vincolano lo spazio delle soluzioni successive.

L'approccio è un'euristica di inserimento con enumerazione completa delle posizioni, seguita da un raffinamento locale con guardia di non peggioramento e da una ri-ottimizzazione periodica delle sole richieste non ancora servite. L'inserimento dà una risposta entro il tempo di una richiesta; la ri-ottimizzazione recupera ciò che l'inserimento perde per l'ordine in cui le richieste arrivano.

A.2 Assegnazione di una richiesta

1. Filtro di orizzonte Una prenotazione anticipata resta fuori dai piani finché il suo orario non è vicino (leva, 30 minuti se non impostata). Poi la inserisce la ri-ottimizzazione. Il motivo è nella decisione 6 di A.7.
2. Mezzi candidati Dello stesso operatore, con un conducente in turno, in uno stato che consente di ricevere passeggeri.
3. Enumerazione degli inserimenti Per ogni mezzo e per ogni coppia di posizioni (p, q), con q dopo p nella sequenza di tappe corrente, si costruisce il piano candidato e se ne ricalcola la linea del tempo, sosta alle fermate compresa.
4. Vincoli fisici Posti e posti per carrozzina, verificati su ogni tratto del giro, e salita prima della discesa. Non sono mai derogabili.
5. Finestra sull'intero piano Nessun inserimento può estendere il giro di un mezzo oltre l'orizzonte di pianificazione (leva, 60 minuti se non impostata) più la durata massima a bordo. Un solo vincolo limita insieme l'attesa del nuovo passeggero, gli slittamenti di chi è già assegnato, il viaggio di chi è a bordo e la lunghezza dei giri.
6. Costo, e due migliori Si tiene il miglior piano che rispetta anche le leve di tempo e il miglior piano che rispetta i soli vincoli fisici. Si adotta il primo se esiste, altrimenti il secondo, marcando l'evento (decisione 5). Se non esiste nessuno dei due, la richiesta resta in coda.
7. Raffinamento locale La sequenza risultante viene riordinata per ridurre il tempo di guida, rispettando precedenze e capienza. Il nuovo ordine è accettato solo se, ricalcolato sulla linea del tempo reale, non peggiora il risultato dell'inserimento.
8. Registrazione Il piano è scritto in un'unica transazione, e gli orari promessi di tutti i passeggeri del giro vengono aggiornati insieme.

A.3 Funzione di costo

Usare la differenza invece del totale è determinante. Il totale favorirebbe sempre i mezzi meno carichi, disperdendo la domanda e riducendo le corse condivise; la differenza misura quanto la richiesta costa davvero al servizio, e rende conveniente mettere insieme passeggeri compatibili. Il peso q sceglie fra piani già ammissibili: non interviene sui vincoli.

Il supplemento di 180 secondi riguarda il passeggero a cui è già stato comunicato un mezzo: un altro mezzo lo prende solo se il guadagno supera tre minuti. Evita che il passeggero si veda cambiare mezzo per vantaggi trascurabili. Quando il cambio avviene, il passeggero viene avvisato.

A.4 Ri-ottimizzazione, ogni minuto

1. Distacco Le richieste spostabili, cioè in coda oppure assegnate ma non ancora salite, vengono staccate dai loro giri. Restano solo le tappe di chi è a bordo.
2. Compattazione I giri rimasti vuoti si chiudono. Un mezzo in pausa resta in pausa anche se il suo giro si svuota, così la fase successiva non gli riassegna passeggeri.
3. Reinserimento Ogni richiesta viene reinserita con lo stato aggiornato della flotta, in ordine stabile, con precedenza alle corse immediate.

Il ciclo gira in un'unica transazione, e chi è a bordo non viene mai spostato. In saturazione prolungata il ciclo smette di ritentare la coda dopo dieci insuccessi consecutivi, mentre chi aveva già un piano viene sempre ricollocato: il costo del ciclo resta piatto anche quando la domanda supera a lungo la capacità.

A.5 Complessità

Il termine cubico è sostenibile perché n, il numero di tappe di un giro, è limitato dalla capienza del mezzo e dalla finestra di A.2, non dal volume complessivo delle richieste. L'enumerazione resta completa, senza potature.

A.6 Il tratto che non si può precalcolare

Un solo tratto non sta nella tabella dei tempi: quello fra la posizione istantanea del mezzo e la sua prima tappa, che dipende da dove si trova il mezzo in quel momento. Per questo tratto si usa una stima geometrica, con coefficienti diversi per fascia di distanza in linea d'aria.

Il gradiente segue la morfologia della rete: sui tratti brevi pesano tornanti e ripartenze, su quelli lunghi si viaggia. I coefficienti sono accurati, non prudenti: servono a decidere, e una stima prudente porterebbe il motore a scartare abbinamenti validi. Il margine sugli orari comunicati al passeggero sta in una leva separata per operatore, tarabile sullo storico di esercizio: così una prudenza voluta nella promessa non peggiora la qualità delle decisioni.

A.7 Decisioni architetturali

Per ognuna: il contesto, la decisione, le alternative valutate, le conseguenze. Le conseguenze sfavorevoli sono scritte accanto a quelle favorevoli.

1. Tabella completa dei tempi fra le fermate

Contesto

Un'assegnazione richiede migliaia di letture di tempi fra fermate, dentro una richiesta che il cittadino sta aspettando.

Decisione

Precalcolare tutte le coppie ordinate di fermate attive e conservarle nella base dati. Il motore stradale non viene mai interrogato mentre si decide.

Alternative scartate

Calcolo a chiamata: migliaia di interrogazioni di rete dentro una transazione aperta, con latenza incompatibile e transazioni bloccate a ogni ritardo. Servizio commerciale a consumo: dipendenza esterna e costo variabile nel ciclo di decisione. Stima geometrica per tutte le coppie: su una rete collinare l'errore misurato è dell'ordine dell'80% mediano, incompatibile con la scelta delle corse condivise.

Conseguenze

A favore: lettura in tempo costante e nessuna dipendenza dalla rete. A sfavore: la tabella va ricostruita quando cambiano le fermate o la cartografia. È un'operazione fuori linea, non di sviluppo: la ricostruzione completa richiede circa sei minuti sul server di esercizio.

2. Inserimento con enumerazione completa

Contesto

Problema NP-difficile, risposta richiesta entro il tempo di una richiesta, flotta di poche unità.

Decisione

Provare tutte le coppie di posizioni di inserimento su tutti i mezzi candidati e scegliere il costo minimo, senza potature.

Alternative scartate

Formulazione esatta con programmazione lineare intera: tempi di risoluzione non garantiti, e un guadagno marginale che la dimensione del problema non giustifica. Metaeuristica evoluta a ogni richiesta: risposte non deterministiche e complessità di esercizio sproporzionata. Inserimento con potature: non necessario a questa dimensione, e renderebbe la decisione meno spiegabile.

Conseguenze

A favore: determinismo e spiegabilità, perché ogni scelta si giustifica mostrando il costo delle alternative scartate. A sfavore: sensibilità all'ordine di arrivo delle richieste, compensata dalla decisione 3; costo cubico da rivedere se la flotta o i giri crescessero di un ordine di grandezza.

3. Ri-ottimizzazione periodica

Contesto

L'inserimento incrementale produce piani ragionevoli uno per uno, ma non nel loro insieme quando l'ordine di arrivo è sfavorevole.

Decisione

Ogni minuto staccare le richieste non ancora servite e reinserirle con lo stato aggiornato, in un'unica transazione.

Alternative scartate

Nessuna ri-ottimizzazione: la distanza dall'ottimo cresce con la densità della domanda, cioè proprio quando il servizio è sotto pressione. Ri-ottimizzazione a ogni inserimento: costo incompatibile con la risposta immediata. Spostare anche chi è a bordo: fisicamente non eseguibile.

Conseguenze

A favore: recupero di efficienza e riparazione automatica degli stati non ottimali, compresi quelli nati dalla concorrenza (decisione 7). A sfavore: l'orario previsto di chi non è ancora salito può cambiare, in meglio o in peggio. Per questo lo spostamento di un mezzo costa un supplemento (A.3) e il passeggero riceve un avviso quando il suo orario si sposta di almeno due minuti.

4. Motore stradale installato in casa

Contesto

Servono tempi su strade vere, senza dipendere da servizi esterni e senza far uscire i percorsi dei cittadini dall'infrastruttura.

Decisione

Motore di calcolo dei percorsi a sorgente aperta, eseguito sul server di esercizio, con cartografia del territorio e un profilo di percorrenza tarato sul minibus (capitolo 05).

Alternative scartate

Servizio cartografico commerciale: costo per interrogazione, limiti di frequenza, trasmissione a terzi delle origini e destinazioni dei cittadini. Licenza commerciale dello stesso motore: il vantaggio riguarderebbe solo il calcolo della tabella, un'operazione fuori linea e rara.

Conseguenze

A favore: nessun costo variabile, nessun limite di frequenza, nessun percorso che lascia l'infrastruttura. A sfavore: il motore va tenuto in esercizio, presidiato da sentinella e riavvio automatico; non c'è modellazione del traffico in tempo reale.

5. Leve di tempo morbide, con piano di ripiego

Contesto

In picco può non esistere nessun piano che rispetti le leve di attesa e di allungamento, pur essendoci posti liberi.

Decisione

Tenere durante la ricerca due migliori, come in A.2: il migliore dentro le leve e il migliore dentro i soli vincoli fisici. In mancanza del primo si assegna il secondo. La richiesta resta in coda solo se non c'è posto fisico in tutta la flotta, o se ogni piano possibile esce dalla finestra di pianificazione.

Alternative scartate

Rifiutare la richiesta: in un servizio pubblico non è accettabile lasciare una persona a piedi con posti liberi. Alzare le leve da sole in picco: la promessa di servizio diventerebbe non verificabile a posteriori.

Conseguenze

A favore: il servizio continua anche in picco. A sfavore: in saturazione alcune assegnazioni escono dalle leve. L'evento è marcato, il preventivo lo dice al cittadino prima che confermi, e a posteriori è misurabile come indicatore di qualità.

6. Prenotazioni anticipate inserite in prossimità dell'orario

Contesto

Una tappa con orario lontano, inserita subito nel giro corrente, produrrebbe un piano formalmente valido in cui il mezzo va subito alla fermata e aspetta.

Decisione

Le prenotazioni con orario oltre una soglia restano fuori dai piani e vengono inserite dalla ri-ottimizzazione quando l'orario si avvicina. La salita non viene mai pianificata prima dell'orario richiesto.

Alternative scartate

Finestre temporali estese nel modello: spazio di ricerca più grande senza beneficio, perché lo stato della flotta a quell'ora non è noto. Pianificazione separata delle programmate: due piani indipendenti sullo stesso mezzo, con il problema di concorrenza della decisione 7 amplificato.

Conseguenze

A favore: l'inserimento avviene con l'informazione completa sullo stato della flotta. A sfavore: l'orario definitivo si conosce in prossimità della partenza, non al momento della prenotazione. Il cittadino riceve una conferma alla prenotazione, un promemoria prima della partenza se ha prenotato con largo anticipo, e un avviso se l'orario si sposta.

7. Consistenza per transazione e riparazione periodica

Contesto

Due assegnazioni contemporanee possono valutare lo stesso mezzo partendo dallo stesso stato.

Decisione

Registrazione del piano in transazione, senza blocco esclusivo sul mezzo durante la ricerca. Gli eventuali piani non ottimali vengono corretti dalla ri-ottimizzazione.

Alternative scartate

Blocco esclusivo per mezzo: serializzerebbe tutta la ricerca, con un costo sproporzionato rispetto a una probabilità di collisione bassa. Controllo ottimistico sulla versione del giro: non implementato, è l'evoluzione naturale se il volume di richieste crescesse.

Conseguenze

A favore: nessuna contesa nel percorso di assegnazione. A sfavore: in caso di concorrenza effettiva sullo stesso mezzo il piano può risultare non ottimale. Non può risultare incoerente, perché i vincoli fisici vengono verificati di nuovo a ogni inserimento.

8. Posizione dei mezzi su un canale dedicato

Contesto

La posizione dei mezzi deve arrivare alle app e alla consolle spesso e con poco ritardo.

Decisione

L'app del conducente pubblica la posizione su un canale in tempo reale dedicato, circa una volta al secondo quando il mezzo si muove. App del cittadino e consolle la leggono direttamente, senza passare dal server applicativo. Se il canale tace per 15 secondi, tornano a chiedere la posizione al server.

Alternative scartate

Connessioni persistenti sul server applicativo: il suo dimensionamento dipenderebbe dal numero di persone collegate invece che dalle prenotazioni. Interrogazione periodica del server come canale principale: carico proporzionale ai telefoni collegati e ritardo visibile sulla mappa.

Conseguenze

A favore: il carico del server cresce con le prenotazioni, non con chi guarda la mappa, e il mezzo si muove in modo fluido sullo schermo. A sfavore: dipendenza da un servizio esterno per la sola visualizzazione; se viene meno, assegnazioni e corse continuano e la mappa si aggiorna più di rado.

A.8 Misure

Ogni valore ha accanto la procedura che lo riproduce e la data in cui è stato misurato.