Manuale Operativo Easy vs Expert Builder¶

Questo documento serve a chiarire una cosa molto importante per il progetto: oggi esistono due modi di costruire e mantenere le checklist, ma non hanno lo stesso ruolo.

Le due modalita' sono: - Easy Builder - Expert Builder / Schema Editor avanzato

Se questa distinzione non resta chiara, dopo poco succede sempre la stessa cosa: - si perde il controllo dei template - si creano varianti difficili da mantenere - non si capisce piu' dove fare le modifiche - ogni caso speciale finisce per diventare un'eccezione permanente

Per questo il documento non serve solo a descrivere strumenti. Serve a fissare una disciplina di lavoro.

L'idea di fondo¶

La regola corretta e' questa:

Easy Builder e' il percorso normale
Expert Builder e' il percorso controllato di eccezione

Questa e' la decisione piu' importante di tutto il sistema.

Non significa che l'editor esperto non serva. Significa che non deve diventare il modo standard di lavorare quando il caso potrebbe essere gestito in easy.

Perche' esistono due builder¶

Nel progetto convivono due esigenze reali.

La prima esigenza e' costruire checklist e moduli in modo rapido, leggibile e governato, senza chiedere all'utente di ragionare su: - JSON schema - metadati avanzati - type - meta - detail_fields - codici interni

La seconda esigenza e' non perdere la capacita' di intervenire tecnicamente quando il caso esce davvero dallo standard.

Da qui nascono i due livelli.

Che cos'e' Easy Builder¶

Easy Builder e' lo strumento con cui si dovrebbe lavorare quasi sempre.

Serve per: - creare checklist standard - costruire Schede > Sottoschede > Domande - usare preset governati - riusare librerie domande - usare il Prompt Builder - verificare il risultato con preview reali - pubblicare versioni ordinate

In pratica: - costruisce contenuto - applica regole gia' previste - riduce gli errori

Se il caso rientra in questo perimetro, non c'e' motivo di uscire dall'easy.

Che cos'e' Expert Builder¶

Expert Builder e' il livello avanzato.

Serve quando hai un caso che davvero non rientra nei binari standard. Per esempio: - una struttura non coperta dai preset - una logica speciale non esprimibile nell'easy - una configurazione legacy o tecnica che va mantenuta - manutenzione avanzata dello schema - debug o correzioni tecniche su template gia' esistenti

In pratica: - non e' lo strumento di produzione quotidiana - e' lo strumento di eccezione, manutenzione e controllo tecnico

Regola pratica da tenere fissa¶

Quando nasce una richiesta nuova, la domanda da farsi non e': - "dove riesco a farla piu' velocemente?"

La domanda giusta e': - "questa richiesta rientra nello standard o sta davvero fuori standard?"

Se rientra nello standard: - si usa Easy Builder

Se non rientra nello standard: - si valuta Expert Builder - oppure si decide se ha senso estendere l'easy

Questa seconda parte e' fondamentale.

Perche' se una richiesta torna spesso, non deve restare una toppa tecnica in expert. Deve diventare: - nuovo preset - nuova libreria domanda - nuova capability dell'easy

Chi usa cosa¶

Admin tenant¶

Il percorso corretto per l'admin tenant e': - creare e modificare i builder in Easy Builder - lavorare in bozza - usare preview - pubblicare

L'admin tenant non dovrebbe usare di default l'editor esperto.

Non perche' non sia capace, ma perche' il sistema va tenuto ordinato e governabile.

Super admin / tecnico avanzato¶

Il percorso corretto per il profilo tecnico avanzato e': - governare i tipi builder - governare i preset - governare le librerie comuni - intervenire in expert solo quando c'e' un motivo tecnico chiaro

Quindi il ruolo tecnico non e' "fare tutto in expert". Il ruolo tecnico e' mantenere l'ecosistema coerente.

Il flusso operativo corretto¶

Se vogliamo lavorare bene, il flusso da seguire e' sempre questo.

1. Si decide il perimetro¶

Prima di costruire, si capisce: - che tipo di builder serve - che struttura avra' - quali preset bastano - quali domande possono arrivare dalla libreria

Qui va presa la decisione piu' importante: - basta Easy Builder? - oppure c'e' davvero un'esigenza fuori standard?

2. Si costruisce in Easy¶

Se il caso e' standard, si lavora in easy: - schede - sottoschede - domande - preset - prompt builder - libreria

Questa e' la fase normale del lavoro.

