@esfaenza/flow-builder 20.3.52 → 20.3.54

package/README.md

@@ -162,7 +162,7 @@ sono opzionali e rifiutano con `MissingService` se non sovrascritti.
 | `listEnumTypes`, `listEvents`, `listSubflowCandidates` | astratti |
 | `describeObject` | opzionale |
 | `listFieldValues(object, field)` | opzionale — i valori ammessi di un campo a **scelta chiusa** (`hasClosedValueSet`, §6.4), cioe' l'altra meta' degli insiemi chiusi: quelli di un `Enum` sono del **tipo** (`listEnumValues`), questi della **colonna** — `Ordine.Stato` e `Attivita.Stato` possono ammettere valori diversi pur essendo due `String`, ed e' perche' serve la coppia. Lista vuota = "non lo so": il valore si scrive a mano |
-| `listFormulaFunctions(usage?)` | opzionale — le funzioni (e gli operatori, se il motore li dichiara) scrivibili in un'espressione: e' la **palette** di `<fb-formula-editor>`, la terza gamba accanto ai nomi (`getReferences`) e al giudizio (`validateFormula`). `usage` e' lo stesso di `validateFormula` e un motore che non filtra risponde comunque tutto, che e' legittimo. Due regole: lista vuota = «il motore non le dichiara» e la palette non compare (§4.6), e l'elenco **non e' autoritativo** — accusare una funzione fuori catalogo sarebbe un rilievo falso su una formula valida |
+| `listFormulaFunctions(usage?)` | opzionale — le funzioni (e gli operatori, se il motore li dichiara) scrivibili in un'espressione: e' la **palette** di `<fb-formula-editor>`, la terza gamba accanto ai nomi (`getReferences`) e al giudizio (`validateFormula`). `usage` e' lo stesso di `validateFormula` e un motore che non filtra risponde comunque tutto, che e' legittimo. Due regole: lista vuota = «il motore non le dichiara» e la palette non compare (§4.6), e l'elenco **non e' autoritativo** — accusare una funzione fuori catalogo sarebbe un rilievo falso su una formula valida. `requiresPriorValues` marca le funzioni sui valori precedenti del record: la palette le toglie dove un «prima» non c'e' (§6.3) |
 | `listEnumValues(enumType)` | opzionale — i **valori** di un tipo di enumerazione, cioe' i nomi scrivibili in `enumValue` (§4.2, §4.6). `listEnumTypes` e' l'altra meta' e non basta: quella dice quali tipi esistono, questa quali valori ha un tipo. `enumType` e' esattamente l'`objectType` della risorsa, del parametro o del **membro** di una classe (§4.7.1): la risposta e' del tipo, non del punto di uso, e la cache e' per nome del tipo. Lista vuota = "non lo so" — il valore si scrive a mano, e un tipo sconosciuto risponde vuoto, non 404 |
 | `listStructures`, `describeStructure(className)` | opzionali — le classi e i loro membri per le risorse `Structure` (§4.7). `listStructures` e' l'**elenco delle classi** senza membri; `describeStructure` restituisce la **descrizione** di una classe (`className`, `label`, `members`), non un array nudo (§4.7.1). Senza, le classi non sono verificabili e il nome si scrive a mano: "non lo so", non "non esiste". I tre esiti sono distinti: `members` popolato = elenco autorevole, `members: []` = membri non dichiarati (si digita, nessuna accusa), rifiuto `StructureNotFound` = classe non registrata (si segnala la **classe**) |
 
@@ -394,11 +394,62 @@ Tre conseguenze nell'editor:
 - **la coppia si legge in un posto solo**, `FlowDictionaryStore.flowTypeOf`. Tre dei sei tipi sono
   `AutoLaunched`, quindi ogni domanda posta al solo `processType` da qui in avanti risponde male: e'
   il motivo per cui la palette decide di offrire gli screen da `allowsScreens` e non piu' dal
