# 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.