diff --git a/docs/WINDOWS-DEVICE-BRIDGE.md b/docs/WINDOWS-DEVICE-BRIDGE.md new file mode 100644 index 0000000..20a6e07 --- /dev/null +++ b/docs/WINDOWS-DEVICE-BRIDGE.md @@ -0,0 +1,176 @@ +# 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.