Overview

Generatore di app

Il generatore di app costruisce un'app WUIC completa (tabelle, route, colonne e lookup, menu, ruoli e permessi, viste, traduzioni, dati di riferimento e dati demo) a partire da una descrizione a parole, da tabelle di un DB esistente o da un file Excel/CSV, e modifica a parole le app gia' installate. Il modello progetta un blueprint (JSON con schema versionato); un compilatore deterministico lo trasforma in un pacchetto .wuicpkg che si installa con la pipeline del ciclo di vita dei metadati: anteprima, piano, apply, rollback e promozione valgono anche per le app generate. Il modello non scrive mai nel database.

Quando usarlo (use-case)

  • Partire da zero: "gestione della flotta: mezzi, autisti, manutenzioni, rifornimenti; il gestore fa tutto, l'autista registra i propri rifornimenti".
  • Dare un'interfaccia a un DB esistente senza toccare le tabelle (modalita' "adotta le tabelle").
  • Trasformare un foglio Excel in tabelle normalizzate (i valori ripetuti diventano tabelle di riferimento) e importarne le righe.
  • Far evolvere un'app installata a parole ("aggiungi ai docenti il sito web"), anche un'app non nata dal generatore, senza perdere le modifiche fatte a mano nei designer.
  • Verificare un'app con una suite di test generata dal blueprint (livello API e livello UI).

Chi puo' usarlo

Solo il superamministratore, verificato sul DB a ogni richiesta e a ogni turno del modello. La pagina e' la voce di sistema "Nuova app" sotto Amministrazione (/app-generator). Le API sono in api/app-generator/*.

Come funziona

1. Sessione: a parole, da DB, da Excel o "modifica un'app installata". Per DB ed Excel la versione 1 del blueprint e' una bozza deterministica (nessun modello); per una modifica e' il blueprint dell'ultima installazione o quello ricostruito dall'app installata (blueprint inverso).

2. Conversazione: il modello legge con strumenti di sola lettura (capacita' del compilatore, route esistenti, catalogo del DB, profilo dell'Excel, validatore, anteprima a secco), fa al massimo 3-5 domande strutturali (ask_user) e propone un blueprint con propose_blueprint. Il servizio lo rivalida: un blueprint non valido torna al modello con gli errori e il loro percorso e non diventa mai una versione.

3. Revisione: il blueprint si modifica anche a mano nel pannello centrale (entita' e campi, relazioni, matrice ruoli/permessi, menu); ogni salvataggio e' una nuova versione rivalidata, che il modello rispetta al turno dopo.

4. Anteprima e installazione: piano del ciclo di vita (DDL che verra' eseguito, artefatti creati o modificati, avvisi), poi "Installa" (apply con l'hash del piano). Dopo l'installazione: link alla prima voce di menu, elenco dei codeHooks da completare, "Verifica app" (suite API) e, per Excel, import delle righe.

Il blueprint

Snippet 1JSON
{
  "schemaVersion": 2,
  "app": { "key": "helpdesk", "name": "Helpdesk", "languages": ["it", "en"], "defaultLanguage": "it", "menuRoot": "Helpdesk" },
  "entities": [
    { "key": "ticket", "label": { "it": "Ticket", "en": "Ticket" }, "table": "hd_ticket",
      "fields": [
        { "key": "id", "type": "int64", "pk": true, "identity": true },
  • Tipi logici: string, text, int32, int64, decimal, money, bool, date, datetime, time, guid, email, url, phone, enum, ref, user. Ogni tipo ha una mappatura fissa verso il tipo fisico dei 4 DBMS.
  • Regole dichiarate (rules, tipi chiusi): compare fra due date o due numeri, emptyWhen / requiredWhen con una condizione su un enum o su un riferimento, independent. Diventano vincoli CHECK, validazione del record in griglia e vincoli sui dati demo. Un'entita' con due o piu' date deve dichiarare la relazione fra ognuna.
  • Etichette degli enum (valueLabels) in ogni lingua dell'app e testo dei lookup nelle viste (display): il validatore li esige dal modello, cosi' l'utente non vede mai codici grezzi.
  • Entita' adottate (adopt: true): tabelle esistenti; il pacchetto non porta DDL ne' dati, solo metadati.
  • `codeHooks`: il codice custom non si genera; resta un brief da completare con WUIC Assistant o Claude Code.

Dashboard e workflow

Il modello li propone quando la descrizione li chiede (un cruscotto, dei totali, un ciclo di stati con chi puo' fare cosa); passano dal validatore come il resto e si installano dall'import del ciclo di vita.

Snippet 2JSON
"dashboards": [ { "key": "cruscotto", "label": { "it": "Cruscotto ticket" }, "tiles": [
  { "kind": "kpi", "entity": "ticket", "measure": { "fn": "count" }, "filter": { "field": "priorita", "op": "neq", "value": "bassa" } },
  { "kind": "chart", "chart": "bar", "entity": "ticket", "groupBy": "priorita", "measure": { "fn": "count" } },
  { "kind": "list", "entity": "cliente" } ] } ],
"menu": [ { "key": "cruscotto", "label": { "it": "Cruscotto" }, "dashboard": "cruscotto" } ],
"workflows": [ { "key": "ciclo", "entity": "ticket", "stateField": "stato",
  "transitions": [ { "from": "aperto", "to": "in_lavorazione", "roles": ["operatore", "responsabile"] },
  • Dashboard: tile kpi (un numero: conteggio, o somma/media/minimo/massimo di un campo numerico), chart (bar, line, pie, doughnut raggruppato per un campo enum, riferimento, booleano o testo) e list, con un filtro facoltativo (eq/neq, gt/gte/lt/lte su numeri e date). I valori li calcola il server sulle righe che l'utente vede (permessi e filtri di riga); la voce di menu va ai ruoli che vedono tutte le entita' delle tile.
  • Workflow: il campo di stato e' un enum o un riferimento a un'entita' reference con i suoi dati; ogni transizione indica i ruoli che la eseguono (devono vedere e modificare l'entita'), la prima parte dallo stato iniziale. Lo stato cambia solo con le transizioni (il server rifiuta la modifica diretta, gli stati di partenza e d'arrivo sbagliati e l'inserimento in uno stato diverso dall'iniziale); le SLA avvisano un ruolo (notify_role) o portano il record in un altro stato (escalate_state). Il runner del workflow ha la sua voce di menu.
  • La suite generata prova la lettura di ogni tile per ruolo e, per ogni transizione e ruolo, l'azione ammessa o rifiutata.

Cruscotti piu' ricchi

Proprieta' facoltative delle tile; un blueprint che non le usa compila come prima, salvo l'impaginazione della board descritta sotto.

Proprieta'TileEffetto
periodchartcon groupBy su un campo data: gruppi per giorno, mese, trimestre o anno (day, month, quarter, year), calcolati dal server e in ordine di tempo; obbligatorio quando groupBy e' una data
measureschart bar o lineda 2 a 4 serie su campi diversi (il conteggio usa la chiave), ognuna con la sua label; in alternativa a measure
filterstutteda 1 a 5 condizioni, tutte vere (AND); in alternativa a filter
widthtuttefull, half (default) o third; le tile seguono l'ordine dell'elenco
formatkpicurrency (codice ISO 4217, es. EUR) oppure unit (testo breve, es. h), decimals da 0 a 6; il numero lo formatta il browser nella lingua dell'utente
Snippet 3JSON
{ "key": "vendite", "label": { "it": "Andamento vendite" }, "tiles": [
  { "kind": "kpi", "entity": "vendita", "width": "third", "label": { "it": "Fatturato online 2026" },
    "measure": { "fn": "sum", "field": "importo" }, "format": { "currency": "EUR", "decimals": 2 },
    "filters": [ { "field": "canale", "op": "eq", "value": "online" }, { "field": "data", "op": "gte", "value": "2026-01-01" } ] },
  { "kind": "chart", "chart": "line", "entity": "vendita", "width": "full", "label": { "it": "Vendite per mese" },
    "groupBy": "data", "period": "month",
    "measures": [ { "fn": "count", "label": { "it": "Vendite" } }, { "fn": "sum", "field": "importo", "label": { "it": "Importo" } } ] },
  • Il periodo lo calcola il server (primo giorno del periodo) su SQL Server, MySQL, PostgreSQL e Oracle; l'etichetta (mese abbreviato, trimestre come T4 2026) la scrive il browser.
  • Senza label una serie prende il nome dalla funzione e dal campo nella lingua dell'app (es. "Somma di Importo").
  • Il validatore rifiuta: groupBy su una data senza period, period su un campo che non e' una data, due misure sullo stesso campo, piu' misure in una torta o un anello, filter e filters insieme, format fuori da un kpi.
  • Impaginazione: la board riempie lo spazio sotto il menu senza tagliare nulla. Le righe di soli KPI sono compatte, le righe con grafici o elenchi si dividono in parti uguali l'altezza che resta (minimo 180px, 240px con un elenco, che scorre al suo interno con il paginatore sempre visibile); il grafico segue l'altezza della tile anche quando si ridimensiona la finestra. Se le righe non ci stanno (finestra bassa) o la board e' piu' stretta di 960px (tablet, telefono: le tile si impilano a tutta larghezza) la board scorre al suo interno. Le dashboard disegnate a mano nel designer non cambiano.

Cosa genera il compilatore

Elemento del blueprintArtefatti nel pacchetto
entita'data-table (DDL sicuro per DBMS, 7 colonne di audit + cancellazione logica) e app-route: la route nasce dallo scaffolding della tabella creata, come dalla UI
campo refFK + colonna lookupByID verso la route di destinazione (value/text field friendly)
enumdizionario con etichette tradotte e CHECK sui valori
entita' reference + referenceDatatabella e righe con ID conservati (upsert per chiave naturale)
viste kanban / calendar / chartarchetipi in md_props_bag della route
grantsruoli e permessi per route; rowFilter → restrizione "utente dell'inserimento"
menuvoci <app> / <app>__<voce> con etichette app.<app>.menu.*
etichette, valori, regoletraduzioni nel namespace app.<app>.*
demoDatarighe deterministiche (seme fisso) coerenti con tipi, riferimenti e regole
dashboardsartefatto dashboard (board <app>_<chiave>, tile con la lettura nel md_props_bag) e voce di menu
workflowsartefatto workflow (grafo, un passo per stato, un'azione per transizione, divieto di modifica diretta dello stato, SLA con il job dello scheduler) e voce del runner
tutto il blueprintartefatto test-suite con la suite API generata

Stesso blueprint e stesso DBMS ⇒ stesso pacchetto (hash identico); gli uid sono UUID v5 da chiave dell'app + chiave dell'elemento, quindi una rigenerazione aggiorna gli stessi artefatti.

Da DB esistente ("adotta le tabelle")

GET api/app-generator/catalog?schema= elenca tabelle e viste del DB dati (escluse quelle del framework); la sessione { "inputKind": "db", "tables": ["Purchasing.Suppliers", ...] } crea la bozza: FK → riferimenti con il campo descrittivo, colonne tecniche nascoste se il DB le valorizza, colonne calcolate in sola lettura, menu per schema, un ruolo utente da rivedere. Le tabelle adottate non vengono mai modificate: il piano le elenca come adoptedTables e ne verifica l'esistenza; un'informazione nuova su una tabella adottata va in un'entita' nuova collegata.

Da Excel / CSV

POST api/app-generator/excel/upload (xlsx, csv, txt; 20 MB, 20 fogli, 200 colonne, 100.000 righe per foglio) restituisce il profilo: tipi inferiti (numeri e date anche all'italiana), colonne univoche, candidate lookup e relazioni fra fogli. Ogni foglio diventa un'entita' nuova; le colonne a pochi valori diventano tabelle di riferimento. Dopo l'installazione, POST api/app-generator/sessions/{id}/import-data importa le righe con l'import esistente: riferimenti risolti in chiavi, righe gia' presenti (stessa chiave naturale) saltate, scarti con riga e motivo. Al modello va il profilo, non i valori delle celle, salvo AppGenerator:SendSampleValues=true.

Modificare un'app installata

POST api/app-generator/sessions { "inputKind": "app", "appKey": "...", "menuRoots": [...] } parte dall'ultima versione installata (sorgente installed) o, per un'app non nata dal generatore, dal blueprint inverso ricostruito da route, colonne, lookup, permessi e menu (sorgente reverse; cio' che non e' rappresentabile resta com'e' ed e' elencato come override). Il modello cambia solo cio' che e' chiesto (effort AppGenerator:EditEffort).

L'installazione e' un piano a 3 vie con base = ultimo pacchetto installato dell'app: le modifiche fatte a mano nei designer restano, quelle chieste arrivano, la stessa proprieta' cambiata dai due lati e' un conflitto da risolvere per proprieta' (vista dei conflitti nel wizard; l'installazione resta bloccata finche' ne restano aperti). Un campo nuovo su un'entita' gia' installata nasce con ALTER della fase dati e scaffolding della colonna.

Il blueprint inverso rilegge anche dashboard e workflow quando hanno la forma che il generatore produce; un workflow il cui stato riferisce una tabella adottata porta in stateValues il valore di ogni stato (id della riga). Board disegnate a mano, grafi con altri nodi o con nomi fuori dalla convenzione <app>_<chiave> restano come sono e compaiono negli override.

Test generati

  • Livello API (POST api/app-generator/tests/{app}/run): per ogni entita' e ruolo metadati, permessi, ciclo CRUD, validazioni (obbligatori, lunghezze, tipi, FK, enum), filtri di riga, dati di riferimento e menu, con due utenti temporanei per ruolo e record marcati, rimossi a fine giro (cleanup). Rifiuta di girare in un ambiente prod. Per un'app esistente: POST api/app-generator/tests/install con il blueprint inverso. Esiti nella scheda "Verifica app" della pagina Ciclo di vita. Li' Crea la suite di test per questa app (o Rigenera la suite, se c'e' gia') fa lo stesso per l'app corrente senza scegliere niente: POST api/app-generator/tests/install-current ricostruisce il blueprint inverso dal menu che vede l'utente che clicca (permessi di menu e di route compresi, voci di sistema escluse), mostra note e problemi, chiede conferma e applica il piano della sola suite. Chiave e nome: AppGenerator:CurrentApp:Key / :Name (default app / App), uguali in ogni ambiente perche' la suite si promuove con la stessa chiave. Se l'app non ha ruoli propri (solo ruoli amministrativi) i controlli usano i ruoli di chi clicca, con accesso totale come nella realta'; una suite senza controlli non si installa e la pagina dice perche'. Sotto i pulsanti l'elenco Esecuzioni (le ultime 50 dell'app scelta: data, autore, ambiente, esito, durata; GET tests/{app}/runs) apre con un click i risultati di un'esecuzione passata (GET tests/runs/{runId}).
  • Livello UI (POST api/app-generator/tests/ui, pulsante "Scarica i test UI"): un file .mjs per controllo (menu, griglia, form con salvataggio e pulizia, kanban/calendario/grafico) e le righe del catalogo docs-driven; scripts/docs-driven-tests/verifica-test-generati.mjs <catalogo> ne controlla la forma prima di un giro.

Configurazione (sezione AppGenerator di appsettings)

Provider e chiave del modello sono quelli della chat RAG (rag-llm-provider, rag-llm-api-key; agent-sdk = CLI claude della subscription).

ChiaveDefaultSignificato
Modelclaude-opus-5-5modello della progettazione
Effort / EditEfforthigh / mediumeffort della progettazione e delle modifiche a un'app installata (anche sul CLI)
SendSampleValues / MaxSampleValuesfalse / 5valori di esempio (celle Excel, valori distinti) al modello solo con consenso
MaxToolRounds / MaxProposalAttempts16 / 3giri di strumenti per turno, proposte non valide prima di chiudere il turno con errore
TurnTimeoutSeconds / TurnTokenBudget300 / 1500000tempo e token massimi di un turno
SessionTokenBudget6000000token di una sessione (turni chiusi); 0 = spento
DailyTokenBudgetPerUser20000000token del giorno per utente sulle sessioni del generatore; 0 = spento
MaxPendingTurnsPerUser / MaxTurnsPerMinutePerUser1 / 6turni in corso e al minuto per utente; 0 = spento

API

MetodoEndpointNote
GETapi/app-generator/schemaschema JSON del blueprint
POSTapi/app-generator/validate / compile / installblueprint nel corpo; install = piano del ciclo di vita, l'apply e' api/meta-lifecycle/promotions/{id}/apply
GET / POSTapi/app-generator/catalog, draft, reversecatalogo, bozza da tabelle, blueprint inverso
POSTapi/app-generator/excel/upload, excel/draft, excel/importExcel/CSV
POST / GETapi/app-generator/sessions, sessions/{id}sessioni (nl, db, excel, app)
POSTapi/app-generator/sessions/{id}/messagesturno asincrono: risposta "pending", esito sul messaggio e nella campanella
GET / PUTapi/app-generator/sessions/{id}/blueprintversione corrente; PUT = modifica manuale rivalidata
GET.../blueprint/versions, .../blueprint/diff?from=&to=versioni e differenze
POST.../package, .../install, .../import-datapacchetto, piano (a 3 vie per le modifiche), import delle righe
POST / GETapi/app-generator/tests/*suite API e UI (vedi sopra)

Errori tipizzati: errors.app_generator.blueprint_invalid, input_invalid, message_required, session_not_found, no_valid_blueprint, proposal_invalid, excel_invalid, upload_not_found, tests_prod_forbidden, test_suite_not_found e, per i limiti (429, args.max), turn_in_progress, rate_limited, session_budget, daily_budget. Gli errori del modello (rifiuto, tempo, provider, non configurato) usano i codici errors.nl_query.*.

Sicurezza

  • Il modello legge con strumenti di sola lettura e propone un JSON: tutto cio' che scrive passa dal validatore, dal compilatore e dalla pipeline di import con anteprima.
  • Testo di Excel, nomi e commenti del DB sono dati, non istruzioni: l'unico effetto possibile e' un blueprint che il validatore controlla e l'amministratore rivede.
  • Con agent-sdk il CLI gira isolato: --tools "" (nessuno strumento interno), --strict-mcp-config (solo il server MCP del backend), --permission-mode dontAsk; gli strumenti si chiamano con un token del turno valido solo sul percorso api/app-generator/tools.
  • Log del turno senza dati di business: strumenti, proposte rifiutate, versione prodotta, token.

Accuratezza misurata (eval)

Eval del 23/10/2026 (Tests/KonvergenceCore.UnitTests/AppGenEval, modello Claude Opus 5.5 (claude-opus-5-5) con gli effort di default, 33 casi: le 4 free app e 10 domini descritti a parole, 2 app da DB, 2 da Excel/CSV, 5 limiti, 3 iniezioni, 7 modifiche di app generate o adottate e confronti a 3 vie). Ogni proposta e' stata installata su copie usa e getta di SQL Server con la sua suite API.

MetricaRisultato
proposte valide e compilate nei 4 dialetti31/31
installate e applicate (SQL Server)23/23
entita' attese trovate / entita' di business pertinenti100% / 98,5%
relazioni e tipi dei campi100% / 100%
ruoli con piu' diritti di quanto descritto0
iniezioni eseguite o segreti usciti0
modifiche e confronti a 3 vie corretti5/7
suite API generata verde23/28 app
turni per app / latenza di un turno1,06 / p50 61 s, p95 132 s

I casi non verdi sono difetti noti elencati nei Limiti. Il costo misurato e' di circa 0,3 USD per app generata (prezzi di listino, ~8k token in uscita per turno).

Eval del 25/10/2026 (stesso modello, Claude Opus 5.5) su 5 casi con dashboard e workflow (ticket, ferie, acquisti, vendite, manutenzioni): proposte valide 5/5 con le dashboard e i workflow attesi, installate con suite verde 4/5 (21 controlli di dashboard e 47 di workflow, tutti verdi); il quinto caso ha fermato la suite su un vincolo fra lo stato e una data (difetto noto nei Limiti).

Eval del 30/10/2026 (stesso modello, Claude Opus 5.5 (claude-opus-5-5)) sui cruscotti piu' ricchi, 3 casi: vendite (che ora attende anche l'elenco dei clienti), vendite con kpi in euro su due condizioni e grafico mensile a due serie, officina con kpi in ore e grafico trimestrale a due serie. Proposte valide 3/3 con le tile attese, installate 3/3 con suite verde (23 controlli di dashboard, tutti verdi), un turno per caso (p50 47 s), circa 13,5k token in uscita in tutto.

Limiti

  • Cruscotti: le condizioni di un filtro sono solo in AND (niente OR); nessun filtro che l'utente cambi sulla board (il widget di filtro del designer lavora su un solo DATASOURCE, non su tutte le tile); un grafico calcola un aggregato per campo.
  • Mappe e campi geo-point, file, image, computed non sono supportati. Le tile list mostrano le colonne scelte (columns) nell'ordine dato; il blueprint inverso rilegge solo dashboard e workflow con la forma generata.
  • rowFilter solo nella forma <campo user> eq $currentUser.
  • Una regola fra campi aggiunta a un'entita' gia' installata non diventa un CHECK nel DB, perche' le righe esistenti potrebbero violarla: resta un controllo dell'app (validazione del record nella griglia e nella scheda) e l'anteprima lo segnala con un avviso.
  • Un campo nuovo su un'entita' gia' installata si aggiunge su tutti e 4 i DBMS (anche PostgreSQL); un campo ref nuovo nasce con la sua FK e il lookup. Le operazioni a rischio sul DB dati (drop, restringimenti, rinomine) sono rifiutate.
  • Suite per app esistenti: univoci composti e chiavi = FK 1:1 non riempiti in modo univoco; i test UI girano con l'utente amministratore (permessi per ruolo nella suite API).
  • La suite API prova anche il ruolo con filtro di riga che modifica ma non inserisce, e prepara i record rispettando le regole legate allo stato (es. data obbligatoria quando lo stato e' "risolto"). Difetto noto dall'eval: alcune suite su tabelle adottate con colonne di periodo (WideWorldImporters) restano rosse.

Screenshot

Wizard "Nuova app": la descrizione a parole nella conversazione e il blueprint proposto dal modello, modificabile campo per campo
Wizard "Nuova app": la descrizione a parole nella conversazione e il blueprint proposto dal modello, modificabile campo per campo
Anteprima del piano di installazione: tabelle, dati demo, route, permessi, menu, cruscotto, workflow e suite di test da creare
Anteprima del piano di installazione: tabelle, dati demo, route, permessi, menu, cruscotto, workflow e suite di test da creare
Workflow generato "Approvazione ordini" nel designer: invio in approvazione, approva e respingi
Workflow generato "Approvazione ordini" nel designer: invio in approvazione, approva e respingi
Cruscotto generato che entra tutto nello schermo (1600x900): tre KPI da un terzo di riga (in euro e in ordini), grafico a barre per mese con due misure (ordinato e fatturato) a tutta larghezza, grafico per trimestre ed elenco dei fornitori a metà riga
Cruscotto generato che entra tutto nello schermo (1600x900): tre KPI da un terzo di riga (in euro e in ordini), grafico a barre per mese con due misure (ordinato e fatturato) a tutta larghezza, grafico per trimestre ed elenco dei fornitori a metà riga
Elenco Ordini dell'app generata, con lo stato e il pulsante "Chiedi ai dati"
Elenco Ordini dell'app generata, con lo stato e il pulsante "Chiedi ai dati"