Audit Easy Builder e documentale - 2026-08-05¶

Esito sintetico¶

Il documentale SafeOps e' gia' il perimetro corretto per documenti e allegati. Compila v3 non deve creare un archivio parallelo.

L'audit conferma tre capability distinte:

foto domanda: media operativi della compilazione, salvati dal runtime v3
document check: verifica documenti cliente gia' presenti nel documentale
allegati documentali: file singoli/multipli che devono restare nel documentale, non dentro il payload della domanda

Stato attuale¶

Foto domanda¶

Le foto sono gestite dal runtime Compila v3.

Contratto attuale: - la domanda dichiara un campo immagine nei detail_fields - v3 applica limite, cattura webcam/caricamento, parcheggio, cestino e riferimenti locali - il backend salva i file tramite storage documentale/media esistente

Questa parte e' operativa e non va trasformata in allegato documentale generico.

Document check¶

Easy Builder salva la configurazione document_check. Compila v3 la legge dalla meta domanda e interroga lo status endpoint.

Parametri supportati: - categoria documentale - categoria per nome/codice - ultimo caricato o ultimo valido - giorni warning - giorni tolleranza scadenza - policy senza scadenza

Il dato verificato resta il documento cliente nel documentale.

Allegati singoli/multipli¶

Gli allegati esistono gia' nel documentale. La parte ancora da modellare in Easy Builder/v3 e' il collegamento dichiarativo tra domanda e allegato richiesto.

La strada corretta e': - Easy Builder dichiara una attachment_policy - v3 mostra lo stato e apre/carica usando il documentale - il file resta documento/allegato documentale - la risposta della domanda salva solo riferimento, stato e note operative

Regola architetturale¶

Non salvare allegati reali dentro legacy_dynamic_answer.

La risposta puo' contenere solo: - id documento/allegato - categoria - stato - note - timestamp - autore

Il contenuto binario e la governance restano nel documentale.

AI¶

L'AI ha senso come assistente, non come certificatore.

Applicazione consigliata a piccoli passi:

Foto domanda: suggerire evidenza, misura, criticita' e qualita' foto.
Document check: spiegare perche' un documento risulta mancante, scaduto o dubbio.
Allegati: proporre categoria e coerenza col requisito Easy Builder.

Ogni proposta AI deve essere confermata o corretta dal tecnico.

Primo contratto implementato¶

E' stata aggiunta una capability dichiarativa attachment_policy in Easy Builder.

La UI minima consente di impostare:

tipo: singolo o multiplo
categoria documentale obbligatoria o consigliata
obbligatorio si/no
max file
formati ammessi
descrizione operativa per il tecnico

Il backend conserva il dato nel payload Easy Builder e lo materializza nella meta della domanda runtime. Compila v3 espone il flag attachment_policy_enabled e mostra il badge Allegati sulla domanda.

Compila v3 legge inoltre lo stato allegati in modalita' read-only:

usa la policy della domanda
cerca documenti e allegati gia' presenti nel documentale cliente
filtra per categoria o nome categoria se indicati
mostra i file trovati con link apertura/download

Compila v3 consente anche di collegare un documento/allegato esistente alla domanda. Il collegamento salva solo riferimenti nel payload risposta:

document_id
attachment_id
nome file
categorie
timestamp
dispositivo

La rimozione in v3 rimuove solo il riferimento dalla domanda. Non cancella il file e non scollega l'allegato dal documento cliente.

Compila v3 consente inoltre il caricamento diretto dal blocco Allegati documentali:

il file viene validato con le regole upload del documentale;
viene creato un nuovo Documento collegato al cliente del RAS;
se la policy indica una categoria, il documento viene categorizzato;
viene creata la versione iniziale documentale;
la domanda salva solo il riferimento al nuovo documento;
max_files viene rispettato sia lato UI sia lato endpoint.

Il payload verso il motore di stampa esterno ora conserva attachment_refs per domanda. Easy Builder puo' decidere dalla checklist:

se includere il collegamento nell'appendice documentale
se mostrare il riferimento breve sotto la domanda
se l'appendice e' solo indice o indice con metadati

Il payload stampa genera:

document_appendix
attachment_appendix_refs sulla domanda
codici stabili A-001, A-002, ...

La stampa RAS genera l'appendice documentale come PDF separato:

nome file appendice_documentale.pdf
salvato tra gli allegati/output del fascicolo come le schede verticali
il PDF principale resta leggero e mostra solo i riferimenti brevi quando abilitati
i file originali restano nel documentale SafeOps

Se un allegato documentale e' obbligatorio ma non risulta collegato:

non viene inserita una riga vuota nell'appendice
la domanda compilata porta lo stato attachment_required_missing
nei dettagli stampa compare Allegato documentale obbligatorio: mancante
l'audit stampa emette il warning attachment_required_missing

L'audit di stampa conta:

attachment_refs_count
questions_with_attachment_refs_count
attachment_required_missing_count
document_appendix_count

Prossimo passo consigliato¶

Raffinare la card allegati della domanda:

preview piu' chiara del documento appena caricato;
eventuale scadenza/data documento quando richiesta dalla categoria;
gestione allegati multipli dentro un documento master se il modello operativo lo richiede.

Questo mantiene compatibilita' con i vecchi RAS e prepara v3 come gestore dinamico generico.