netgescon-day0/docs/roadmaps/DOCUMENTI-ARCHIVIO-DAFARE.md

Documenti Archivio DAFARE

Obiettivo operativo

Costruire un flusso unico che parta dal file digitale, generi una codifica master stabile, stampi etichette QR leggibili, colleghi eventuali tag NFC o RFID e accompagni il documento dentro la catena fisica fino alla collocazione finale o al passaggio consegne tra amministratori.

Stato reale da cui partiamo

• Nel modulo documenti esistono gia tre concetti separati da unificare: Categoria, Classe archivio e Voce archivio.
• Nel codice attuale il punto piu vicino e app/Filament/Pages/Strumenti/DocumentiArchivio.php, dove la tab scansione usa categoria e archivio_classe, mentre l'archivio fisico registra la voce separatamente.
• Per le assemblee esiste gia una base dati con Assemblea, OrdineGiorno, Convocazione, PresenzaAssemblea, Verbale, DocumentoAssemblea e collegamenti allo stabile.
• Il lavoro da fare ora non e inventare concetti nuovi, ma unificare nomenclatura, codifica e flussi sopra strutture gia presenti.

Decisione guida

Tutto deve convergere su una sola codifica master archivistica, usata in quattro contesti:

1. Nome logico del documento e riferimento archivistico umano.
2. Payload QR o tag NFC.
3. Chiave di import/export per passaggio consegne tra amministratori.
4. Ancoraggio comune per archivio digitale, archivio fisico, assemblee e future automazioni hardware.

Gruppo A - Codifica master unificata archivio

Obiettivo

Sostituire i tre campi disallineati con un unico concetto di classificazione archivistica master, mantenendo compatibilita con le schermate esistenti.

Modello logico proposto

• codice_master: identificatore archivistico stabile e stampabile
• famiglia_archivio: macro famiglia funzionale
• classe_archivio: classe normalizzata interna
• voce_archivio: descrizione umana operativa
• versione_schema: versione della codifica XML, QR e NFC

Convenzioni archivio da fissare

Famiglie iniziali

• CONTR: contratti di servizio
• ASSIC: polizze assicurative
• CERT: certificati e autorizzazioni
• PREV: preventivi e offerte
• FATT: fatture e documenti fiscali
• VERB: verbali assemblee
• ASSEMB: convocazioni, allegati, presenze e verbali assembleari
• DOC: altri documenti

Regole comuni

• Il codice deve essere Linux-safe: maiuscolo, senza spazi, solo caratteri stabili.
• Il codice mnemonico deve diventare sia nome logico del file digitale sia fallback umano dell'etichetta stampata.
• Il QR o tag deve contenere sempre almeno schema, codice_master, tipo_record, stabile, hash o checksum.
• Il passaggio consegne tra amministratori deve riusare lo stesso codice senza ricodifiche locali.
• La descrizione umana puo cambiare, il codice master no.

Formato consigliato del codice master

• FAMIGLIA-ANNO-SEQ
• esempi:
• CONTR-2026-001
• VERB-2026-014
• ASSEMB-2026-005

Data nei file

• Inserire la data nel nome file con formato YYMMGG.
• Prevedere una futura impostazione generale dell'amministratore per cambiare il formato globale della data.

Gruppo B - XML master per QR, NFC e passaggio consegne

Obiettivo

Usare XML come formato di trasporto e scambio per non dipendere da link esterni, URL o host specifici.

Vincolo tecnico da non perdere di vista

• Un QR standard non e affidabile per 6000 byte in lettura smartphone generalista.
• Per uso reale conviene progettare un XML compatto e mantenere un payload sicuro molto piu basso.
• Un NTAG215 offre circa 504 byte utili: questo obbliga a usare un XML molto compatto o una variante abbreviata dedicata al tag NFC.
• Quindi servono due profili dello stesso schema:
• MASTER-XML-FULL per esportazioni, passaggi consegne e QR ad alta capienza
• MASTER-XML-LITE per QR rapidi e soprattutto per NTAG215

Campi minimi del profilo full

• schema
• versione
• tipo_record
• codice_master
• stabile_id o codice_stabile
• titolo
• note sintetiche
• nome_file
• classe_archivio normalizzata
• voce_archivio umana
• tag liberi
• riferimento RFID o NFC se presente
• pagine o consistenza fogli
• checksum

Campi minimi del profilo lite

• schema
• versione
• tipo_record
• codice_master
• stabile
• classe
• checksum

Uso operativo previsto

• QR su singolo documento
• QR su cartellina, faldone, scatola o foglio consegna
• QR master finale su verbale di passaggio consegne con tabella di codifica incorporata
• Tag NFC adesivo per scrittura e rilettura rapida da app o bridge locale

Regola importante

Se la lettura trova un codice_master gia presente nel DB, il sistema deve collegare e arricchire il record esistente; se non lo trova, deve proporre import guidato o creazione rapida.

Gruppo C - Flusso documenti e archivio fisico

Flussi da realizzare

1. Gestione file base

