docs(windows): outline local device bridge architecture
This commit is contained in:
parent
de3c95b32a
commit
5f248f825c
176
docs/WINDOWS-DEVICE-BRIDGE.md
Normal file
176
docs/WINDOWS-DEVICE-BRIDGE.md
Normal file
|
|
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user