3. Si verifica¶

Prima di pubblicare si controlla: - preview della domanda - preview del caso In attesa - preview compila - comportamento immagini - comportamento document_check

Questa fase non va saltata.

Perche' un builder apparentemente corretto in editor puo' comunque comportarsi male in compilazione se non viene provato davvero.

4. Si pubblica¶

La pubblicazione e' l'ultimo passaggio, non il primo.

Si pubblica solo quando: - la struttura e' giusta - i preset sono coerenti - le preview sono corrette - i controlli pre-pubblicazione non segnalano errori

5. Si apre una deviazione solo se serve¶

Se nella fase di costruzione o verifica emerge un limite reale, allora si decide: - passare a Expert Builder - oppure trasformare quel bisogno in una nuova capability easy

Questa decisione va presa con lucidita', non per comodita' momentanea.

Come capire se restare in Easy o salire in Expert¶

Questa e' la domanda pratica che conta davvero.

Resta in Easy quando¶

Resta in Easy Builder se devi: - creare checklist RAS, DVR o checklist standard - usare una struttura chiara a schede - configurare domande con preset gia' esistenti - riusare domande - usare prompt builder per velocizzare - fare preview e pubblicare

In breve: - se il caso e' ripetibile e governabile, deve stare in easy

Vai in Expert quando¶

Valuta Expert Builder solo quando: - il preset non basta davvero - la struttura richiesta non rientra nel modello easy - serve una personalizzazione tecnica non coperta - stai gestendo compatibilita' legacy o una correzione tecnica puntuale

In breve: - se stai uscendo dal modello standard, allora ha senso usare expert

Cosa non fare¶

Ci sono alcuni errori tipici che vanno evitati.

Non partire in expert per abitudine¶

E' l'errore piu' comune nei progetti che crescono.

Se parti in expert anche quando non serve: - perdi coerenza - aumenti manutenzione - rendi piu' difficile il lavoro degli altri

Non usare expert per evitare di pensare i preset¶

Se un bisogno torna spesso, la risposta corretta non e' "lo faccio ogni volta a mano".

La risposta corretta e': - creo un preset migliore - creo una domanda di libreria - estendo l'easy

Non mischiare easy ed expert senza una regola¶

Aprire un template easy e poi stravolgerlo in expert senza una decisione chiara e' una ricetta per la confusione.

Se succede, bisogna sapere: - perche' si esce dall'easy - cosa si sta aggiungendo - se quel caso restera' un'eccezione o diventera' uno standard

Non pubblicare senza preview reale¶

La preview compila non e' un extra. E' una parte del controllo di qualita'.

Governance minima da mantenere¶

Per non perdere il controllo, servono poche regole ma tenute bene.

Preset¶

I preset devono essere: - pochi - chiari - riconoscibili - davvero utili

Non serve creare dieci preset quasi uguali che differiscono solo per un dettaglio minimo.

Libreria domande¶

La libreria va usata per: - standardizzare i controlli ricorrenti - ridurre la duplicazione - velocizzare la costruzione

Se una domanda ricorre spesso, deve entrare in libreria.

Prompt Builder¶

Il Prompt Builder va trattato come acceleratore, non come sorgente incontrollata di configurazioni.

Il flusso corretto resta sempre: - scrivo - controllo la traduzione - guardo il diff - applico

Quattro casi tipici¶

Caso 1. Checklist standard¶

Situazione: - struttura ordinaria - preset gia' presenti

Scelta corretta: - Easy Builder

Caso 2. Checklist lunga con molto testo ripetitivo¶

Situazione: - molte domande simili - tanto lavoro di inserimento

Scelta corretta: - Easy Builder + Prompt Builder

Caso 3. Domande con verifica documentale¶

Situazione: - serve controllo su documentale e scadenza

Scelta corretta: - Easy Builder con preset document_check

Caso 4. Richiesta tecnica fuori standard¶

Situazione: - l'easy non riesce a rappresentare bene il caso

Scelta corretta: - prima si valuta se quella richiesta merita un'estensione del sistema - se no, si gestisce in Expert Builder

La regola finale da tenere a mente¶

Easy Builder deve essere il percorso normale, leggibile e governato.

Expert Builder deve restare il percorso controllato, usato quando serve davvero e con una ragione chiara.

Se questa disciplina resta ferma, il sistema cresce bene.

Se invece ogni eccezione viene risolta direttamente in expert senza criterio, col tempo si perde il controllo del prodotto.