Manuale Completo Easy / Expert Builder¶

Questo documento raccoglie in un unico percorso tutto quello che serve per capire, usare, governare e mantenere l'ecosistema: - Easy Builder - Prompt Builder - Expert Builder

L'obiettivo e' semplice: - dare una visione unica del sistema - spiegare i diversi livelli di utilizzo - evitare che chi legge debba rincorrere informazioni sparse in piu' documenti

Questo manuale e' pensato anche come base per un PDF completo.

Come leggere questo manuale¶

Non tutti devono leggere tutto.

Se sei: - operatore o utente pratico: parti dal capitolo Livello Operatore - admin tenant: parti dal capitolo Livello Admin Tenant - super admin o figura di governance: leggi Livello Governance - tecnico/manutentore: leggi anche Livello Tecnico

Mappa rapida¶

Il sistema ha tre livelli principali.

1. Easy Builder¶

E' il percorso normale.

Serve per: - costruire checklist - usare schede, sottoschede e domande - scegliere preset - usare prompt builder - fare preview - pubblicare

2. Prompt Builder¶

E' un acceleratore dell'easy.

Serve per: - scrivere blocchi di struttura - aggiungere molte domande - modificare checklist lunghe - lavorare piu' velocemente mantenendo il controllo

3. Expert Builder¶

E' il percorso avanzato.

Serve per: - casi fuori standard - manutenzione avanzata - interventi tecnici sullo schema - compatibilita' legacy o custom particolari

La regola da ricordare e' questa: - Easy e' il percorso normale - Expert e' il percorso controllato di eccezione

Parte 1. Visione generale¶

Perche' esiste questo sistema¶

Nel progetto c'era un bisogno chiaro: - costruire checklist e moduli anche complessi - mantenerli compatibili con il runtime compila - evitare che chi crea contenuti debba lavorare direttamente su configurazioni tecniche

Per questo e' stato costruito un layer guidato sopra il motore dynamic esistente.

In pratica: - il motore finale e' sempre quello gia' in uso - cambia il modo con cui il template viene costruito e governato

Idea chiave¶

L'idea di fondo e' questa: - chi costruisce contenuto lavora in Easy Builder - chi governa le regole lavora su preset, librerie e cataloghi - chi deve fare manutenzione avanzata ha a disposizione Expert Builder

Questo permette di avere: - velocita' - ordine - compatibilita' - meno errori

Screenshot consigliato¶

Lista Easy Builder
Evidenziare: nuovo builder, stato bozza/pubblicato, accesso editor

Parte 2. Livello Operatore¶

Questa parte e' per chi usa soprattutto il Prompt Builder o lavora in modo operativo sulla creazione delle checklist.

Cosa deve sapere un operatore¶

Un operatore non deve conoscere lo schema tecnico.

Gli basta capire: - come e' fatta una checklist - come scrivere i prompt in modo chiaro - come controllare il risultato prima di applicarlo

Come e' fatta una checklist¶

La struttura e' sempre questa: - Scheda principale - Sottoscheda - Domanda

Pensala cosi': - la scheda principale e' il grande argomento - la sottoscheda e' il gruppo omogeneo - la domanda e' il singolo controllo

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

Come usare il Prompt Builder¶

Il Prompt Builder non e' fatto per scrivere tutto in modo libero e confuso.

Funziona bene quando: - scrivi poco per volta - sei chiaro - usi nomi leggibili - controlli sempre preview e diff

Regola pratica¶

meglio 5 prompt piccoli che 1 prompt enorme

Due modi per scrivere¶

Linguaggio guidato¶

E' il modo piu' sicuro.

Esempio:

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

Linguaggio naturale assistito¶

E' il modo piu' comodo, ma va controllato meglio.

Esempio:

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

Come lavorare bene con checklist lunghe¶

Il modo corretto e' spezzare il lavoro:

crea le schede
crea le sottoschede
inserisci le domande di una sottoscheda per volta
applica le regole comuni
fai le correzioni finali

Errori da evitare¶

prompt troppo lunghi
riferimenti vaghi
troppe modifiche in un solo passaggio
apply senza leggere il diff

Screenshot consigliato¶

Schermata Prompt Builder
Evidenziare: area prompt, traduzione, diff, pulsante apply

Parte 3. Livello Admin Tenant¶

Questa parte e' per chi usa davvero il sistema per costruire e pubblicare checklist.

Cosa fa l'admin tenant¶

L'admin tenant lavora soprattutto in Easy Builder.

Il suo flusso corretto e': - crea una bozza - costruisce la struttura - aggiunge domande - sceglie i preset - verifica con preview - pubblica

1. Creazione builder¶

Quando crei un nuovo builder scegli: - tipo builder - nome - versione

Tipi tipici: - RAS - DVR - Checklist

2. Costruzione struttura¶

Dentro il builder: - aggiungi schede principali - dentro ogni scheda aggiungi sottoschede - dentro ogni sottoscheda aggiungi domande

Regola semplice: - prima struttura - poi contenuto

