Manuale Utente Easy Builder¶

Questo manuale serve a chi deve costruire checklist e moduli nella GUI Easy Builder senza entrare nello schema tecnico avanzato.

L'idea di fondo e' semplice: invece di lavorare direttamente su JSON, metadati e configurazioni complesse, lavori in modo guidato con una struttura chiara: - Scheda principale - Sottoscheda - Domanda

Flusso operativo Easy Builder

In breve¶

Se devi solo creare o aggiornare una checklist, resta in Easy Builder.

Il percorso normale e':

scegli il tipo di builder;
controlla preset e libreria;
crea schede, sottoschede e domande;
prova la preview;
pubblica solo quando la preview e' coerente.

Non partire dallo schema JSON se la modifica si puo' fare dalla schermata guidata.

A cosa serve davvero¶

Easy Builder serve quando vuoi creare o aggiornare una checklist in modo ordinato e governato.

E' pensato per chi deve: - costruire checklist RAS, DVR o checklist standard - lavorare per schede e sottoschede - riusare domande gia' pronte - vedere una preview reale prima di pubblicare

Non e' pensato per fare configurazioni tecniche molto particolari. Per quei casi esiste il builder esperto.

Chi lo usa¶

Il profilo tipico e': - admin tenant

L'uso corretto e' questo: - costruisci il contenuto in Easy Builder - fai le verifiche - pubblichi solo quando la bozza e' pronta

Dove si apre¶

Route principali: - /easy-builder/ - /easy-builder/new?builder_type=ras - /easy-builder/import-legacy?builder_type=ras - /easy-builder/import-builder?builder_type=ras

Nella lista builder trovi normalmente queste azioni:

Builder: apre la modifica guidata;
Preview: apre la prova nel runtime di compilazione;
Schema: apre il livello avanzato;
Export: scarica il builder;
Pubblica: rende utilizzabile la versione pronta;
Duplica: crea una copia di lavoro.

Screenshot consigliato quando disponibile: lista Easy Builder con filtro tipo, pulsante Nuovo Builder e azioni di riga.

Prima di iniziare: tre concetti chiave¶

1. Builder¶

Un builder e' il modello della checklist che stai costruendo.

Ogni builder ha uno stato: - draft: lo puoi modificare - published: e' pubblicato e pronto all'uso - obsolete: resta in storico ma non e' piu' il riferimento corrente

2. Gerarchia¶

La struttura e' sempre questa: - una Scheda principale contiene una o piu' Sottoschede - ogni Sottoscheda contiene le Domande

Le domande non vanno direttamente nella scheda principale.

3. Preset¶

Ogni domanda usa un preset.

Il preset decide come funziona quella domanda. Per esempio: - risposta Si/No/In attesa - note - immagini - controllo documento

Tu in genere scegli il preset, non devi costruirlo da zero.

Il flusso corretto di lavoro¶

Se vuoi lavorare bene, usa sempre questo ordine.

Procedura rapida da ticket¶

Quando arriva una richiesta di modifica checklist, lavora cosi':

apri il builder in draft o duplica quello pubblicato;
identifica la scheda e la sottoscheda interessata;
applica la modifica minima richiesta;
controlla preset e semantica risposta v3 della domanda toccata;
apri la preview della domanda;
apri la preview compila;
pubblica solo se il comportamento e' coerente.

Se durante il controllo scopri che la richiesta non rientra nei preset disponibili, non forzare la modifica: segnala che serve valutazione Expert Builder o nuovo preset.

1. Crea la bozza¶

Apri Easy Builder
clicca Nuovo
scegli il tipo builder:
RAS
DVR
Checklist
inserisci nome e versione
salva

Da qui in avanti lavori sempre su una bozza.

2. Costruisci la struttura¶

Dentro il builder: 1. aggiungi le schede principali 2. dentro ogni scheda aggiungi le sottoschede 3. dentro ogni sottoscheda aggiungi le domande

Il modo giusto di pensarlo e': - prima la struttura - poi il contenuto

Non conviene partire subito con tante domande se la struttura non e' ancora chiara.

3. Aggiungi le domande¶

Puoi farlo in tre modi: - una domanda alla volta - inserimento massivo - dalla libreria domande

