Manuale Tecnico Easy Builder¶

Questo documento descrive l'architettura tecnica dell'ecosistema Easy Builder, Prompt Builder e delle estensioni collegate al runtime compila.

L'obiettivo non e' solo elencare componenti, ma chiarire tre cose: - come e' costruito il sistema - quali parti sono davvero centrali - dove si puo' intervenire senza rompere la compatibilita'

1. Decisione architetturale di base¶

La decisione piu' importante e' questa:

Easy Builder non introduce un secondo runtime.

E' un layer di authoring sopra il motore legacy dynamic / RAS gia' esistente.

Questo significa: - stesso formato schema del dynamic esistente - stessa tabella risposte - stesso pack frontend compila - stessa gestione media/MinIO

In altre parole: - cambia il modo di costruire il template - non cambia il motore finale che lo esegue

Questa e' la ragione per cui il sistema resta compatibile con tutto il flusso gia' in produzione.

2. Obiettivo tecnico¶

L'obiettivo del layer easy e' rendere costruibile e governabile un template dynamic senza chiedere all'utente di lavorare direttamente su: - JSON schema - meta - detail_fields - codici interni - configurazioni di basso livello

Il livello tecnico avanzato resta comunque disponibile tramite Expert Builder / editor schema, ma non e' il percorso standard.

3. Componenti principali¶

View centrale¶

La classe principale e': - EasyBuilderView

File: - app/modules/documentale/views.py

Responsabilita' principali: - CRUD builder - gestione tipi builder - gestione preset - libreria domande - libreria prompt - preview sandbox - audit - import/export builder - prompt parsing/apply - integrazione document_check

Questa classe e' il punto di orchestrazione del sistema.

Template HTML principali¶

Interfacce principali: - easy_builder_admin.html - easy_builder_edit.html - easy_builder_import.html - easy_builder_import_builder.html - easy_builder_compila_preview.html - easy_builder_catalog_types.html - easy_builder_catalog_presets.html - easy_builder_catalog_library.html - easy_builder_catalog_audit.html - easy_builder_prompt_builder.html

In pratica: - admin e edit sono il cuore del lavoro quotidiano - i catalog_* sono il layer di governance - compila_preview e' il ponte verso il runtime reale - prompt_builder e' il layer di authoring testuale

Frontend runtime¶

Il runtime finale continua a usare: - app/static/ras/ras_pack_hotfix35_finalize_zip.html

Questa e' un'altra scelta architetturale centrale: - non esiste un pack frontend separato per easy builder - l'easy produce configurazioni che il pack RAS gia' sa leggere

Le estensioni introdotte nel pack sono additive: - document_check - conditional_document_check - preview sandbox - gestione immagini compatibile con object key MinIO

4. Modello dati¶

Tabelle del layer easy¶

Tabelle applicative: - easy_builder_template - easy_builder_type - easy_builder_question_preset - easy_builder_question_library - easy_builder_prompt_library - easy_builder_audit

Ruolo delle tabelle:

`easy_builder_template`¶

Contiene la testata del builder: - tenant - tipo - nome - versione - stato - link al legacy_model_id

`easy_builder_type`¶

Contiene i tipi builder attivi: - ras - dvr - checklist - eventuali estensioni future

`easy_builder_question_preset`¶

Contiene i preset domanda disponibili per tipo builder.

`easy_builder_question_library`¶

Contiene le domande riusabili lato tenant/tipo builder.

`easy_builder_prompt_library`¶

Contiene template prompt seed e custom.

`easy_builder_audit`¶

Traccia le azioni principali sul sistema.

Tabelle runtime riusate¶

Il layer easy salva e legge dal motore runtime esistente: - legacy_dynamic_template - legacy_dynamic_template_schema - legacy_dynamic_template_question - legacy_dynamic_answer - legacy_dynamic_draft

Questo e' il cuore della compatibilita'.

Se si rompe questo mapping, si rompe il contratto con compila.

5. Mapping concettuale¶

Dal builder allo schema dynamic¶

Il mapping logico e' questo: - scheda principale -> sezione root - sottoscheda -> sezione child - domanda -> field - preset -> type/options/meta

Questo significa che l'easy non salva una struttura separata da quella runtime. La traduce in schema dynamic compatibile.

Dalla domanda alla risposta¶

Lato pack, la risposta viene normalizzata in un payload del tipo:

{
  "value": "Si",
  "detail": {
    "note": "testo"
  },
  "images": ["tenant/object/key.jpg"],
  "image_meta": {},
  "_ts": 1740000000
}

Questo payload viene poi salvato in: - legacy_dynamic_answer.valore_json

Questa forma va considerata il contratto di fatto tra editor, runtime e backend.

6. Preset domanda¶

I preset sono il modo con cui il sistema standardizza il comportamento delle domande.

Un preset definisce tipicamente: - type - choices - meta - detail_fields - eventuale question_mode

Ci sono due modalita' di authoring preset: - guidata - avanzata JSON

La GUI espone anche: - preview JSON - preview visuale - preview standard / In attesa

Questa parte e' molto importante perche' evita di dover dedurre il comportamento solo leggendo il JSON.

7. Prompt Builder¶

Il Prompt Builder e' un layer sopra il builder, non un motore a parte.

La pipeline corretta e': 1. input testo 2. traduzione assistita opzionale a DSL 3. parsing in operazioni 4. validazione 5. diff preview 6. apply su payload builder

Supporta: - DSL guidata - testo naturale assistito - libreria prompt

La scelta architetturale corretta qui e' stata: - non salvare direttamente da testo libero allo schema finale - passare sempre da operazioni e preview

Questo riduce molto il rischio.

8. Preview compila¶

La preview draft e' uno dei punti piu' importanti del sistema.

Usa endpoint sandbox dedicati per: - export - section - progress - save - bulk_save - draft_load - draft_save - upload_blob - image_url

Caratteristiche: - usa il pack reale - non tocca le risposte ufficiali - conserva stato in sessione - permette upload immagini temporanei

Questa parte e' importante perche' permette di validare il comportamento del builder senza pubblicarlo e senza sporcare dati veri.

9. Document check¶

Il document_check e' una capability trasversale al builder.

Modalita' presenti: - document_check diretto - conditional_document_check

Parametri tipici: - categoria - selection mode - validity field - warning days - grace days - no expiry policy

Il runtime interroga il backend e rende lo stato nel pack.

Il caso conditional_document_check e' importante perche' dimostra il confine tra: - logica easy/preset - logica runtime/frontend

10. Validazioni¶

La pubblicazione non e' un semplice cambio stato.

Prima del publish il sistema verifica almeno: - presenza schede - presenza sottoschede - presenza domande - preset obbligatorio - completezza document_check

Questo e' un punto di hardening, non solo una comodita' UI.

11. Audit e governance¶

Le azioni principali vengono registrate in: - easy_builder_audit

Ambiti tipici: - builder - preset - libreria domande - prompt library - import/export

L'audit non e' solo storico: e' un supporto di governance quando il sistema cresce.

12. Ruoli¶

Admin tenant¶

Può: - creare e gestire builder - usare prompt builder - pubblicare bozze

Super admin¶

Può in piu': - gestire tipi builder - gestire preset globali - governare il layer piu' avanzato

Questa separazione e' importante per mantenere la disciplina easy come standard, expert come eccezione.

13. Punti delicati da non rompere¶

Chi modifica il sistema deve tenere fissi questi vincoli:

1. Compatibilita' col pack `compila`¶

Il layer easy non deve introdurre un contratto alternativo casuale.

2. Compatibilita' col payload risposta¶

La forma delle answer deve restare coerente col pack e col backend.

3. Compatibilita' con media/MinIO¶

Le immagini devono continuare a usare object key e facade backend esistenti.

4. Compatibilita' con schema legacy/dynamic¶

Il valore dell'easy builder e' proprio il riuso del motore esistente.

14. Import legacy RAS JSON¶

Per la famiglia legacy RAS la direzione corretta e': - 1 template dynamic dedicato - N documenti importati - allegati storici conservati

Riferimenti: - docs/legacy_ras_json_import_strategy.md - comando CLI flask --app app legacy_ras_json_import ...

Questo e' coerente con tutta l'architettura appena descritta: si importa nel motore dynamic, non si crea un sottosistema separato.

15. Cosa fare quando arriva una nuova esigenza¶

La domanda corretta non e': - "dove riesco a infilarla?"

La domanda corretta e': - "questa esigenza va in preset, libreria, prompt capability o richiede davvero expert?"

Ordine corretto di valutazione: 1. preset 2. libreria domanda 3. estensione easy 4. expert

Se si salta subito all'ultimo livello, il sistema perde governabilita'.

16. Conclusione¶

Easy Builder non e' una pagina admin in piu'.

E' una piattaforma di authoring guidato costruita sopra il motore dynamic esistente, con: - governance - preview runtime - librerie - prompt - audit - compatibilita' piena col flusso in produzione

Chi lo mantiene deve proteggere soprattutto questo equilibrio: - semplificazione in authoring - compatibilita' a runtime - controllo delle eccezioni tramite expert