Una Blade dedicata deve permettere di registrare il singolo file o una raccolta di fogli con:

• titolo
• descrizione
• note
• tag
• classificazione master strutturata
• numero totale dei fogli o dell'incartamento
• selezione del layout etichetta da usare
• stampa etichetta con QR e fallback testuale nel titolo e sotto il QR
• eventuale lettura o scrittura NFC

2. Primo contenitore fisico

Dal file base bisogna poter scegliere il primo supporto:

• busta ad anelli
• faldone a tre lembi
• raccoglitore
• altro supporto scelto a catalogo

Il record deve restare collegato al documento digitale per consentire nuove stampe dell'etichetta in qualsiasi momento.

3. Contenitori successivi e movimentazione

Serve una gestione separata dove il materiale gia preparato venga caricato nei contenitori successivi:

• cartellina
• busta
• faldone
• scatola
• scaffale
• posto finale

La tab movimentazione-codici deve diventare il centro operativo per:

• cambiare il contenitore padre
• aggiornare supporto operativo
• aggiornare magazzino, scaffale, ripiano e dettaglio ubicazione
• leggere codici da scanner, smartphone, QR o bridge locale
• associare o riscrivere NFC quando consentito dal profilo utente

Slice da fare subito su documenti

1. Rifinire il builder etichette su etichette-generiche.
2. Tenere le impostazioni accanto alla riga o al campo che controllano.
3. Rendere piu esplicita la modifica e la ristampa delle etichette gia create.
4. Portare la gestione di supporto e ubicazione nella tab movimentazione-codici.
5. Preparare il flusso file base -> primo supporto -> contenitori successivi.
6. Introdurre una tabella unica di classificazione da cui derivano Categoria, Classe archivio e Voce archivio.

Gruppo D - Etichette 11354 e binding DB

• Per il formato 11354 prevedere un campo di collegamento ai dati DB da riversare automaticamente in stampa.
• Ogni riga deve poter leggere un campo DB oppure testo libero.
• Le impostazioni della singola riga devono stare vicino alla riga stessa.
• La ristampa deve essere disponibile anche se fallisce la lettura automatica del QR.
• Il payload QR stampato deve poter scegliere tra XML lite, XML full o semplice codice master.

Gruppo E - Plugin locale o bridge dispositivi

Obiettivo

Un agent locale deve fare da ponte fra browser e hardware, sia in lettura che in scrittura.

Periferiche previste

• TWAIN/WIA scanner
• lettori barcode e QR
• NFC
• seriali
• eventuali periferiche di stampa e lettura

Flussi minimi del bridge

• GET /devices: elenco periferiche disponibili
• POST /scan: acquisizione scanner o lettore QR
• POST /nfc/read: lettura tag
• POST /nfc/write: scrittura XML lite su tag NFC
• POST /label/print: stampa etichetta con payload deciso dalla webapp

Nota tecnica

La webapp resta il pannello operativo. Il bridge locale si occupa della parte hardware e non diventa mai il sistema autorevole dei dati.

Gruppo F - Passaggio consegne tra amministratori

Obiettivo

Preparare una procedura standard di uscita ed entrata che usa documenti umani piu un QR master/XML per ricostruire il contesto senza lavoro manuale ridondante.

Flusso proposto

1. L'amministratore seleziona i faldoni, le cartelline e i documenti da consegnare.
2. Il sistema produce un foglio consegna umano stampabile.
3. In coda al foglio viene aggiunto un QR master con XML di riepilogo.
4. L'amministratore ricevente scansiona il QR master.
5. Il sistema propone import, ricostruzione dell'albero archivistico e collegamento ai record gia esistenti.

Contenuto minimo del QR master di consegna

• identificativo passaggio
• amministratore uscente
• amministratore entrante se noto
• stabile o gruppo stabili
• elenco contenitori e codici master
• schema di classificazione usato
• checksum generale

Gruppo G - HUB Assemblee dentro Stabili

Obiettivo

Creare un hub operativo unico per ogni stabile che gestisca l'intero ciclo assembleare, dalla convocazione al verbale e alle attivita post-assemblea.

Base dati gia presente

• Assemblea
• OrdineGiorno
• Convocazione
• PresenzaAssemblea
• Verbale
• DocumentoAssemblea

Cosa deve contenere l'HUB

• elenco assemblee per stabile in ordine cronologico
• prima e seconda convocazione
• allegati inviati per convocazione
• verifica convocazioni prodotte e spedite
• gestione destinatari email, PEC, RR e futuri provider postalizzazione
• stato spedizione per ciascun destinatario
• tabella millesimale di riferimento per assemblea o per singolo punto
• gestione punti all'ordine del giorno
• allegati e conteggi collegati a ogni punto OdG
• norma o criterio di votazione associato al punto
• gestione verbale e relativo invio
• generazione ticket operativi derivati dalla delibera
• registrazione presenza diretta o per delega anche via QR del partecipante

Slice 1 consigliata per l'HUB

