netgescon-master/docs/02-architettura-laravel/specifiche/Gestione DOCUMENTI.txt

GESTIONE DOCUMENTI 


1. Cosa Avevamo Previsto di Archiviare
L'obiettivo era creare un sistema in grado di gestire qualsiasi tipo di file rilevante per la gestione condominiale, tra cui:

Fatture Elettroniche (XML): Questo era il punto di partenza. Non solo archiviare il file, ma anche estrarne i dati per automatizzare la contabilità.
Fatture Passive (PDF): Le classiche fatture in PDF.
Verbali di Assemblea (PDF/DOCX): Per avere uno storico consultabile.
Contratti di Fornitura (PDF): Contratti con fornitori, assicurazioni, etc.
Preventivi (PDF): Preventivi ricevuti e inviati.
Documenti di Identità: Dei soggetti o dei legali rappresentanti.
Foto e Immagini: Relative a sinistri, lavori, o per documentare lo stato di un immobile.
2. Come Avevamo Previsto di Gestirli: L'Architettura
La soluzione che avevamo definito è basata su un concetto chiave di Laravel: le Relazioni Polimorfiche.

Invece di creare una tabella documenti_stabile, una documenti_fornitore, etc., avevamo pianificato di creare una sola tabella documenti centrale e di renderla "collegabile" a qualsiasi altra entità del sistema.

Nuova Tabella: documenti Scopo: Un archivio unico per tutti i file, con un sistema di collegamento intelligente.

Nome Campo	Tipo Dati	Chiave/Indice	Note
id	BIGINT (PK)		Chiave primaria.
documentable_id	BIGINT	INDEX	L'ID del modello a cui è collegato (es. id_stabile, id_fornitore).
documentable_type	VARCHAR(255)	INDEX	La classe del modello (es. App\Models\Stabile). Questo è il cuore della polimorfia.
nome_file	VARCHAR(255)		Nome originale del file caricato.
path_file	VARCHAR(255)		Percorso del file nello storage di Laravel.
tipo_documento	VARCHAR(255)		Categoria (es. 'Fattura', 'Verbale', 'Contratto', 'Altro').
descrizione	TEXT		Note opzionali sul documento.
created_at, updated_at	TIMESTAMP		Timestamps standard.
3. Il Piano di Lavoro per il Team
Per rendere questo sistema funzionante, ecco i passaggi che il team di sviluppo deve seguire:

Creare la Migration: Scrivere il file di migrazione per la tabella documenti come descritta sopra, assicurandosi di definire i campi documentable_id e documentable_type.

Creare il Modello Documento:

Creare il modello App\Models\Documento.php.
All'interno del modello, definire la relazione polimorfica inversa:
php
public function documentable()
{
    return $this->morphTo();
}
Aggiornare i Modelli Esistenti:

In ogni modello che può avere documenti (es. Stabile.php, Fornitore.php, Ticket.php, etc.), aggiungere la relazione polimorfica "in avanti":
php
// In Stabile.php, Fornitore.php, etc.
public function documenti()
{
    return $this->morphMany('App\Models\Documento', 'documentable');
}
Questo permetterà di fare chiamate intuitive come $stabile->documenti per ottenere tutti i file associati a quello stabile.
Sviluppare il DocumentoController:

Creare un controller per gestire la logica di upload, visualizzazione e cancellazione dei file.
Il metodo store dovrà:
Validare il file caricato.
Salvare il file nello storage di Laravel (es. storage/app/public/documenti/{stabile_id}/...).
Creare un nuovo record nella tabella documenti, popolando documentable_id e documentable_type con i dati del modello a cui si sta allegando il file.
Integrare l'Interfaccia Utente:

Nella pagina di dettaglio di ogni entità (es. admin.stabili.show), aggiungere un nuovo TAB "Documenti".
Questo tab conterrà un form per l'upload di nuovi file e una tabella che elenca tutti i documenti già associati a quell'entità, con pulsanti per il download e la cancellazione.
Questo approccio è estremamente potente e scalabile. Ci permette di avere un sistema di gestione documentale centralizzato, pulito e facilmente estendibile a qualsiasi nuova funzionalità che aggiungeremo in futuro.



L'idea di base è smettere di pensare al documento come a un semplice file, ma come a un oggetto digitale composto da due parti: il file originale e i metadati associati.

