netgescon-day0/docs/DOCUMENTI-NFC-E-ACQUISIZIONE.md

# Documenti, NFC e acquisizione

## Stato attuale archivio documenti

La pagina Strumenti > Documenti gestisce gia un flusso rapido di archiviazione:

- selezione stabile;
- scelta cartella archivio con ACL;
- categoria protocollo e titolo;
- metadati principali del documento;
- upload PDF;
- protocollo progressivo automatico;
- collegamento eventuale a movimento contabile;
- indicazione faldone fisico per l'archivio cartaceo.

Dopo il salvataggio il documento viene gia memorizzato con:

- file PDF archiviato;
- protocollo interno;
- cartella logica;
- visibilita per ruolo, gruppo e utente singolo;
- estrazione testo best-effort per ricerca tramite `PdfTextExtractionService`.

## Tab scansione documenti

La pagina `Strumenti > Documenti` include ora una tab dedicata chiamata `Scansione documenti`.

Questa tab copre il flusso subito testabile in staging senza dipendere da un comando diretto browser -> scanner:

- upload del PDF prodotto dallo scanner;
- selezione stabile, cartella archivio, categoria e classe archivio;
- tracciamento del canale di acquisizione;
- salvataggio del riferimento batch o sessione;
- riuso dello stesso motore documento e della stessa pipeline OCR gia presenti.

Metadati aggiuntivi salvati nel documento:

- `canale_acquisizione`;
- `scanner_profile`;
- `riferimento_acquisizione`;
- `origine_documento`.

Canali previsti nella prima versione operativa:

- upload PDF da scanner;
- scanner Epson verso cartella o rete;
- scanner via email;
- upload mobile o camera;
- acquisizione manuale.

## Dashboard protocollo comunicazioni

La pagina Strumenti > Documenti ora apre di default una prima tab dedicata al protocollo comunicazioni.

Questa vista e pensata come dashboard operativa per l'amministratore e mostra solo i documenti visibili diversi dalle fatture.

Funzioni attive:

- ricerca live su protocollo, titolo, descrizione, ente e riferimento archivio;
- filtro per categoria documento;
- vista a box universale per allegati PDF, immagini, file Office e testi;
- vista lista compatta per consultazione rapida;
- contatori rapidi su totale documenti, allegati disponibili, inserimenti del mese e categorie presenti.

Aggiornamento operativo:

- la griglia box e stata estesa fino a 4 schede per riga sui layout ampi;
- il pulsante `Apri` usa lo stesso endpoint inline gia esistente e quindi non resta limitato ai soli PDF;
- il pulsante `Stampa` viene mostrato solo per i tipi file che il browser puo gestire in modo utile in preview o print;
- i documenti senza file restano comunque visibili come metadati di protocollo, senza forzare una falsa anteprima.

Scelta implementativa:

- la tab usa i record `Documento` gia protocollati e gia filtrati dal servizio di visibilita;
- le fatture restano nella loro vista archivio digitale separata;
- non e stato aperto un sottosistema parallelo su `CommunicationMessage` per evitare doppioni funzionali in questa fase.

## Archivio fisico ed etichette

La base operativa dell'archivio cartaceo e ora utilizzabile con etichette e codici persistenti.

Capacita disponibili:

- registrazione di elementi fisici come documento, busta, cartella a tre lembi, faldone con anelli, faldone con lacci e scatola;
- collegamento facoltativo tra voce fisica e documento digitale;
- codifica univoca persistente per la movimentazione dell'archivio;
- stampa etichette nei formati `DYMO 11354` e `DYMO 99014`;
- pagina pubblica firmata per dettaglio contenitore o documento tramite QR.

Etichette generiche evolute:

- preset rapidi per scatole, raccoglitori, buste e nodi logistici;
- scelta layout con varianti QR a destra o in basso;
- binding dei campi DB nelle zone titolo, sottotitolo, meta e nota;
- preview grafica live prima del salvataggio;
- salvataggio del template dentro `metadati.generic_label_template`, cosi la stampa reale segue lo stesso disegno scelto in tab.

Taratura operativa corrente:

- `11354`: layout orizzontale principale con correzione verticale leggera verso l'alto;
- `11354 verticale`: variante dedicata ai driver che ruotano l'etichetta, ora con rotazione corretta lato stampa;
- `99014`: QR spostato in basso a destra per liberare spazio scrivibile nella parte alta.