-  `processType`, e per cui lo Start propone i soli `triggerTypes` del tipo scelto;
+  `processType`, e per cui lo Start propone i soli `triggerTypes` del tipo scelto — e su un flow
+  innescato da un record nemmeno quelli, vedi qui sotto;
 - `flowType` compare **derivato** nell'elenco dei flow, nelle versioni e nell'outline, e vale `null`
   per cio' che non e' uno dei sei (un `Evaluation`, un'orchestrazione senza trigger): lì si mostra il
   `processType`, e non e' un difetto da correggere.
 
+**Quando parte un flow innescato da un record (§3.4).** I campi sono due — `recordTriggerType` è
+l'**operazione**, `triggerType` il **momento** rispetto alla scrittura — ma non sono due assi liberi,
+perché l'eliminazione ha un momento solo: le coppie che significano qualcosa sono sei. Da due tendine
+indipendenti si dichiara «prima dell'eliminazione» insieme a «alla creazione», e il runtime la legge
+come un'eliminazione — con `RecordBeforeDelete` l'operazione la dice il trigger e `recordTriggerType`
+non viene guardato — cioè il flow parte su un'operazione che nessuno ha scelto.
+
+Quindi su questi flow l'inspector dello Start **non ha la tendina «quando parte»**: chiede
+l'oggetto, poi l'**operazione**, poi i criteri, poi il **momento** fra i soli che l'operazione
+ammette. Quali siano lo dice la voce di `recordTriggerTypes` nei dizionari — `triggerTypes`,
+`defaultTriggerType`, `allowsTimingChoice`, `usesPriorRecord` — e sono gli stessi flag che applica il
+backend: proporre i `triggerTypes` di primo livello significa proporre coppie che la validazione
+rifiuta. Quattro conseguenze:
+
+- i due campi si scrivono **insieme, in una sola mutazione**: con due, l'annulla riporterebbe
+  indietro il momento lasciando l'operazione nuova, cioè una coppia che non è nessuna delle sei;
+- dove il momento è unico la domanda **non si pone** e il campo si scrive comunque, perché il
+  contratto chiede entrambi;
+- `doesRequireRecordChangedToMeetCriteria` compare **solo** dove l'operazione porta
+  `usesPriorRecord`: alla creazione e all'eliminazione non c'è un «prima» da confrontare, e il flag
+  resterebbe inerte;
+- `START_TRIGGER_MISMATCH` da questa sequenza **non è esprimibile**. Lo si incontra solo aprendo un
+  documento scritto altrove, e lì l'editor lo **dice** e offre il comando per rimettere il momento fra
+  quelli ammessi, invece di correggerlo da sé — quale metà della coppia sia quella voluta non lo sa.
+  Gli altri due rilievi sono avvisi: operazione assente su un trigger di salvataggio vale «ogni
+  salvataggio» (`START_RECORD_TRIGGER_MISSING`), operazione su un flow che non è innescato da un
+  record è inerte (`START_RECORD_TRIGGER_IGNORED`).
+
+**I valori precedenti del record non ci sono sempre (§7).** Chi li legge — l'operatore `IsChanged`,
+un riferimento radicato su `$Record__Prior`, il flag `doesRequireRecordChangedToMeetCriteria` — vale
+quanto l'**operazione** che innesca il flow, non quanto il momento. È l'unico codice con **tre**
+gravità: sull'aggiornamento i valori ci sono a ogni esecuzione e non c'è niente da dire; su
+«creazione e aggiornamento» sulla creazione non ci sono, e lì la condizione non è valutabile — il
+flow funziona a metà, quindi `Warning`; sulla creazione e sull'eliminazione non ci sono mai e a
+runtime l'interview **fallisce** davanti a chi stava salvando, quindi `Error`. Su un flow che non è
+innescato da un record resta un avviso: i valori può passarli chi avvia l'interview.
+
+La regola sta in `core/record-trigger.ts` — `priorValuesOfDefinition`, `priorValuesSeverity`,
+`priorCriteriaSeverity` — ed è esportata perché la applicano i due capi: l'editor la dice **mentre
+si scrive** la condizione (condition editor, editor dei filtri, reference picker), il backend la
+emette come `PRIOR_VALUES_NOT_AVAILABLE`. Tre conseguenze:
+
+- il flag dei criteri di ingresso è l'eccezione: il runtime lo **ignora** invece di fallire, quindi
+  non è mai un errore, e su «creazione e aggiornamento» non è nemmeno un rilievo;
+- nel reference picker `$Record__Prior` ha uno stato suo, guardato **prima** degli altri: un host
+  che smette di proporre quello scope — ed è giusto che lo faccia dove i valori non ci sono mai — lo
+  farebbe altrimenti cadere in «questo nome non esiste», che manda a cercare un nome sbagliato;
+- le **formule** restano fuori: un'espressione che cita `$Record__Prior` non è analizzabile lato
+  client, perché la sintassi la conosce solo il motore (§6.3).
+
 **L'attivazione, e la sua seconda meta' (§8).** I tre tipi che non partono da soli vanno **presi in
 carico** dall'infrastruttura dell'ospite — uno scheduler, un bus, un intercettore delle scritture — e
 il backend li registra prima di attivare. Da lì due esiti che il pannello dei problemi non spiega,
@@ -765,7 +816,15 @@ Due cose che non si devono confondere: elenco vuoto significa «il motore non le
 il bottone non compare affatto invece di aprire un pannello vuoto; e l'elenco **non e'
 autoritativo** — a giudicare resta `validateFormula`, e accusare una funzione fuori catalogo
 sarebbe un rilievo falso su una formula valida, perche' un motore puo' supportare piu' di quanto
-dichiara. `signature` e `description` si mostrano e non si parsano: la grammatica resta del motore. Lo usano tutti i punti in cui si scrive
+dichiara. `signature` e `description` si mostrano e non si parsano: la grammatica resta del motore.
+Il solo filtro che la palette applica da sé è `requiresPriorValues` (§6.3): le funzioni che leggono i
+**valori precedenti** del record — `PRIORVALUE`, `ISCHANGED` — non si propongono dove un «prima» non
+c'è mai (creazione, eliminazione) né dove non c'è un record che innesca; su «creazione e
+aggiornamento» restano, perché la metà aggiornamento le usa. La regola è quella di
+`core/record-trigger.ts`, la stessa che il backend applica quando il suo endpoint riceve il
+documento — la `GET` proposta dal contratto non lo porta, quindi filtrare qui è ciò che la fa
+funzionare comunque; e resta una **proposta**, perché a giudicare una `PRIORVALUE` scritta a mano è
+sempre `validateFormula`, con il codice che il motore dichiara. Lo usano tutti i punti in cui si scrive
 un'espressione: la risorsa `Formula`, la modalita' Formula di una condizione, la `filterFormula`
 di un filtro, la regola di validazione di un campo di screen dinamico e il `formulaExpression`
 dentro un valore. A ogni punto corrispondono un `usage` e un `expectedDataType` — `Boolean` per