1. Pagina indice Assemblee Hub nel gruppo menu Stabile.
2. Lista assemblee filtrabile per stabile, stato e data.
3. Scheda assemblea con le due convocazioni e pannello allegati.
4. Sezione destinatari convocazione con stato invio e canale.
5. Sezione OdG con collegamento ad allegati e conti.

Slice 2

1. Gestione presenze, deleghe e quorum.
2. Regole di voto per punto OdG.
3. Verbale, invio verbale e storico esiti.
4. Creazione ticket da delibera.

Slice 3

1. QR partecipante per check-in.
2. Import automatico deleghe.
3. Integrazione con postalizzazione online.
4. Collegamento forte con archivio documentale e codice master.

Gruppo H - Area pubblica normativa e knowledge base

Obiettivo

Aprire sul sito pubblico una sezione informativa sulla gestione condominiale, con contenuti normativi referenziati e governati da ruoli editoriali distinti dall'area amministrativa riservata.

Contenuti previsti

• articoli di riferimento
• commi e leggi collegate
• note applicative
• collegamenti a casi pratici o domande frequenti
• possibile forum o blog esterno federato ma non mescolato alla parte riservata

Governance desiderata

• redazione affidata a un avvocato o associazione
• pubblicazione separata dai permessi amministrativi ordinari
• workflow bozza, revisione, pubblicazione

Gruppo I - Bacheca amministratore e raccolta voti preliminari

Obiettivo

Consentire all'amministratore di pubblicare comunicazioni e aprire una raccolta di consensi o indicazioni prima dell'assemblea.

Funzioni richieste

• invio email con accesso alla bacheca
• notizia pubblica o riservata per stabile o gruppo utenti
• allegati
• stato lettura
• richiesta approvazione o voto preliminare
• tracciamento dei riscontri prima dell'assemblea
• collegamento eventuale a un punto OdG futuro

Gruppo L - Catalogo supporti e Amazon

• Ogni supporto fisico scelto dall'utente deve poter avere il pulsante Amazon.
• Il link Amazon deve arrivare dal catalogo prodotti gestito dal super admin.
• L'archivio fisico non deve duplicare il catalogo: deve consumare il dato gia scelto.

Gruppo M - Catalogo fornitore, Amazon e TecnoRepair

Amazon prodotti fornitore

• La UI catalogo fornitore esiste gia in fornitore/prodotti.
• Il servizio Creators API esiste gia, ma per usarlo davvero su staging servono le variabili ambiente AMAZON_CREATORS_* valorizzate sul nodo.
• Variabili richieste per chiudere il setup:
• AMAZON_CREATORS_ENABLED=true
• AMAZON_CREATORS_API_BASE_URL
• AMAZON_CREATORS_TOKEN_URL
• AMAZON_CREATORS_CREDENTIAL_ID
• AMAZON_CREATORS_CREDENTIAL_SECRET
• AMAZON_CREATORS_SEARCH_PATH
• AMAZON_CREATORS_GET_ITEMS_PATH
• Variabili opzionali ma consigliate:
• AMAZON_MARKETPLACE
• AMAZON_REFERRAL_TAG
• Obiettivo operativo: cercare, salvare e aggiornare candidati Amazon direttamente nel catalogo fornitore interno.

TecnoRepair e scheda riparazione

• Esiste gia una base import TecnoRepair e una sincronizzazione prodotto catalogo da MDB.
• Da completare il collegamento con la singola scheda riparazione per gestire meglio stato chiusura e riconsegna.
• Campi legacy da intercettare o mappare esplicitamente:
• isRiparato
• isRiconsegnato
• Tmarche
• Tapparecchi
• Cod_Marca come chiave di legame fra marca e apparecchio
• Obiettivo funzionale:
• marcare chiusa la singola riparazione quando il legacy la considera riparata
• distinguere chiusa da riconsegnata
• usare Tmarche e Tapparecchi per costruire o normalizzare marchio e modello nel catalogo prodotti
• collegare il prodotto TecnoRepair alla scheda di lavorazione e agli eventuali candidati Amazon equivalenti o sostitutivi

Primo ordine di esecuzione consigliato

1. Tabella unica di classificazione archivio e normalizzazione dei tre campi attuali.
2. XML schema lite e full con checksum e codice master.
3. Stampa QR coerente con il nuovo schema.
4. Lettura QR e collegamento ai record gia esistenti.
5. Hub Assemblee slice 1 dentro il gruppo Stabile.
6. Bridge locale NFC e scrittura NTAG215.
7. Foglio passaggio consegne con QR master.
8. Area pubblica normativa e bacheca.

Backlog successivo

1. Foto ubicazione finale come nel ticket.
2. Vista modifica e ristampa dalle ultime etichette.
3. Blade separata per file singolo e per raccolta fogli.
4. Conteggio pagine persistente su database.
5. Impostazioni globali amministratore per formato data e convenzioni etichetta.
6. Integrazione completa col bridge locale di comunicazione.
7. QR multilivello per scatole o interi lotti documentali.
8. Import ed export XML firmato o verificato con checksum forte.
9. Collegamento tra verbali assemblea, delibere e ticket generati.