Per i documenti digitali resta disponibile anche l'assegnazione dei metadati fisici principali:

- supporto fisico;
- contenitore o faldone;
- busta;
- fascicolo;
- periodo di riferimento;
- modello etichetta;
- watermark predefinito in stampa.

## QR locale sulle etichette

La generazione QR per le etichette fisiche non dipende piu da servizi remoti.

Dettagli operativi:

- viene usata la libreria gia presente nel progetto `chillerlan/php-qrcode`;
- non e stato aggiunto `simple-qrcode` per incompatibilita con il lock corrente su `bacon/bacon-qr-code`;
- il rendering finale viene convertito in SVG inline, cosi il preview di stampa resta visibile anche nel browser e il QR non esce dai margini dell'etichetta.

Questo elimina la dipendenza da URL esterni per il QR e rende piu stabile il preview di stampa.

## QR pubblico e dominio esterno

Il QR dell'archivio fisico non deve piu dipendere dall'IP interno del server.

Implementazione attuale:

- la firma della route pubblica viene generata in forma relativa;
- il link finale viene costruito usando `APP_PUBLIC_URL`, con fallback su `APP_URL`;
- la validazione avviene lato controller con firma relativa, cosi il QR resta valido anche dietro dominio pubblico o reverse proxy.

Questo rende il QR gia abbastanza universale anche nel caso di passaggio del materiale tra amministratori, perche il riferimento stabile e l'item fisico firmato e non l'identita del singolo operatore che ha creato l'etichetta.

Configurazione richiesta in ambiente:

1. impostare `APP_PUBLIC_URL` con il dominio realmente raggiungibile dall'esterno;
2. lasciare `APP_URL` per il contesto applicativo interno se serve;
3. rigenerare o aggiornare i QR gia salvati solo se si vuole riallineare anche il dato persistito nel database.

Esempio:

- `APP_PUBLIC_URL=https://netgescon.example.it`

## Stampa PDF e watermark archivio

Per i documenti PDF sono ora previste due aperture distinte dalla tab archivio:

- apertura/stampa standard del PDF;
- apertura con watermark archivio digitale e fisico, quando i riferimenti archivistici sono presenti.

Il watermark usa Ghostscript solo se disponibile lato server. In assenza del binario, il PDF continua ad aprirsi senza bloccare il flusso.

## Topbar contestuale

La topbar Filament non usa piu lo scorrimento orizzontale per stabile, gestione e anno.

La soluzione adottata e strutturale:

- i controlli ora vanno a capo;
- il contenitore topbar nasconde l'overflow orizzontale;
- il selettore riscaldamento continua a dipendere dallo stato operativo reale dello stabile.

## Indicizzazione e OCR

La base applicativa e gia predisposta per:

- testo OCR o testo estratto dal PDF;
- metadati OCR;
- ricerca documentale su contenuto;
- classificazione guidata con cartelle e categorie.

La parte da verificare operativamente e la qualita reale dell'estrazione sui documenti scansionati e sui PDF immagine. Il prossimo test utile e:

1. caricare un PDF nativo;
2. caricare un PDF da scanner;
3. verificare contenuto OCR salvato e ricercabilita.

## PDF watermark e firma

Fattibile lato server:

- watermark visivo con protocollo, stabile, data e utente;
- timbro di archiviazione;
- overlay su PDF acquisiti;
- ristampa etichetta o frontespizio.

Da distinguere dalla firma digitale vera:

- watermark: semplice e interno, subito fattibile;
- firma PAdES/CAdES: richiede certificato, firma remota o dispositivo di firma.

Quindi la strada pragmatica e:

1. watermark/timbro immediato per i PDF archiviati;
2. firma digitale solo quando decidiamo provider o certificato operativo.

## Short link con bcards.it

Il dominio `bcards.it` si presta bene a generare short link per:

- apertura rapida cartella archivio;
- apertura scheda stabile;
- apertura documento o checklist;
- accesso a presenza assemblea;
- accesso a votazione assemblea;
- accesso a pagina di scansione o acquisizione.

Architettura consigliata:

- short code univoco nel dominio corto;
- redirect verso URL NetGescon firmata o tokenizzata;
- scadenza opzionale;
- tracciamento accessi;
- associazione a tag NFC o QR.

## iPhone e autenticazione dispositivo

Safari su iPhone non espone seriale hardware, IMEI o MAC address alla pagina web.

La soluzione corretta e:

- primo accesso con login normale;
- enrollment del dispositivo;
- passkey/WebAuthn o token revocabile;
- NFC che apre short link;
- il browser completa l'autenticazione con la credenziale gia registrata.

## ACR122U e tag NFC da PC

Con il lettore/scrittore ACR122U su PC si puo lavorare, ma non in modo affidabile da una semplice pagina web pura per tutti i browser.

Strade realistiche:

- Chrome/Edge desktop con WebUSB/WebHID: possibile solo in alcuni scenari, non ideale come base di produzione;
- bridge locale su PC con PC/SC o libnfc: soluzione robusta;
- pagina web NetGescon che dialoga con un piccolo servizio locale: soluzione consigliata.

Uso previsto:

- leggere UID o NDEF del tag;
- scrivere short link `bcards.it/...`;
- associare il tag a faldone, cartella, documento o stabile;
- richiamare in un click la scheda giusta.

## Presenze e votazioni assemblea

Fattibile nello stesso impianto:

- convocazione assemblea;
- check-in presenza via link corto, QR o NFC;
- conteggio deleghe e millesimi presenti;
- apertura votazioni per punto ODG;
- raccolta voto da device autenticato;
- verbale e report finale.

Per farlo bene conviene usare due livelli:

- regia assemblea da desktop operatore;
- accesso rapido da smartphone per presenza e voto quando previsto.

## Scanner Epson da pagina web

Pilotare uno scanner Epson direttamente da una pagina web standard non e generalmente affidabile.

Le strade reali sono:

- scanner di rete che salva in cartella o invia via mail;
- agente locale Windows che usa TWAIN/WIA/SDK Epson;
- pagina web che invia il comando al servizio locale e acquisisce il PDF risultante.

Per operativita immediata la soluzione piu semplice e:

1. scansione verso cartella controllata;
2. upload/ingestione rapida nella tab `Scansione documenti` di NetGescon;
3. OCR e archiviazione automatica.

Per il modello Epson WF-C5710 la direzione pratica da testare non e il browser puro, ma una di queste due:

- scansione verso cartella di rete osservata da NetGescon;
- piccolo bridge locale o di rete che espone una chiamata HTTP interna e usa il canale scanner disponibile sul dispositivo.

Questo evita il vincolo dei browser su TWAIN/WIA e mantiene il flusso pilotabile dalla pagina archivio.

## Archivio digitale

La vista `Strumenti > Documenti > Archivio digitale` e stata alleggerita per lavorare meglio dentro la cartella corrente.

Stato attuale:

- breadcrumb e cartelle restano in alto;
- la tabella documenti ora usa tutta la larghezza utile;
- le informazioni laterali sono state compattate in tre card sintetiche sopra la tabella;
- la pagina mostra nome cartella attiva, numero documenti del livello e stato operativo digitale/fisico.

## Dymo LAN 11354

Domani si puo provare una stampa etichetta su rete con formato `11354` usando:

- template HTML/PDF per etichetta;
- spool di stampa verso stampante LAN;
- contenuti minimi: codice stabile, tipo archivio, faldone/cartella, short link o QR.

Nota stato attuale:

- l'app genera gia il layout etichetta e il QR locale;
- non e ancora stato collegato uno spool diretto verso la DYMO su IP `192.168.0.56`;
- restano quindi aperte due strade operative: stampa via macchina Windows gia configurata oppure invio diretto future-proof verso stampante di rete.

## Prossimi passi consigliati

1. test reale OCR e ricerca su 2-3 PDF campione caricati dalla tab `Scansione documenti`;
2. prova con un PDF generato da Epson ADF e verifica dei metadati `canale_acquisizione` e `riferimento_acquisizione`;
3. attivazione watermark PDF in archiviazione;
4. tabella short links con dominio `bcards.it`;
5. bridge locale PC per ACR122U;
6. prova Dymo LAN con etichetta 11354;
7. definizione modulo presenza e voto assemblea.