3. Domande e preset¶

Ogni domanda usa un preset.

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

Il preset evita di dover configurare tutto a mano.

4. Libreria domande¶

La libreria serve per riusare controlli che tornano spesso.

Va usata quando: - una domanda compare in molte checklist - vuoi standardizzare - vuoi lavorare piu' velocemente

5. Riordino e spostamenti¶

Con il drag&drop puoi: - riordinare schede - spostare sottoschede - spostare domande tra sottoschede

Questo e' utile soprattutto quando la checklist cresce e va rifinita.

6. Preview¶

Ci sono due livelli importanti.

Preview preset¶

Serve per capire come si comporta la singola domanda.

Preview compila¶

Serve per vedere il draft nel runtime reale.

Questa e' la verifica piu' importante prima della pubblicazione.

7. Pubblicazione¶

La pubblicazione va fatta solo dopo: - controllo struttura - controllo preset - prova Preview compila - controllo document check e immagini

Screenshot consigliati¶

Lista builder
Editor builder
Scelta preset
Preview domanda
Preview compila

Parte 4. Livello Governance¶

Questa parte e' per chi deve tenere ordine nel sistema.

La regola centrale¶

Easy Builder deve restare il percorso normale.

Expert Builder deve restare il percorso di eccezione.

Se questa regola salta, col tempo il sistema diventa difficile da mantenere.

Quando restare in Easy¶

Resti in Easy Builder quando: - il caso rientra nei preset - la struttura e' standard - il builder e' governabile - il caso e' ripetibile

Quando salire in Expert¶

Valuti Expert Builder quando: - il preset non basta davvero - la struttura non rientra nel modello easy - c'e' un caso tecnico o legacy speciale

Cosa fare quando un bisogno torna spesso¶

Se un caso torna molte volte, non deve restare una toppa in expert.

Deve diventare: - nuovo preset - nuova domanda di libreria - nuova capability easy

Governance minima¶

Da tenere sotto controllo: - tipi builder - preset - libreria domande - libreria prompt - audit

Screenshot consigliati¶

Catalogo tipi
Catalogo preset
Catalogo libreria
Audit

Parte 5. Livello Tecnico¶

Questa parte e' per chi mantiene il sistema.

Decisione architetturale¶

Easy Builder non introduce un runtime separato.

E' un layer di authoring sopra il motore dynamic esistente.

Questo vuol dire: - stesso schema finale - stesso pack compila - stessa gestione media - stessa tabella risposte

Componenti centrali¶

Backend¶

Classe principale: - EasyBuilderView

Responsabilita': - builder - preset - librerie - preview - audit - prompt builder - document check

Frontend editor¶

Template principali: - admin - edit - preview - prompt builder - cataloghi

Frontend runtime¶

Pack: - ras_pack_hotfix35_finalize_zip.html

Contratto risposta¶

Le risposte lato runtime usano un payload coerente con: - value - detail - images - image_meta

Questo contratto non va rotto.

Preview sandbox¶

La preview usa endpoint sandbox separati e non deve sporcare i dati ufficiali.

Questo e' uno dei punti piu' delicati da preservare.

Document check¶

Il document_check e': - una capability di preset - una capability backend - una capability frontend runtime

Il caso conditional_document_check e' ancora piu' delicato, perche' tocca: - regola domanda - rendering dinamico - refresh UI

Punti da non rompere¶

compatibilita' col pack compila
compatibilita' col payload risposta
compatibilita' con MinIO/object key
compatibilita' col motore dynamic legacy

Screenshot consigliati¶

Nessuno obbligatorio qui
Se serve, al massimo diagramma flusso dati o schema logico

Parte 6. Inventario del sistema¶

Oggi il sistema copre gia': - tipi builder multipli - preset - libreria domande - libreria prompt - prompt DSL - prompt naturale assistito - preview compila - upload immagini preview - document check - conditional document check - import/export builder - audit - validazione publish - versioning - stati builder

Questo significa che non stiamo piu' parlando di una singola funzionalita', ma di una vera piattaforma di authoring guidato.

Parte 7. Chiusura e collaudo¶

Prima di considerare chiuso il blocco Easy / Expert Builder vanno verificati: - flusso base builder - preset - libreria domande - prompt builder - preview compila - document check - conditional document check - validazioni publish - versioning - permessi - audit - documentazione

Per il collaudo finale usare: - docs/processo/easy_expert_builder_closure_checklist.md

Parte 8. Documenti collegati¶

Documenti di supporto: - manuale utente easy builder - guida prompt builder - manuale operativo easy vs expert - manuale tecnico easy builder - inventario funzionale - checklist finale di chiusura - strategia import legacy

Conclusione¶

Il valore di questo sistema non sta solo nelle funzioni che offre.

Sta nell'equilibrio che riesce a tenere tra: - semplicita' per chi costruisce contenuto - controllo per chi governa - compatibilita' per chi mantiene il runtime

Per questo il manuale completo va letto non come una raccolta di schermate, ma come una guida a un modo ordinato di lavorare.