1. Il Concetto Fondamentale: Metadati + File
Ogni documento che carichi nel sistema dovrebbe avere una "carta d'identità" nel database, separata dal file fisico.

Tabella documenti nel database: Questa tabella non contiene il file, ma le informazioni sul file.
id (PK)
protocollo (es. 2025-0001)
data_protocollo
tipo_documento (Fattura, Contratto, Estratto Conto, Verbale...)
stabile_id (FK alla tabella stabili)
fornitore_id (FK alla tabella fornitori, se applicabile)
esercizio_contabile_id (FK all'esercizio di riferimento)
descrizione
importo (se applicabile)
data_documento
percorso_file (il path dove il file è salvato, es. documenti/2025/fattura_xyz.pdf)
testo_estratto_ocr (un campo TEXT dove salveremo il contenuto testuale del documento)

Storage (Archiviazione): I file fisici (PDF, XML, JPG) vengono salvati in una cartella specifica sul server o, ancora meglio, su un servizio di cloud storage come Amazon S3, Google Cloud Storage o DigitalOcean Spaces. Laravel, con il suo sistema di Filesystem, rende trasparente l'uso di questi servizi.

2. Protocollo Intelligente e Automazione dell'Acquisizione
Quando carichi un documento, il sistema deve fare molto più che salvarlo.
Fatture Elettroniche (XML): Questa è la tua più grande opportunità di automazione. Essendo file XML, sono dati strutturati. Il tuo sistema dovrebbe:
Leggere l'XML: Estrarre automaticamente Fornitore (Partita IVA), Data, Numero Fattura, Importo Totale e descrizione delle righe.
Compilare i Metadati: Pre-compilare la "carta d'identità" del documento. L'utente deve solo verificare e confermare.
Archiviazione: Salvare sia il file XML originale che una versione PDF di cortesia (che puoi generare o che è già allegata).
PDF e Immagini (Contratti, Ricevute, ecc.): Qui entra in gioco la tecnologia OCR (Optical Character Recognition).
Coda di Elaborazione: Quando l'utente carica un PDF o un'immagine, Laravel dovrebbe mettere il file in una coda di elaborazione (Laravel Queues). Questo evita che l'utente debba attendere.

Processo OCR: Un processo in background analizza il file. Hai due strade:
Open Source: Usare una libreria come Tesseract. Richiede più configurazione ma è gratuita.
Servizi Cloud (Consigliato): Usare API come Google Vision AI o Amazon Textract. Sono incredibilmente potenti (Textract è specializzato nel riconoscere tabelle e dati da fatture) e paghi solo per quello che usi.
Salvataggio del Testo: Il testo estratto dall'OCR viene salvato nel campo testo_estratto_ocr della tabella documenti.

3. Organizzazione Flessibile e Ricerca Potente
Etichette (Tags) invece di Categorie Rigide: Oltre al tipo_documento, permetti all'utente di applicare delle etichette (tags) ai documenti. Una singola fattura potrebbe essere etichettata come manutenzione, ascensore, straordinaria. Questo rende la ricerca e il raggruppamento molto più flessibili.

Collegamento tra Documenti: Crea la possibilità di collegare i documenti tra loro.
Un verbale di assemblea può essere collegato a un contratto d'appalto.
Un contratto può essere collegato a tutte le fatture emesse da quel fornitore.
Una fattura può essere collegata al movimento dell'estratto conto che la salda.
Ricerca Full-Text (La Funzionalità Killer): Ora che hai il testo di ogni documento nel database (o estratto dall'XML o dall'OCR), puoi implementare una ricerca potentissima.
Laravel Scout è lo strumento perfetto per questo. È un pacchetto ufficiale di Laravel che si integra con motori di ricerca come MeiliSearch (leggero e velocissimo) o Elasticsearch.
Quando un utente cerca "sostituzione pompa", Scout cercherà quella frase non solo nei metadati (descrizione, tipo), ma anche all'interno di tutti i documenti, inclusi i PDF scansionati, restituendo risultati istantanei.
Questo approccio trasforma un semplice archivio di file in un vero e proprio centro di conoscenza intelligente per l'amministratore, dove trovare qualsiasi informazione è questione di secondi.