Se la checklist e' lunga, spesso il modo migliore e': - creare prima la sottoscheda - incollare un blocco di domande - poi rifinire i preset

4. Scegli il preset giusto¶

Ogni domanda deve avere il preset corretto.

I casi piu' comuni sono: - domanda standard Si / No / In attesa - domanda con immagini - domanda con document_check

Se non sai quale preset usare, parti dal piu' semplice e poi verifica in preview.

Nota importante: - le immagini della domanda sono foto operative della compilazione - il document_check controlla documenti gia' presenti nel documentale - gli allegati singoli/multipli devono restare nel documentale e non diventare un archivio parallelo dentro Compila v3

Per gli allegati documentali:

abilita Allegati documentali solo quando la domanda richiede un file del documentale;
usa Obbligatorio se la domanda non deve essere considerata completa senza documento;
usa In appendice se quel documento deve comparire nell'appendice documentale separata;
usa Ref. nel RAS se nel RAS principale vuoi mostrare il codice breve del documento collegato;
se il documento obbligatorio manca, la stampa segnala la mancanza sulla domanda e non crea una riga vuota nell'appendice.

5. Imposta la semantica della risposta¶

Per le checklist RAS e per il Compila v3 e' importante distinguere la risposta dalla valutazione tecnica.

Esempio: - domanda: Sono presenti aree verdi comuni esterne? - risposta: No - significato: puo' essere una risposta neutra, non una non conformita'

Nel riquadro della domanda trovi Semantica risposta v3: - Neutra / inventario: la risposta descrive una presenza/assenza e non crea NC da sola - Requisito: la domanda verifica un requisito - Pericolo: la domanda rileva una condizione potenzialmente critica - Personalizzata: usala solo se imposti regole esplicite

I campi NC se, OK se e In attesa se accettano valori separati da virgola.

Regola pratica: - se No non significa automaticamente problema, scegli Neutra / inventario e lascia NC se vuoto - se una risposta deve indicare NC, scrivila esplicitamente in NC se - non usare mai la regola mentale No = NC

Esempi rapidi:

Caso	Semantica consigliata	`NC se`
Presenza di un elemento da censire	`Neutra / inventario`	vuoto
Requisito obbligatorio	`Requisito`	risposta che viola il requisito
Pericolo o criticita'	`Pericolo`	risposta che indica il pericolo

Screenshot consigliato quando disponibile: riga domanda con campi Semantica risposta v3, NC se, OK se, In attesa se.

6. Riordina¶

Puoi spostare: - schede - sottoschede - domande

Il drag&drop serve proprio a sistemare la struttura senza rifarla da capo.

Usalo soprattutto quando: - hai creato una checklist lunga - hai inserito domande in blocco - ti accorgi che una domanda starebbe meglio in un'altra sottoscheda

7. Controlla la preview¶

Prima di pubblicare, fermati sempre qui.

Hai due livelli di preview:

Preview preset¶

Ti fa vedere come si comporta la singola domanda: - versione standard - versione In attesa - immagini - note - regole documentali

Preview compila¶

Ti apre il draft nel runtime reale di compilazione.

Questa e' la prova piu' importante, perche' ti fa vedere: - come appare davvero la checklist - come si comportano le risposte - come si comportano immagini e note - come si comporta il document_check

La preview usa una sandbox: - non sporca i dati ufficiali - puoi fare prove - puoi caricare immagini di test

8. Pubblica¶

Pubblica solo quando: - la struttura e' chiara - i preset sono giusti - la preview compila e' coerente

Se ci sono errori strutturali, il sistema blocca la pubblicazione.

Le funzioni che userai di piu'¶

Schede, sottoschede e domande¶

Sono la base di tutto.

Regola pratica: - la scheda principale e' il grande argomento - la sottoscheda e' il gruppo omogeneo - la domanda e' il controllo specifico

Esempio: - Scheda: Impianto elettrico - Sottoscheda: Quadri - Domanda: Il quadro e' identificato correttamente?

Libreria domande¶

La libreria ti evita di riscrivere sempre le stesse domande.

Usala quando hai controlli che tornano spesso, per esempio: - targhetta identificativa - accessibilita' - presenza documentazione - immagini obbligatorie

