come è costruito
Costruito per essere verificato.
Un browser, le funzioni dell’app, un database Postgres con una regola per ogni organizzazione, un archivio di file: tutto in Europa. Qui vedi come lavorano insieme, che cosa succede quando il telefono perde la rete e perché un documento emesso non cambia di nascosto.
01architettura
Quattro stazioni, una sola regola per i dati.
Le pagine dell’app si compongono sul server, vicino al database. Il browser riceve la pagina pronta e le sole righe che la tua organizzazione può leggere.
Il browser
Parla con il sito solo in HTTPS. Ogni risposta porta una politica dei contenuti con un nonce nuovo: il browser esegue solo gli script firmati da quella risposta.
Le funzioni dell’app
Componenti server e azioni del server di Next.js: verificano la sessione e l’organizzazione attiva, poi parlano con il database a nome di chi ha chiesto.
Il database
Postgres, in Europa. Su ogni tabella con i dati di un’azienda una regola lascia passare solo le righe delle organizzazioni di chi chiede.
L’archivio dei file
Foto, documenti e PDF. Si leggono con link firmati che scadono; le foto del campo arrivano dirette dal telefono con un biglietto firmato per quel file.
02senza rete
Il tecnico lavora anche in cantina. Il lavoro parte quando torna il segnale.
Nell’app del tecnico ogni gesto riesce subito sul telefono e aspetta in una coda salvata sul dispositivo. Quando la rete torna, la coda si svuota da sola, una volta sola per gesto.
- Cambio di stato
work_order.transitionid 7c1e9a42 · gesto 09:12:04in attesa - Foto
evidence.uploadid e4b20d6f · gesto 09:14:37in attesa
Aggiungi una foto o cambia stato, poi riaccendi la rete.
Un identificativo per gesto
Ogni gesto nasce sul telefono con il suo identificativo, che fa da chiave contro i doppioni: se una risposta si perde e il telefono riprova, il server riconosce il gesto e non crea una seconda riga.
L’ora vera
Resta l’ora in cui il tecnico ha fatto il gesto, non quella in cui il telefono ha ritrovato la rete.
Niente perso in silenzio
Se tecnico e ufficio cambiano la stessa cosa, l’app la mette fra quelle «da rivedere» e chiede quale tenere. Se il server rifiuta un gesto, lo dice con il motivo.
Un service worker prudente
Senza rete l’app del tecnico si apre lo stesso, invece della pagina d’errore del browser. Il service worker conserva solo le pagine senza dati dell’azienda e i file del programma; i dati passano dalla coda, mai dalla sua cache.
03impronta digitale
Cambia una lettera, cambia l’impronta.
Un documento definitivo conserva l’impronta SHA-256 del suo contenuto. Modifica il testo qui sotto: l’impronta la ricalcola il tuo browser, e basta una virgola perché non coincida più.
57f6f4f9c8c38f73118e713d90ac4daeece4bf07090a3a5c3940970b013dee9dCoincide con l’impronta registrata: il documento è quello emesso.
Perché funziona. Dall’impronta non si ricostruisce il documento, e non si conosce un modo pratico per scrivere un documento diverso con la stessa impronta. Chi conserva l’impronta di un documento emesso si accorge di qualunque modifica.
Dove la usiamo. Documenti confermati della Logistica, definitivi del Doc Lab, report archiviati e firme: ognuno porta l’impronta del contenuto com’era al momento dell’emissione.
04qr, nfc ed etichette
Il bene porta il suo indirizzo. Il telefono lo apre.
Ogni bene ha un QR che porta alla sua scheda; lo stesso indirizzo si scrive su un tag NFC. Le etichette si disegnano nell’app e si stampano dal browser.
QR generato sul server
Il codice porta a un indirizzo con un gettone del bene. Inquadrato da chi lavora con te apre la scheda sul telefono; a chi non è entrato chiede prima l’accesso.
Tag NFC dal browser
Con Chrome su Android l’app scrive l’indirizzo del bene sul tag (Web NFC): avvicini il telefono e la scheda si apre.
Etichette vettoriali
Label Studio disegna le etichette in SVG: si scaricano in SVG o PNG, si stampano su foglio A4 o si salvano in PDF dalla finestra di stampa del browser.
05pdf e verifiche pubbliche
Chi riceve un documento lo controlla da sé.
Le pagine di verifica sono pubbliche e non chiedono un account: se per controllare servisse essere dei nostri, la prova varrebbe la metà. Mostrano solo ciò che serve alla fiducia.
/verifica/…Verifica per impronta
Mostra se l’impronta è registrata e, partendo dall’ancora, se il dato di oggi produce ancora la stessa impronta.
/od/…Documenti operativi del Doc Lab
Mostra tipo, numero, data, organizzazione, controparte, stato e impronta.
/certificato/…Certificati di taratura
Mostra centro, attrezzatura, esito, emissione, scadenza e impronta.
I PDF dei report
Si compongono sul server: un Chromium senza interfaccia apre una pagina di stampa raggiungibile solo con un indirizzo firmato e a scadenza breve, e ne fa il PDF. Il report archiviato conserva l’impronta del suo contenuto.
Mai righe, importi o note nelle pagine pubbliche: solo ciò che identifica il documento, il suo stato e l’impronta.
06prove e disciplina
Prima la prova, poi la modifica.
Le regole che contano hanno prove automatiche scritte accanto al codice. Le modifiche al database seguono un percorso fisso, e non si salta un passo.
packages/core/src/offline/outbox.test.tsla coda offline: doppioni, ordine di partenza, nuovi tentativi, modifiche concorrentipackages/core/src/auth/permissions.test.tsla mappa dei permessi di ogni ruolosrc/lib/offline/idb.test.tsla coda sul telefono: un gesto è confermato solo quando è scrittosrc/app/api/stripe/webhook/route.test.tsi pagamenti: firma verificata, un evento ripetuto si elabora una voltasrc/server/pdf/render.test.tsla stampa dei PDF sul serversrc/lib/label-studio/layout.test.tsi modelli di etichetta: QR, testi e misure
La prova, rossa
Lo script di prova si scrive prima della modifica: deve fallire prima e passare dopo.
La migrazione con la sua guardia
Ogni modifica al database è un file che finisce con un controllo: se il risultato non è quello atteso, si annulla da sola.
Il ritorno, scritto insieme
Il file per tornare indietro nasce con la migrazione, non dopo.
Un ambiente alla volta
Ogni migrazione gira prima su un database locale, poi su quello di prova; all’ambiente successivo arriva solo dopo essere passata verde. Le prove sulle regole girano in una transazione che alla fine si annulla.
07scheda tecnica
I componenti, per nome
Le versioni sono lette dai file del progetto quando la pagina viene costruita.
- Interfaccia
- Next.js 15.5.28 · React 19App Router, componenti server, TypeScript
- Funzioni
- Funzioni serverin Europa, accanto al database
- Database
- Postgresin Europa, regole per organizzazione
- File
- Archivio a oggetti privatolink firmati a tempo, caricamento diretto
- Accessi
- Sessioni verificate sul serververifica in due passaggi TOTP
- Pagamenti
- Stripeeventi firmati, verificati prima di agire
- Intelligenza artificiale
- Anthropic Claudepropone; conferma una persona
- Resendavvisi e report programmati
- Chromium senza interfacciapagina di stampa con indirizzo firmato
- Senza rete
- Service worker e IndexedDBscritti a mano, senza librerie
- Prove
- Vitest e transazioni annullatelogica pura e regole del database
- Caratteri
- Geist e Geist Monoserviti dal sito stesso, senza richieste a terzi
inizia
Mettilo alla prova con i tuoi beni.
14 giorni con tutti i moduli, senza carta. L’app del tecnico, il QR e i documenti con impronta sono compresi.