netgescon-day0/docs/WINDOWS-DEVICE-BRIDGE.md

Windows Device Bridge per NetGescon

Obiettivo

Creare un componente utilizzabile su postazioni Windows per collegare il browser NetGescon a periferiche locali che il browser da solo non gestisce in modo affidabile o uniforme:

• scanner TWAIN o WIA;
• lettori/scrittori NFC;
• dispositivi seriali;
• scanner o lettori QR/barcode.

Conclusione breve

Si, e possibile, ma non come Blade pura o JavaScript puro nel browser.

Per TWAIN la strada corretta e un bridge locale Windows, installato sulla macchina utente, che espone una API locale sicura e parla con NetGescon via browser.

Perche non basta il browser

• TWAIN non e una API web standard.
• WIA e un layer Windows locale, non direttamente esposto al browser.
• WebNFC oggi e limitato e non copre bene il desktop Windows reale.
• WebSerial puo aiutare solo per dispositivi seriali compatibili e con permessi espliciti del browser.
• Molti scanner QR e barcode lavorano in modalita HID tastiera e quindi non richiedono bridge, ma non tutti.

Architettura consigliata

1. Agent locale Windows

Servizio o tray app installata sulla postazione, ad esempio:

• .NET 8 per integrazione Windows nativa;
• servizio locale su http://127.0.0.1:17890 oppure WebSocket locale;
• pairing con token temporaneo firmato da NetGescon.

Responsabilita dell'agent:

• enumerare scanner TWAIN/WIA;
• acquisire scansioni PDF o immagini;
• leggere/scrivere NFC;
• leggere porte seriali;
• ricevere input da lettori QR dedicati non HID;
• pubblicare eventi al browser;
• caricare file e metadati verso NetGescon.

2. Componente frontend NetGescon

Componente riusabile nella UI Filament o Blade che:

• verifica se l'agent locale risponde;
• mostra lo stato periferiche disponibili;
• apre le azioni: scansiona, leggi NFC, apri seriale, attendi QR;
• riceve il risultato dall'agent;
• salva documento o metadati nel modulo giusto.

3. Endpoint backend NetGescon

API Laravel dedicate per:

• upload PDF/scansioni con metadati archivio;
• memorizzazione eventi NFC;
• memorizzazione letture seriali;
• memorizzazione codici QR/barcode;
• audit e tracciatura operatore/macchina.

Matrice supporto dispositivi

Scanner TWAIN/WIA

Supporto: alto tramite agent Windows.

Approccio:

• l'agent enumera sorgenti scanner;
• l'utente sceglie il profilo;
• l'agent produce PDF o immagini;
• il browser invia i metadati archivio a NetGescon.

NFC

Supporto: medio-alto tramite agent.

Approccio:

• lettura UID, NDEF e blocchi compatibili;
• scrittura tag solo su profili autorizzati;
• mapping con documenti, cespiti, chiavi, contenitori, badge.

Seriale

Supporto: alto.

Approccio:

• agent locale apre COM e inoltra stream o pacchetti al browser;
• configurazioni per baud rate, parity, stop bit, framing.

QR / barcode

Supporto: molto alto.

Approccio preferito:

• prima usare lettori HID, che scrivono come tastiera nei campi di input;
• usare il bridge solo per lettori industriali o feed continui.

Flussi NetGescon consigliati

A. Documenti da scanner

1. Il componente web chiede all'agent la lista scanner.
2. L'utente avvia la scansione.
3. L'agent genera PDF.
4. Il browser invia PDF e metadati alla pagina Documenti.
5. NetGescon salva in archivio e lancia OCR.

B. NFC per archivio fisico o cespiti

1. Il componente chiede readNfc.
2. L'agent restituisce UID e payload.
3. NetGescon collega il tag a documento, faldone, cespite o ticket.

C. Seriale per dispositivi legacy

1. Il componente apre la porta via agent.
2. L'agent invia i dati in streaming o a record.
3. NetGescon salva l'evento e lo associa al modulo corretto.

Sicurezza minima

• ascolto solo su 127.0.0.1;
• token effimeri generati da NetGescon;
• allowlist delle origin autorizzate;
• audit locale e server;
• firma dei pacchetti piu sensibili;
• blocco delle operazioni di scrittura NFC senza permesso esplicito.

Fasi consigliate

Fase 1

Bridge Windows + upload scanner PDF + lettori HID QR/barcode.

Questa e la fase con il miglior rapporto valore/complessita.

Fase 2

NFC lettura e associazione a documenti, faldoni, cespiti o accessi.

Fase 3

Seriale e dispositivi speciali.

Fase 4

Scrittura NFC e automazioni avanzate scanner.

Raccomandazione pratica

Per NetGescon conviene partire da un progetto separato chiamabile ad esempio netgescon-device-bridge-windows con:

• agent desktop Windows .NET;
• API locale REST/WebSocket;
• componente frontend unico device-bridge-panel dentro Filament;
• primo caso d'uso: pagina Documenti, tab Scansione documenti.

Stato attuale del repository

Il repository ha gia una base web utile lato Documenti:

• upload PDF da scanner;
• classificazione immediata nel modulo Documenti;
• metadati di canale acquisizione;
• pipeline pronta per OCR e archivio.

Manca invece il bridge locale Windows che pilota davvero TWAIN/WIA, NFC e seriale.