La libreria ti permette di: - salvare una domanda utile - riutilizzarla in altri builder - organizzarla con tag - disattivarla se non serve piu'

Buona regola: - se una domanda la riscrivi per la terza volta, probabilmente deve stare in libreria

Prompt Builder¶

Il Prompt Builder ti aiuta a costruire o modificare il builder scrivendo testo.

Non sostituisce il controllo umano: accelera il lavoro.

Il flusso corretto e': 1. scrivi il testo 2. il sistema lo interpreta 3. vedi preview e diff 4. confermi l'applicazione

Quando usarlo¶

Usalo soprattutto quando: - hai molte domande simili - devi costruire una checklist lunga - vuoi aggiungere blocchi interi di struttura - vuoi modificare tante domande insieme

Esempio semplice¶

AGGIUNGI SCHEDA: Impianto elettrico
AGGIUNGI SOTTOSCHEDA: Impianto elettrico > Quadri
AGGIUNGI DOMANDE IN: Impianto elettrico > Quadri
- Il quadro e' identificato? | tipo: si_no
- Il quadro e' conforme? | tipo: si_no_in_attesa | note: si

Esempio in linguaggio piu' naturale¶

scheda Impianto elettrico
sottoscheda Quadri
domanda Il quadro e' identificato?
domanda Il quadro e' conforme?

Se il prompt e' lungo, e' meglio lavorare a blocchi piccoli invece di fare tutto in una volta.

Tipi domanda piu' comuni¶

Domanda RAS standard¶

E' il caso piu' frequente.

Risposte: - Si - No - In attesa

Può includere: - note - immagini - dettagli standard

Document check¶

Questa domanda controlla la presenza e la validita' di un documento nel documentale.

E' utile per casi come: - certificazioni - documenti obbligatori - documenti con scadenza

Quando la usi, devi controllare bene: - categoria - criterio di selezione - warning scadenza - tolleranza

La cosa migliore e' sempre provarla in Preview compila.

Screenshot consigliato quando disponibile: domanda document_check con categoria documento, criterio, gestione senza scadenza, warning e tolleranza.

In attesa¶

Alcuni preset hanno una gestione speciale di In attesa.

Tipicamente: - la risposta base resta In attesa - si apre solo il campo note

Per questo la preview della domanda mostra sempre anche il caso In attesa.

Import e export¶

Funzioni disponibili: - import builder da JSON - import da template dynamic evoluto - export builder

Queste funzioni servono soprattutto per: - backup - riuso - copia tra ambienti o versioni

Errori piu' comuni¶

1. Struttura confusa¶

Succede quando si inseriscono tante domande senza aver deciso bene le sottoschede.

Rimedio: - fermati - sistema la struttura - poi riprendi le domande

2. Preset sbagliato¶

Succede quando la domanda funziona in modo diverso da come ti aspettavi.

Rimedio: - controlla il preset - guarda la preview domanda - prova in preview compila

3. Troppa duplicazione¶

Succede quando si continuano a riscrivere domande gia' esistenti.

Rimedio: - usa la libreria

4. Uso troppo libero del Prompt Builder¶

Succede quando si scrive un prompt troppo lungo o ambiguo.

Rimedio: - spezza il lavoro - usa comandi piccoli - controlla il diff prima dell'apply

5. Pubblicazione troppo veloce¶

Succede quando si pubblica senza fare preview reale.

Rimedio: - fai sempre almeno una prova in Preview compila

Buone pratiche semplici¶

Parti sempre da una bozza piccola e chiara.
Costruisci prima la struttura, poi il dettaglio.
Usa la libreria domande per i controlli ripetitivi.
Usa il Prompt Builder a blocchi, non in modo caotico.
Pubblica solo dopo una preview reale.

Checklist finale prima della pubblicazione¶

Prima di cliccare Pubblica, controlla sempre:

le schede sono giuste?
le sottoschede sono complete?
ogni domanda ha il preset corretto?
le domande inventario hanno Neutra / inventario?
NC se e' compilato solo quando una risposta deve davvero produrre non conformita'?
la preview domanda e' coerente?
la preview compila e' corretta?
immagini e document check funzionano come previsto?

Se la risposta e' si, allora la bozza e' pronta per diventare pubblica.