@esfaenza/flow-builder 20.3.53 → 20.3.55

package/README.md

@@ -141,7 +141,7 @@ sono opzionali e rifiutano con `MissingService` se non sovrascritti.
 | `createVersion(flowName, request?)` | astratto |
 | `activateVersion(flowName, version)` | astratto |
 | `deactivateFlow(flowName)` | astratto |
-| `cloneFlow`, `deleteVersion`, `deleteFlow` | opzionali — senza `cloneFlow` «Duplica» resta disponibile e ripiega su `createFlow` |
+| `cloneFlow`, `deleteVersion`, `deleteFlow` | opzionali — senza `cloneFlow` «Duplica» resta disponibile e ripiega su `createFlow`; `deleteVersion` e' il comando del pannello versioni, mentre **`deleteFlow` non la chiama nessun componente**: eliminare un flow e' dell'ospite (vedi «Versioni») |
 
 | §6.3 Validazione | |
 |---|---|
@@ -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**) |
 
@@ -428,6 +428,28 @@ rifiuta. Quattro conseguenze:
   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,
@@ -642,6 +664,17 @@ ripulitura e' un comando («Togli»), non un effetto dell'apertura del form: can
 un flow scritto altrove farebbe sparire l'unico indizio di cosa doveva selezionare. Il rilievo si
 vede in **tutti e due** i posti, elenco e form, come gli altri controlli locali.
 
+*Da dove vengono i due campi su una collection.* Su `collectionReference` non c'e' nessun `object` a cui
+chiedere i campi: i nomi citabili sono quelli del **tipo degli elementi**, che il form legge da
+`getReferences` (`dataType` + `objectType` della collection scelta, output automatici compresi) — un
+`Object` propone i campi dell'entita', una `Structure` i membri della classe, la stessa strada del
+campo da sommare di un Transform. Su questa sorgente **nessuno dei due e' obbligatorio** (su una
+collection di scalari vanno lasciati vuoti) e la validazione **non li verifica**: un nome sbagliato
+ricade in silenzio sull'elemento intero. Per questo l'elenco si propone davvero, e un nome fuori
+elenco si dice come **avviso senza codice** (`unverified` dello structure member picker): accusarlo
+con `STRUCTURE_MEMBER_UNKNOWN` prometterebbe un rilievo che il backend lì non emette. `object` resta
+vuoto: valorizzarlo per far funzionare il picker sarebbe `CHOICE_SET_SOURCE_AMBIGUOUS`.
+
 *La logica dei filtri.* `filterLogic` **esiste anche sui choice set**, con le stesse forme degli
 elementi che interrogano il database: `AND` (o assente), `OR`, oppure l'espressione sugli indici
 1-based dei filtri (`1 AND (2 OR 3)`), che l'editor verifica mentre si scrive e **riscrive** quando
@@ -794,7 +827,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
@@ -911,6 +952,19 @@ flow da sé (come la demo) il tipo lo chiede lì, e lo passa a `emptyFlowDefinit
 attivazione bloccata finche' ci sono errori, eliminazione dietro una conferma esplicita che
 spiega il rischio per le esecuzioni sospese.
 
+**Eliminare il flow intero e' dell'ospite.** Il pannello versioni si ferma alla **versione**: il
+flow lo toglie chi integra, perche' il builder edita un flow già aperto e l'elenco da cui toglierlo
+e' suo. La primitiva e' `deleteFlow` (§6.2, opzionale) e la sequenza e' la parte che leggendo
+l'interfaccia non si indovina: `DELETE /flows/{name}` e' **rifiutata finche' esiste una versione
+attiva**, quindi dove c'e' si chiama prima `deactivateFlow`. Sono due chiamate e non una
+transazione — se la seconda fallisce il flow resta lì, **disattivato**, e l'elenco va ricaricato
+anche sull'errore, altrimenti mostra uno stato che sul backend non esiste piu'. Disattivare ed
+eliminare cancellano anche la presa in carico presso l'infrastruttura (§8), quindi di qui tornano gli
+stessi due errori dell'attivazione: con `MissingService` il comando si spegne — e' così che degrada
+una primitiva concreta — con `RegistrationFailed` il flow c'e' ancora e «riprova» ha senso.
+L'esempio, con la conferma in due passi, sta nella demo
+([`app.component.ts`](../flow-builder-example/src/app/app.component.ts)).
+
 **Duplica.** Il flow salvato sotto un altro nome, alla versione 1 (§6.2): il comando chiede nome
 tecnico e nome visibile della copia, e l'editor **continua sulla copia** — restare sull'originale
 farebbe finire il salvataggio successivo nel flow sbagliato. Due strade, e la differenza conta: