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
{
"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):comparefra due date o due numeri,emptyWhen/requiredWhencon 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.
"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) elist, con un filtro facoltativo (eq/neq,gt/gte/lt/ltesu 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'
referencecon 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' | Tile | Effetto |
|---|---|---|
period | chart | con 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 |
measures | chart bar o line | da 2 a 4 serie su campi diversi (il conteggio usa la chiave), ognuna con la sua label; in alternativa a measure |
filters | tutte | da 1 a 5 condizioni, tutte vere (AND); in alternativa a filter |
width | tutte | full, half (default) o third; le tile seguono l'ordine dell'elenco |
format | kpi | currency (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 |
{ "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
labeluna serie prende il nome dalla funzione e dal campo nella lingua dell'app (es. "Somma di Importo"). - Il validatore rifiuta:
groupBysu una data senzaperiod,periodsu un campo che non e' una data, due misure sullo stesso campo, piu' misure in una torta o un anello,filterefiltersinsieme,formatfuori 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 blueprint | Artefatti 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 ref | FK + colonna lookupByID verso la route di destinazione (value/text field friendly) |
enum | dizionario con etichette tradotte e CHECK sui valori |
entita' reference + referenceData | tabella e righe con ID conservati (upsert per chiave naturale) |
viste kanban / calendar / chart | archetipi in md_props_bag della route |
grants | ruoli e permessi per route; rowFilter → restrizione "utente dell'inserimento" |
menu | voci <app> / <app>__<voce> con etichette app.<app>.menu.* |
| etichette, valori, regole | traduzioni nel namespace app.<app>.* |
demoData | righe deterministiche (seme fisso) coerenti con tipi, riferimenti e regole |
dashboards | artefatto dashboard (board <app>_<chiave>, tile con la lettura nel md_props_bag) e voce di menu |
workflows | artefatto 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 blueprint | artefatto 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 ambienteprod. Per un'app esistente:POST api/app-generator/tests/installcon 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-currentricostruisce 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(defaultapp/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.mjsper 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).
| Chiave | Default | Significato |
|---|---|---|
Model | claude-opus-5-5 | modello della progettazione |
Effort / EditEffort | high / medium | effort della progettazione e delle modifiche a un'app installata (anche sul CLI) |
SendSampleValues / MaxSampleValues | false / 5 | valori di esempio (celle Excel, valori distinti) al modello solo con consenso |
MaxToolRounds / MaxProposalAttempts | 16 / 3 | giri di strumenti per turno, proposte non valide prima di chiudere il turno con errore |
TurnTimeoutSeconds / TurnTokenBudget | 300 / 1500000 | tempo e token massimi di un turno |
SessionTokenBudget | 6000000 | token di una sessione (turni chiusi); 0 = spento |
DailyTokenBudgetPerUser | 20000000 | token del giorno per utente sulle sessioni del generatore; 0 = spento |
MaxPendingTurnsPerUser / MaxTurnsPerMinutePerUser | 1 / 6 | turni in corso e al minuto per utente; 0 = spento |
API
| Metodo | Endpoint | Note |
|---|---|---|
| GET | api/app-generator/schema | schema JSON del blueprint |
| POST | api/app-generator/validate / compile / install | blueprint nel corpo; install = piano del ciclo di vita, l'apply e' api/meta-lifecycle/promotions/{id}/apply |
| GET / POST | api/app-generator/catalog, draft, reverse | catalogo, bozza da tabelle, blueprint inverso |
| POST | api/app-generator/excel/upload, excel/draft, excel/import | Excel/CSV |
| POST / GET | api/app-generator/sessions, sessions/{id} | sessioni (nl, db, excel, app) |
| POST | api/app-generator/sessions/{id}/messages | turno asincrono: risposta "pending", esito sul messaggio e nella campanella |
| GET / PUT | api/app-generator/sessions/{id}/blueprint | versione corrente; PUT = modifica manuale rivalidata |
| GET | .../blueprint/versions, .../blueprint/diff?from=&to= | versioni e differenze |
| POST | .../package, .../install, .../import-data | pacchetto, piano (a 3 vie per le modifiche), import delle righe |
| POST / GET | api/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-sdkil 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 percorsoapi/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.
| Metrica | Risultato |
|---|---|
| proposte valide e compilate nei 4 dialetti | 31/31 |
| installate e applicate (SQL Server) | 23/23 |
| entita' attese trovate / entita' di business pertinenti | 100% / 98,5% |
| relazioni e tipi dei campi | 100% / 100% |
| ruoli con piu' diritti di quanto descritto | 0 |
| iniezioni eseguite o segreti usciti | 0 |
| modifiche e confronti a 3 vie corretti | 5/7 |
| suite API generata verde | 23/28 app |
| turni per app / latenza di un turno | 1,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,computednon sono supportati. Le tilelistmostrano le colonne scelte (columns) nell'ordine dato; il blueprint inverso rilegge solo dashboard e workflow con la forma generata. rowFiltersolo 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
refnuovo 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




