@noeva/etl-core 1.0.0-next.0 → 1.0.0-next.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/README.md +5 -1
  2. package/dist/cli.js +143 -117
  3. package/dist/guida/404.html +2 -2
  4. package/dist/guida/GUIDA_SVILUPPO.html +9 -6
  5. package/dist/guida/TECHNICAL_OVERVIEW.html +5 -5
  6. package/dist/guida/assets/{GUIDA_SVILUPPO.md.B_lGYssk.js → GUIDA_SVILUPPO.md.D13C7Zwu.js} +5 -2
  7. package/dist/guida/assets/{GUIDA_SVILUPPO.md.B_lGYssk.lean.js → GUIDA_SVILUPPO.md.D13C7Zwu.lean.js} +1 -1
  8. package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.C9V6rGhh.js → TECHNICAL_OVERVIEW.md.DQP0pWc8.js} +1 -1
  9. package/dist/guida/assets/{app.Bgu6oi0F.js → app.BMz6ZZYF.js} +1 -1
  10. package/dist/guida/assets/chunks/@localSearchIndexroot.B3bE99g8.js +1 -0
  11. package/dist/guida/assets/chunks/{VPLocalSearchBox.ByJkVQg0.js → VPLocalSearchBox.D8gO6gDY.js} +1 -1
  12. package/dist/guida/assets/chunks/{theme.DvCzVyXX.js → theme.DV62mViB.js} +2 -2
  13. package/dist/guida/connectors/README.html +3 -3
  14. package/dist/guida/connectors/file.html +3 -3
  15. package/dist/guida/connectors/http.html +3 -3
  16. package/dist/guida/connectors/imap.html +3 -3
  17. package/dist/guida/connectors/jira.html +3 -3
  18. package/dist/guida/connectors/noeva.html +3 -3
  19. package/dist/guida/connectors/oauth.html +3 -3
  20. package/dist/guida/connectors/postgres.html +3 -3
  21. package/dist/guida/connectors/process.html +3 -3
  22. package/dist/guida/connectors/sendgrid.html +3 -3
  23. package/dist/guida/connectors/smtp.html +3 -3
  24. package/dist/guida/connectors/sqlserver.html +3 -3
  25. package/dist/guida/conventions/node-columns.html +3 -3
  26. package/dist/guida/conventions/node-descriptor.html +3 -3
  27. package/dist/guida/conventions/run-report.html +3 -3
  28. package/dist/guida/conventions/run-trace.html +3 -3
  29. package/dist/guida/conventions/variabili-del-core.html +3 -3
  30. package/dist/guida/conventions/versioni-di-pipeline.html +3 -3
  31. package/dist/guida/guide/claude-code/index.html +3 -3
  32. package/dist/guida/guide/claude-code/prompt.html +3 -3
  33. package/dist/guida/guide/claude-code/strumenti.html +3 -3
  34. package/dist/guida/guide/grafo.html +3 -3
  35. package/dist/guida/guide/usare/app-desktop.html +3 -3
  36. package/dist/guida/guide/usare/esito-di-una-run.html +3 -3
  37. package/dist/guida/guide/usare/index.html +3 -3
  38. package/dist/guida/hashmap.json +1 -1
  39. package/dist/guida/index.html +3 -3
  40. package/dist/guida/nodes/README.html +3 -3
  41. package/dist/guida/nodes/action.html +3 -3
  42. package/dist/guida/nodes/ai.html +3 -3
  43. package/dist/guida/nodes/join.html +3 -3
  44. package/dist/guida/nodes/lookup.html +3 -3
  45. package/dist/guida/nodes/pipeline.html +3 -3
  46. package/dist/guida/nodes/route.html +3 -3
  47. package/dist/guida/nodes/sink.html +3 -3
  48. package/dist/guida/nodes/source.html +3 -3
  49. package/dist/guida/nodes/task.html +3 -3
  50. package/dist/guida/nodes/transform.html +3 -3
  51. package/dist/guida/nodes/try-catch.html +3 -3
  52. package/dist/guida/nodes/union.html +3 -3
  53. package/dist/guida/pipelines/README.html +3 -3
  54. package/dist/guida/pipelines/crm-leads-sync.html +3 -3
  55. package/dist/guida/pipelines/cross-workspace-csv-merge.html +3 -3
  56. package/dist/guida/pipelines/movimenti-per-conto.html +3 -3
  57. package/dist/guida/pipelines/orders-enriched-daily.html +3 -3
  58. package/dist/guida/pipelines/test-posta.html +3 -3
  59. package/dist/guida/runbooks/aggiornamento-pm2.html +3 -3
  60. package/dist/guida/runbooks/deployment.html +3 -3
  61. package/dist/guida/runbooks/etl-worker.html +3 -3
  62. package/dist/guida/runbooks/graph-server.html +3 -3
  63. package/dist/guida/runbooks/mask-key.html +3 -3
  64. package/dist/guida/runbooks/oauth-google-posta.html +3 -3
  65. package/dist/guida/runbooks/rollback-di-pipeline.html +3 -3
  66. package/dist/guida/runbooks/scd2-rehash.html +3 -3
  67. package/dist/guida/runbooks/sql-task-truncate-swap.html +3 -3
  68. package/dist/guida/runbooks/stato-incrementale.html +3 -3
  69. package/dist/guida/sub-pipelines/README.html +3 -3
  70. package/dist/guida/sub-pipelines/riepilogo-ordini.html +3 -3
  71. package/docs/.vitepress/lib/published-docs.ts +4 -3
  72. package/kit/blocco-agents.md +7 -1
  73. package/package.json +1 -1
  74. package/dist/guida/assets/chunks/@localSearchIndexroot.B3k7jzMh.js +0 -1
  75. /package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.C9V6rGhh.lean.js → TECHNICAL_OVERVIEW.md.DQP0pWc8.lean.js} +0 -0
@@ -9,9 +9,9 @@
9
9
  <link rel="preload stylesheet" href="/guida/core/assets/style.BNn_AkzN.css" as="style">
10
10
  <link rel="preload stylesheet" href="/guida/core/vp-icons.css" as="style">
11
11
 
12
- <script type="module" src="/guida/core/assets/app.Bgu6oi0F.js"></script>
12
+ <script type="module" src="/guida/core/assets/app.BMz6ZZYF.js"></script>
13
13
  <link rel="preload" href="/guida/core/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
14
- <link rel="modulepreload" href="/guida/core/assets/chunks/theme.DvCzVyXX.js">
14
+ <link rel="modulepreload" href="/guida/core/assets/chunks/theme.DV62mViB.js">
15
15
  <link rel="modulepreload" href="/guida/core/assets/chunks/framework.qdetmeNX.js">
16
16
  <link rel="modulepreload" href="/guida/core/assets/conventions_versioni-di-pipeline.md.cy5nsizS.lean.js">
17
17
  <link rel="icon" type="image/svg+xml" href="/guida/core/favicon.svg">
@@ -29,7 +29,7 @@
29
29
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:snapshot</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --force</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # sovrascrive uno snapshot diverso</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Situazione</th><th>Esito</th><th>Exit code</th></tr></thead><tbody><tr><td>Lo snapshot della versione corrente manca</td><td>Lo scrive in <code>versions/v&lt;N&gt;.plan.json</code>, creando la cartella</td><td>0</td></tr><tr><td>Lo snapshot c&#39;è ed è uguale al piano</td><td>Non tocca nulla e lo dice</td><td>0</td></tr><tr><td>Lo snapshot c&#39;è ed è diverso, senza <code>--force</code></td><td>Non lo sovrascrive: spiega che il piano di una versione rilasciata è congelato e serve un bump</td><td>1</td></tr><tr><td>Lo snapshot c&#39;è ed è diverso, con <code>--force</code></td><td>Lo sovrascrive: è la versione ancora in lavorazione, il cui piano cambia finché la PR non è chiusa</td><td>0</td></tr><tr><td>Nome che non è nel catalogo</td><td>Errore che elenca le pipeline del catalogo; nessun file scritto</td><td>2</td></tr><tr><td>Nome mancante, sottocomando o flag sconosciuto</td><td>Errore d&#39;uso</td><td>2</td></tr><tr><td>Cartella della pipeline non trovata (nessun <code>run.ts</code> in <code>src/pipelines/</code> che esporta la pipeline)</td><td>Errore che dice perché; nessun file scritto</td><td>2</td></tr><tr><td>Pipeline pronta in un repo cliente</td><td>Errore: la versiona il core; nessun file scritto</td><td>2</td></tr><tr><td>Lettura o scrittura su disco fallita</td><td>Errore col messaggio del sistema</td><td>1</td></tr></tbody></table><p>Il rifiuto senza <code>--force</code> esiste perché sovrascrivere in silenzio lo snapshot di una versione già rilasciata farebbe tornare verde il test del catalogo <strong>senza</strong> bump, e la versione dichiarata non direbbe più con quale piano è girata una run. <code>--force</code> da solo non basta a impedirlo, quindi lo impone il gate: lo snapshot di ogni versione che è già sulla base deve restare uguale, e uno riscritto o tolto è una violazione. <code>--force</code> serve solo alla versione che non è ancora sulla base. L&#39;unica eccezione è una versione la cui voce di changelog cambia insieme allo snapshot: il numero è passato a un&#39;altra versione, come nel back-merge di un rollback quando <code>dev</code> aveva già preso quel numero (<a href="./../runbooks/rollback-di-pipeline">runbook</a>, § 5).</p><p>Il comando trova la cartella di una pipeline importando i <code>run.ts</code> sotto <code>src/pipelines/</code> del repo e cercando quello che esporta il suo <code>RunnablePipeline</code> (vedi <a href="#in-quale-repo">In quale repo</a>).</p><h2 id="etl-versions-snapshot-realign" tabindex="-1"><code>etl versions snapshot --realign</code> <a class="header-anchor" href="#etl-versions-snapshot-realign" aria-label="Permalink to &quot;`etl versions snapshot --realign`&quot;">​</a></h2><p>Un bump del core può spostare il piano di una pipeline senza che la sua cartella cambi: un connettore che espone una colonna in più, un nodo che descrive diversamente la sua configurazione. Anche quella deriva chiede una versione di pipeline nuova, e la PR che alza il core la porta. Il comando la scrive al posto dell&#39;autore:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> versions</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> snapshot</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --realign</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --ticket</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">chiav</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><p>Per ogni pipeline versionata dal repo (le pronte no) il cui snapshot della versione corrente non coincide col piano di oggi, aggiunge al <code>changelog.ts</code> la versione successiva con la voce «Piano riallineato al core x.y.z» fra le Modifiche, il ticket, la data di oggi e <code>core</code>, e ne scrive lo snapshot. Il gate poi la tratta come ogni bump: base + 1, con la sua voce.</p><p>Prima di committare, <strong>rivedi gli snapshot nel diff</strong>: ogni spostamento dev&#39;essere spiegato dal <code>CHANGELOG.md</code> del core. Il segnale che serve arriva dalle release marcate «Cambia il piano».</p><table tabindex="0"><thead><tr><th>Situazione</th><th>Esito</th><th>Exit code</th></tr></thead><tbody><tr><td>Uno o più piani spostati</td><td>Voce e snapshot della versione nuova per ognuno, ed elenco</td><td>0</td></tr><tr><td>Nessun piano spostato</td><td>Non tocca nulla e lo dice</td><td>0</td></tr><tr><td>Lo snapshot della versione corrente di una pipeline manca</td><td>Errore che indica il comando per scriverlo; nessun file scritto</td><td>2</td></tr><tr><td><code>--ticket</code> mancante o non una chiave Jira, un nome di pipeline, <code>--force</code></td><td>Errore d&#39;uso; nessun file scritto</td><td>2</td></tr></tbody></table><p><code>--realign</code> serve alle versioni <strong>già rilasciate</strong>, il cui piano è congelato. Se la versione corrente è quella che il branch sta scrivendo, il suo snapshot si aggiorna con <code>snapshot &lt;nome&gt; --force</code>, non con una versione in più: il gate vorrebbe la base + 1, non + 2.</p><h2 id="quando-serve-un-bump" tabindex="-1">Quando serve un bump <a class="header-anchor" href="#quando-serve-un-bump" aria-label="Permalink to &quot;Quando serve un bump&quot;">​</a></h2><p>Il comportamento di una pipeline non cambia senza che cambi la sua versione. Lo verifica il <strong>gate delle versioni</strong>, <code>etl versions check</code>, in CI e in <code>etl ci</code> (nel core <code>pnpm run check</code>).</p><p><strong>File di comportamento</strong> sono tutti i file della cartella della pipeline, compreso <code>changelog.ts</code>, <strong>esclusi</strong> i test (<code>*.test.ts</code>) e gli snapshot (<code>versions/</code>). Toccare solo test o doc (le schede in <code>docs/pipelines/</code> stanno fuori dalla cartella) non chiede un bump. Un cambio fuori dalla cartella che sposta il piano (un connettore, il core) lo intercetta lo snapshot: anche quello è un bump.</p><p>Nemmeno lo <strong>scopo dei nodi</strong> chiede un bump: un file di comportamento che differisce dal merge-base solo nelle proprietà <code>purpose: &quot;&lt;stringa letterale&gt;&quot;</code> delle opzioni di un metodo del builder (<code>.source(</code>, <code>.transform(</code>, …, <code>.pipeline(</code> per lo scopo di un&#39;istanza) non conta come cambiato, e lo snapshot del piano si calcola senza gli scopi, di nodi e istanze. Il confronto è a token, quindi ignora anche gli spazi e le virgole finali che Prettier sposta quando aggiunge l&#39;opzione; un <code>{ purpose }</code> rimasto vuoto vale come opzione tolta. Per dare uno scopo a un nodo con opzioni calcolate, stendile in un oggetto: <code>{ ...opzioni, purpose: &quot;…&quot; }</code> vale <code>opzioni</code>, ma solo se accanto allo spread c&#39;è lo scopo e nient&#39;altro. Uno scopo scritto con una costante, una concatenazione o un template con interpolazione invece non si riconosce, e conta come modifica: scrivilo letterale. Un <code>purpose</code> fuori dalle opzioni del builder (un campo di un record, il parametro di una query) è un dato, e il suo cambio chiede il bump. Ne segue anche che un cambio di soli spazi fuori dalle stringhe non chiede un bump, tranne gli a capo che decidono il punto e virgola automatico.</p><p>Se un file di comportamento differisce dalla <strong>base</strong>, la pipeline deve dichiarare <strong>la versione della base più uno</strong>, con la sua voce nel changelog e almeno una riga fra Aggiunte, Modifiche e Rimozioni. Una pipeline che sulla base non c&#39;è, non è ancora versionata o è stata rinominata (un altro nome nello snapshot della base), parte dalla <strong>v1</strong>.</p><p><strong>Senza base restano solo gli snapshot.</strong> Se il riferimento che la mappa qui sotto chiede non c&#39;è (un repo cliente appena creato con <code>etl init</code> e mai pubblicato, il bootstrap di un repo migrato, un clone senza <code>origin/dev</code>), non c&#39;è niente da confrontare: il gate lo dice con un avviso, <code>nessuna base (origin/dev): niente da confrontare</code>, e salta i controlli che leggono la base (il bump richiesto, la versione uguale a base + 1, gli snapshot già sulla base). Applicare lì «nuova ⇒ v1» farebbe fallire il bootstrap di una pipeline che arriva dal core già alla v2 o oltre. Lo snapshot della versione corrente invece si confronta col piano anche senza base, perché la base non serve per saperlo: in un repo appena migrato uno snapshot che non coincide, o che manca, è rosso subito e non al primo push. Dove il gate deve valere tutto la base va scaricata: in CI con il checkout a <code>fetch-depth: 0</code>, in locale con <code>git fetch origin dev main</code>. Una base indicata a mano con <code>--base</code> che non c&#39;è resta un errore.</p><table tabindex="0"><thead><tr><th>Branch</th><th>Base</th></tr></thead><tbody><tr><td><code>hotfix/*</code> diretto a <code>main</code> (o senza PR: in locale, sui push), e <code>main</code> stesso</td><td><code>origin/main</code></td></tr><tr><td>tutti gli altri, compreso il back-merge di un <code>hotfix/*</code> verso <code>dev</code> o <code>staging</code></td><td><code>origin/dev</code></td></tr></tbody></table><p>La base è <code>origin/dev</code> anche quando la PR va verso un branch di feature: così tutti i ticket di una feature che toccano la stessa pipeline <strong>condividono un solo bump</strong>, il primo che lo scrive, e gli altri lo trovano già fatto. Su un <code>hotfix/*</code> il numero si conta da <code>main</code>, perché è lì che il codice torna; la sua PR di back-merge verso <code>dev</code> invece si confronta con <code>dev</code>, ed è lì che una collisione col numero già preso da <code>dev</code> chiede di rinumerare. Su <code>main</code> il codice è già in produzione: il confronto con sé stesso lascia solo il controllo dello snapshot.</p><p>I file cambiati si contano dal <strong>merge-base</strong> con la base, la versione della base si legge <strong>in cima</strong> alla base. Ne segue che:</p><ul><li>un branch rimasto indietro non risponde delle pipeline che <code>dev</code> ha cambiato dopo: non le ha toccate, e il gate non le guarda;</li><li>due PR in parallelo che rivendicano lo stesso numero <strong>si scontrano</strong>: quando la prima entra in <code>dev</code>, la seconda va in rosso finché non allinea il branch e rinumera la sua voce. È lo stesso fenomeno dei numeri degli ADR, reso rosso invece che silenzioso.</li></ul><p>Una cartella <strong>spostata</strong> non perde la sua storia. Se sulla base <code>changelog.ts</code> non c&#39;è nel percorso nuovo, il gate chiede a git da quale cartella vengono i file spostati (basta che ne riconosca uno, anche se il changelog è stato riscritto dal bump) e legge la versione lì. In locale sposta con <code>git mv</code>, o fai <code>git add -A</code> prima del gate: git riconosce uno spostamento solo fra file in indice, mentre in CI è tutto già committato. Lo spostamento muove file di comportamento, quindi chiede un bump, con una voce che lo dice.</p><p>Una pipeline <strong>rinominata</strong> invece è una pipeline nuova e riparte dalla v1, anche se la cartella resta la stessa: la dichiarazione della base conta solo se è della stessa pipeline, e lo dice il nome nello snapshot della base, che il test del catalogo vuole uguale al nome nel catalogo.</p><p>Il gate non vede un cambio del core che altera il comportamento <strong>senza</strong> cambiare il piano: per scelta, lo rende visibile il report di run, che porta sia la versione sia la release.</p><h3 id="il-changelog-contiene-solo-dati" tabindex="-1">Il changelog contiene solo dati <a class="header-anchor" href="#il-changelog-contiene-solo-dati" aria-label="Permalink to &quot;Il changelog contiene solo dati&quot;">​</a></h3><p>Il gate legge la versione della base importando il <code>changelog.ts</code> di quel commit, da solo, fuori dal repo. Per questo <code>changelog.ts</code> contiene solo dati: sono ammessi gli import di <strong>tipo</strong> (<code>import type { PipelineChangelog } …</code>), che spariscono; un import di valore non si risolverebbe e il gate si fermerebbe col percorso del file.</p><h2 id="etl-versions-check" tabindex="-1"><code>etl versions check</code> <a class="header-anchor" href="#etl-versions-check" aria-label="Permalink to &quot;`etl versions check`&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:check</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # alias di: pnpm run etl versions check</span></span>
30
30
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:check</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --base</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> origin/staging</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # confronta con un&#39;altra base</span></span></code></pre></div><p>Per ogni pipeline del catalogo raccoglie i file cambiati dal merge-base (committati, modificati e nuovi non ancora aggiunti), la dichiarazione sulla base e lo snapshot, e li passa alla decisione pura in <code>src/versions/version-gate.ts</code>. Prima toglie dai file cambiati quelli di comportamento che differiscono dal merge-base solo negli scopi dei nodi (vedi <a href="#quando-serve-un-bump">Quando serve un bump</a>). Elenca tutte le violazioni in una volta, ognuna con la pipeline e cosa fare. Le pipeline pronte senza cartella le salta, e l&#39;intestazione le elenca. Il branch lo legge da <code>GITHUB_HEAD_REF</code> (le PR, dove il checkout è il merge commit a HEAD staccato), poi da <code>GITHUB_REF_NAME</code> (i push), poi da git; il branch di destinazione di una PR da <code>GITHUB_BASE_REF</code>.</p><table tabindex="0"><thead><tr><th>Messaggio</th><th>Cosa fare</th></tr></thead><tbody><tr><td><code>i file di comportamento sono cambiati … ancora la vN</code></td><td>Aggiungi la voce vN+1 al changelog e lancia <code>pnpm run pipeline:snapshot &lt;nome&gt;</code>.</td></tr><tr><td><code>dichiara la vX, ma su origin/dev è alla vB</code></td><td>Il numero è sbagliato: è vB+1. Se la base è andata avanti, <code>git merge origin/dev</code> e rinumera la voce.</td></tr><tr><td><code>su origin/dev è nuova (…), quindi parte dalla v1</code></td><td>Una pipeline nuova, o rinominata, ha la sola voce v1.</td></tr><tr><td><code>la vN è già presa su origin/dev da un&#39;altra modifica</code></td><td>Un&#39;altra PR è entrata prima con lo stesso numero: <code>git merge origin/dev</code>, porta la tua voce alla vN+1, snapshot.</td></tr><tr><td><code>il changelog non ha la voce vN</code></td><td>La versione dichiarata deve avere la sua voce.</td></tr><tr><td><code>la voce vN ha Aggiunte, Modifiche e Rimozioni tutte vuote</code></td><td>Scrivi cosa cambia e perché.</td></tr><tr><td><code>manca lo snapshot</code> / <code>il piano non coincide con lo snapshot</code></td><td>Come per il test del catalogo: vedi <a href="#quando-il-test-e-rosso">Quando il test è rosso</a>.</td></tr><tr><td><code>lo snapshot della vN è già su origin/dev e qui è stato riscritto o tolto</code></td><td>Ripristinalo dalla base (<code>git checkout origin/dev -- &lt;cartella&gt;/versions/vN.plan.json</code>). Se il piano è cambiato, serve un bump.</td></tr></tbody></table><table tabindex="0"><thead><tr><th>Situazione</th><th>Exit code</th></tr></thead><tbody><tr><td>Nessuna violazione</td><td>0</td></tr><tr><td>Nessuna base della mappa dei branch: avviso «nessuna base», snapshot della versione corrente a posto</td><td>0</td></tr><tr><td>Almeno una violazione, anche senza base (solo snapshot mancante o diverso dal piano)</td><td>1</td></tr><tr><td>Base data con <code>--base</code> che non c&#39;è, storia insufficiente, git che fallisce, flag sbagliato</td><td>2</td></tr><tr><td><code>changelog.ts</code> o snapshot del piano della base che non si importa, non è JSON o non ha la forma attesa</td><td>2</td></tr></tbody></table><p>In CI il gate è un passo del workflow <code>ci.yml</code>, dopo i test; in un repo cliente è una fase di <code>etl ci</code>, che il <code>ci.yml</code> del boilerplate lancia dopo il setup. Il checkout usa <code>fetch-depth: 0</code>: senza, mancherebbero <code>origin/dev</code>, <code>origin/main</code> e la storia per il merge-base. La CI gira sulle PR verso <code>dev</code> e <code>main</code> e sui push su <code>main</code>; le PR verso un branch di feature non hanno CI, quindi lì il gate si lancia in locale con <code>etl ci</code> (nel core <code>pnpm run check</code>), e in CI scatta sulla PR finale verso <code>dev</code>.</p><h2 id="etl-versions-rollback" tabindex="-1"><code>etl versions rollback</code> <a class="header-anchor" href="#etl-versions-rollback" aria-label="Permalink to &quot;`etl versions rollback`&quot;">​</a></h2><p>Riporta il codice di <strong>una sola</strong> pipeline a una sua versione andata in produzione. La procedura completa, dalla PR di hotfix al back-merge, è nel runbook <a href="./../runbooks/rollback-di-pipeline">Rollback di una pipeline</a>.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:rollback</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">N</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --motivo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&lt;testo&gt;&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --ticket</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">chiav</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # alias di: pnpm run etl versions rollback …</span></span>
31
31
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:rollback</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">N</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --motivo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&lt;testo&gt;&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --ticket</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">chiav</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --workspace</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><p>Il <strong>piano</strong> lo decide una funzione pura, <code>src/versions/rollback-plan.ts</code>; il comando raccoglie i fatti da git e lo esegue:</p><ul><li><strong>la vN</strong> è quella dell&#39;<strong>ultimo</strong> commit di <code>origin/main</code> che la dichiarava, cercato solo fra i commit che <code>main</code> ha avuto in cima (<code>git log --first-parent</code>): una versione entrata con un merge e già superata nel suo branch non è mai stata in produzione. Risalendo la storia una versione può solo scendere; se sale, la cartella ospitava una pipeline poi rinominata, e lì la ricerca si ferma;</li><li><strong>il numero nuovo</strong> è la versione corrente su <code>main</code> più uno, non la vN: la voce ha <code>rollbackTo</code> con la vN e il motivo, il ticket di <code>--ticket</code>, la data di oggi, la versione del core installata (<code>core</code>), e una riga fra le Modifiche che dice quali versioni si ritirano;</li><li>crea <code>hotfix/rollback-&lt;pipeline&gt;-v&lt;N&gt;</code> da <code>origin/main</code> e riporta la cartella della pipeline com&#39;era su quel commit, <strong>esclusi</strong> <code>changelog.ts</code> e <code>versions/</code>, che restano quelli di <code>main</code> perché portano la storia arrivata dopo. Aggiunge la voce in fondo a <code>changelog.ts</code>, nella forma che Prettier lascerebbe;</li><li>rigenera lo snapshot della versione nuova con <code>etl versions snapshot</code> <strong>in un processo a parte</strong>, lanciato con la CLI dello stesso pacchetto e lo stesso <code>etl.config.ts</code>: il codice ripristinato si carica solo lì;</li><li><strong>confronta il core</strong> della voce della vN, se la registra, con quello installato: la cartella ripristinata gira sul core di oggi, e se i due differiscono il piano può non essere quello della vN. La riga <strong>Core</strong> del resoconto lo dice;</li><li><strong>legge</strong> lo stato di pipeline (locale, o del workspace con <code>--workspace</code>) e confronta le source degli snapshot della versione ritirata e della vN: elenca lo stato salvato, le source che la versione ritirata aggiungeva o toglieva, e lo stato di nodi che nella vN non sono source. Si guardano le source perché solo loro hanno stato; il piano non dice quali dichiarano un watermark, quindi una source toccata compare anche senza stato salvato.</li></ul><p>Se lo stato non si legge (l&#39;API del workspace non risponde) il rollback va avanti lo stesso, e il resoconto dice il comando <code>etl state show</code> per leggerlo prima di aprire la PR: lo stato serve a decidere cosa dichiarare, non a preparare il branch.</p><p>Non committa, non pusha, e non scrive né dati né stato.</p><table tabindex="0"><thead><tr><th>Situazione</th><th>Esito</th><th>Exit code</th></tr></thead><tbody><tr><td>Rollback preparato</td><td>Branch creato, cartella ripristinata, voce e snapshot scritti; stampa stato e prossimi passi</td><td>0</td></tr><tr><td>Lo snapshot non si genera (la cartella vecchia non gira contro il core di oggi)</td><td>Branch, cartella e voce restano: l&#39;errore del processo figlio e cosa fare</td><td>1</td></tr><tr><td>Pipeline fuori dal catalogo, nome o versione mancanti, versione non intera, flag sconosciuto</td><td>Errore d&#39;uso</td><td>2</td></tr><tr><td>Pipeline pronta in un repo cliente</td><td>Errore che indica il rollback del deploy e il downgrade del core</td><td>2</td></tr><tr><td><code>--motivo</code> mancante o vuoto, <code>--ticket</code> mancante o non una chiave Jira</td><td>Errore d&#39;uso, prima di leggere git</td><td>2</td></tr><tr><td>vN mai stata in cima a <code>main</code>, uguale alla versione corrente o successiva</td><td>Errore che elenca le versioni che <code>main</code> ha avuto</td><td>2</td></tr><tr><td>Pipeline senza <code>changelog.ts</code> su <code>origin/main</code>, o <code>origin/main</code> assente (<code>git fetch origin</code>)</td><td>Errore che dice perché</td><td>2</td></tr><tr><td><code>changelog.ts</code> di <code>main</code> senza la forma attesa (l&#39;array chiuso da <code>];</code> a inizio riga)</td><td>Errore: la voce va scritta a mano</td><td>2</td></tr><tr><td>Modifiche non committate, o <code>hotfix/rollback-&lt;pipeline&gt;-v&lt;N&gt;</code> che esiste già</td><td>Errore, prima di cambiare branch</td><td>2</td></tr></tbody></table><p>Ogni esito con exit 2 arriva <strong>prima</strong> di toccare branch e file.</p><h2 id="la-sezione-versioni-della-scheda" tabindex="-1">La sezione Versioni della scheda <a class="header-anchor" href="#la-sezione-versioni-della-scheda" aria-label="Permalink to &quot;La sezione Versioni della scheda&quot;">​</a></h2><p>La scheda di ogni pipeline (<code>docs/pipelines/</code>) chiude con una sezione <code>## Versioni</code> e il componente <code>&lt;PipelineVersions name=&quot;&lt;pipeline&gt;&quot; /&gt;</code>. Mostra la storia completa, dalla versione più recente:</p><ul><li>la voce del changelog scritta dall&#39;autore, cioè il <strong>perché</strong>: Aggiunte, Modifiche e Rimozioni, il ticket, la data e, per una voce nata da un rollback, la versione a cui si torna e il motivo;</li><li>sotto, il <strong>diff generato</strong> rispetto alla versione precedente, cioè il <strong>cosa</strong>: nodi, archi e colonne per nodo aggiunti, cambiati e rimossi, calcolato dagli snapshot <code>v&lt;N-1&gt;</code> e <code>v&lt;N&gt;</code>. La v1 non ha una versione precedente, e la scheda lo dice.</li></ul><p>Nodi e archi si confrontano per <code>id</code>, le colonne per <code>id</code> dentro il loro nodo. Un arco che cambia estremi o porta cambia anche <code>id</code>, quindi compare come rimosso più aggiunto; un arco con lo stesso <code>id</code> e un <code>joinType</code> o un tipo diverso è cambiato.</p><p>Una versione è marcata <strong>«rompe il contratto»</strong> quando una colonna di un nodo <strong>sink</strong> della versione precedente sparisce, cambia nome o cambia <code>dataType</code>: chi legge le tabelle a valle se ne deve accorgere. Il nome conta anche quando l&#39;<code>id</code> della colonna resta lo stesso, perché a valle si legge il nome. Vale anche quando sparisce il sink intero, o quando il nodo smette di essere un sink: le sue colonne non escono più. Una colonna aggiunta, una che cambia solo chiave, o un cambio su un nodo che non è sink non rompono il contratto.</p><p>Il diff lo calcola <code>etl docs build</code> a build time, e il loader della doc lo legge dal file del sito. Nella guida del core lo calcola per le schede che la guida pubblica, cioè le pipeline pronte e gli esempi. Uno snapshot non valido ferma la build col suo percorso, uno mancante col comando che lo scrive, invece di mostrare un diff inventato.</p><h2 id="una-pipeline-nuova" tabindex="-1">Una pipeline nuova <a class="header-anchor" href="#una-pipeline-nuova" aria-label="Permalink to &quot;Una pipeline nuova&quot;">​</a></h2><p>Parte dalla v1: <code>changelog.ts</code> con la sola voce v1, poi <code>pnpm run pipeline:snapshot &lt;nome&gt;</code> dopo averla aggiunta al catalogo in <code>etl.config.ts</code>. Lo scaffold <code>/new-pipeline</code> fa entrambe le cose.</p><h2 id="riferimenti" tabindex="-1">Riferimenti <a class="header-anchor" href="#riferimenti" aria-label="Permalink to &quot;Riferimenti&quot;">​</a></h2><ul><li>Codice: <code>src/versions/changelog.ts</code> (il changelog), <code>src/versions/plan-snapshot.ts</code> (snapshot e confronto), <code>src/versions/plan-diff.ts</code> (il diff fra due piani e «rompe il contratto»), <code>src/versions/pipeline-dirs.ts</code> (la cartella di una pipeline), <code>src/versions/core-version.ts</code> (la versione del core installata), <code>src/versions/version-gate.ts</code> (la decisione del gate), <code>src/versions/rollback-plan.ts</code> (il piano di rollback), <code>src/versions/changelog-source.ts</code> (la voce aggiunta al testo di <code>changelog.ts</code>), <code>src/versions/purpose-diff.ts</code> (il confronto a token che ignora gli scopi di nodi e istanze), <code>src/cli-versions.ts</code> (i comandi), <code>src/cli-versions-check.ts</code> (l&#39;adattatore git del gate), <code>src/cli-versions-realign.ts</code> (<code>snapshot --realign</code>), <code>src/cli-versions-rollback.ts</code> (l&#39;adattatore del rollback, con <code>-io.ts</code> per git e il processo figlio e <code>-report.ts</code> per il resoconto), <code>.github/workflows/ci.yml</code> (il passo in CI).</li><li>Doc: <code>docs/.vitepress/lib/pipeline-versions.ts</code> (la storia per la scheda), <code>docs/.vitepress/lib/pipeline-diagrams.ts</code> (grafi e storia, che <code>src/docs/sito.ts</code> calcola per <code>etl docs</code>), <code>docs/.vitepress/data/pipelines.data.ts</code> (il loader, che li legge dal file del sito), <code>docs/.vitepress/theme/components/PipelineVersions.vue</code> (il componente).</li><li>Test: <code>src/catalog/catalogo-del-core.test.ts</code> (snapshot di ogni pipeline del catalogo del core), <code>tests/cli/catalog-check.test.ts</code> (il changelog, con <code>etl catalog check</code>), <code>src/versions/version-gate.test.ts</code> (i casi del gate), <code>src/versions/purpose-diff.test.ts</code> (cosa conta come cambio a meno degli scopi), <code>src/cli-versions-check.test.ts</code> (il comando su un git finto), <code>tests/integration/versions-check.integration.test.ts</code> (il comando su un repository git temporaneo, in <code>pnpm run test:integration</code>), <code>src/versions/rollback-plan.test.ts</code> (i casi del piano), <code>src/cli-versions-rollback.test.ts</code> (il comando su un git finto), <code>src/cli-versions-rollback-io.test.ts</code> (git e processo figlio), <code>tests/integration/versions-rollback.integration.test.ts</code> (il comando su un repository git temporaneo), <code>tests/cli/versions-repo-cliente.test.ts</code> (gate, pronte, <code>--realign</code> e rollback attraverso la CLI, su un repo cliente con <code>dev</code>, <code>staging</code> e <code>main</code>), <code>src/versions/plan-diff.test.ts</code> (il diff), <code>docs/.vitepress/lib/pipeline-cards.test.ts</code> (ogni scheda ha <code>&lt;PipelineVersions&gt;</code>).</li></ul></div></div></main><footer class="VPDocFooter" data-v-303c7d43 data-v-64d0b887><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-64d0b887><span class="visually-hidden" id="doc-footer-aria-label" data-v-64d0b887>Pager</span><div class="pager" data-v-64d0b887><a class="VPLink link pager-link prev" href="/guida/core/conventions/run-trace" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina precedente</span><span class="title" data-v-64d0b887>La traccia di una run</span><!--]--></a></div><div class="pager" data-v-64d0b887><a class="VPLink link pager-link next" href="/guida/core/conventions/node-descriptor" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina successiva</span><span class="title" data-v-64d0b887>Descriptor dei nodi</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooter has-sidebar" data-v-f5dee57d data-v-e10de3dd><div class="container" data-v-e10de3dd><p class="message" data-v-e10de3dd>Noeva è un marchio registrato di 4D S.R.L.</p><p class="copyright" data-v-e10de3dd>© 2026 4D S.R.L. · Gruppo4D</p></div></footer><!--[--><span hidden></span><!--]--></div></div>
32
- <script>window.__VP_HASH_MAP__=JSON.parse("{\"connectors_file.md\":\"B1NJe0VJ\",\"connectors_http.md\":\"B8utPijY\",\"connectors_imap.md\":\"CMMpZVXn\",\"connectors_jira.md\":\"0DJvrRXH\",\"connectors_noeva.md\":\"DkxCC8Ey\",\"connectors_oauth.md\":\"DUHajB0u\",\"connectors_postgres.md\":\"DPpHqXkc\",\"connectors_process.md\":\"lQLmWbGN\",\"connectors_readme.md\":\"ChyXSf73\",\"connectors_sendgrid.md\":\"dJzIWepq\",\"connectors_smtp.md\":\"DXXvaNxD\",\"connectors_sqlserver.md\":\"D1sYNLEq\",\"conventions_node-columns.md\":\"D9K1peUx\",\"conventions_node-descriptor.md\":\"D8Si7E2S\",\"conventions_run-report.md\":\"D_pG07VG\",\"conventions_run-trace.md\":\"nKS_RgLC\",\"conventions_variabili-del-core.md\":\"BU6BD6w_\",\"conventions_versioni-di-pipeline.md\":\"cy5nsizS\",\"guida_sviluppo.md\":\"B_lGYssk\",\"guide_claude-code_index.md\":\"CxVSru8e\",\"guide_claude-code_prompt.md\":\"C7uETA9W\",\"guide_claude-code_strumenti.md\":\"BWhQnAlY\",\"guide_grafo.md\":\"Dy8_YMeh\",\"guide_usare_app-desktop.md\":\"CcDu8cJL\",\"guide_usare_esito-di-una-run.md\":\"DkvAOPBE\",\"guide_usare_index.md\":\"BJqi3P7J\",\"index.md\":\"kMhsF-sv\",\"nodes_action.md\":\"DOsTbV-i\",\"nodes_ai.md\":\"CVtP9gEJ\",\"nodes_join.md\":\"DSYbIDG6\",\"nodes_lookup.md\":\"BI8tgBIq\",\"nodes_pipeline.md\":\"DIMlyprm\",\"nodes_readme.md\":\"CHGy_go6\",\"nodes_route.md\":\"Bt9qH6OA\",\"nodes_sink.md\":\"yAf_z4wO\",\"nodes_source.md\":\"V_vlNfOz\",\"nodes_task.md\":\"Dk6VB7as\",\"nodes_transform.md\":\"Bv5fg2Xx\",\"nodes_try-catch.md\":\"DCYydDPm\",\"nodes_union.md\":\"CznVzHTK\",\"pipelines_crm-leads-sync.md\":\"BlZUnxYn\",\"pipelines_cross-workspace-csv-merge.md\":\"CsRE6GNe\",\"pipelines_movimenti-per-conto.md\":\"DRGfO1_5\",\"pipelines_orders-enriched-daily.md\":\"jESRtvBo\",\"pipelines_readme.md\":\"Ee6LS-SU\",\"pipelines_test-posta.md\":\"Cxo_DGBs\",\"runbooks_aggiornamento-pm2.md\":\"f3LAxif4\",\"runbooks_deployment.md\":\"DvIOOsoG\",\"runbooks_etl-worker.md\":\"Bu05cEgT\",\"runbooks_graph-server.md\":\"BOXZqdXC\",\"runbooks_mask-key.md\":\"nZkhAjBf\",\"runbooks_oauth-google-posta.md\":\"Bs7QTkmU\",\"runbooks_rollback-di-pipeline.md\":\"6US0Wsdc\",\"runbooks_scd2-rehash.md\":\"DtmuXA67\",\"runbooks_sql-task-truncate-swap.md\":\"C8viT-fp\",\"runbooks_stato-incrementale.md\":\"hGZ8FlbZ\",\"sub-pipelines_readme.md\":\"CF8gmNPU\",\"sub-pipelines_riepilogo-ordini.md\":\"qCBZJ4nh\",\"technical_overview.md\":\"C9V6rGhh\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"it-IT\",\"dir\":\"ltr\",\"title\":\"Noeva ETL\",\"titleTemplate\":\":title · Noeva ETL\",\"description\":\"Documentazione di Noeva ETL: come usare la piattaforma e come creare pipeline con Claude Code.\",\"base\":\"/guida/core/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":{\"light\":\"/logo-dark.png\",\"dark\":\"/logo-light.png\",\"alt\":\"Noeva\"},\"siteTitle\":false,\"footer\":{\"message\":\"Noeva è un marchio registrato di 4D S.R.L.\",\"copyright\":\"© 2026 4D S.R.L. · Gruppo4D\"},\"outline\":{\"level\":[2,3],\"label\":\"In questa pagina\"},\"docFooter\":{\"prev\":\"Pagina precedente\",\"next\":\"Pagina successiva\"},\"darkModeSwitchLabel\":\"Tema\",\"lightModeSwitchTitle\":\"Passa al tema chiaro\",\"darkModeSwitchTitle\":\"Passa al tema scuro\",\"sidebarMenuLabel\":\"Menu\",\"returnToTopLabel\":\"Torna su\",\"langMenuLabel\":\"Lingua\",\"notFound\":{\"title\":\"PAGINA NON TROVATA\",\"quote\":\"Il documento che cercavi non c'è più, o non è mai stato pubblicato qui.\",\"linkLabel\":\"Torna alla home\",\"linkText\":\"Torna alla home\"},\"search\":{\"provider\":\"local\",\"options\":{\"translations\":{\"button\":{\"buttonText\":\"Cerca\",\"buttonAriaLabel\":\"Cerca nella documentazione\"},\"modal\":{\"displayDetails\":\"Mostra i dettagli\",\"resetButtonTitle\":\"Azzera la ricerca\",\"backButtonTitle\":\"Chiudi la ricerca\",\"noResultsText\":\"Nessun risultato per\",\"footer\":{\"selectText\":\"per aprire\",\"selectKeyAriaLabel\":\"invio\",\"navigateText\":\"per spostarti\",\"navigateUpKeyAriaLabel\":\"freccia su\",\"navigateDownKeyAriaLabel\":\"freccia giù\",\"closeText\":\"per chiudere\",\"closeKeyAriaLabel\":\"esc\"}}}}},\"nav\":[{\"text\":\"Usare\",\"link\":\"/guide/usare/\",\"activeMatch\":\"^/guide/usare/\"},{\"text\":\"Creare con Claude Code\",\"link\":\"/guide/claude-code/\",\"activeMatch\":\"^/guide/claude-code/\"},{\"text\":\"Riferimento\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Tipi di nodo\",\"link\":\"/nodes/README\"},{\"text\":\"Connettori\",\"link\":\"/connectors/README\"},{\"text\":\"Pipeline pronte\",\"link\":\"/pipelines/README\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"},{\"text\":\"Operatività\",\"link\":\"/runbooks/graph-server\"}]}],\"sidebar\":[{\"text\":\"Usare Noeva ETL\",\"items\":[{\"text\":\"Come si usa\",\"link\":\"/guide/usare/\"},{\"text\":\"L'app desktop\",\"link\":\"/guide/usare/app-desktop\"},{\"text\":\"Leggere l'esito di una run\",\"link\":\"/guide/usare/esito-di-una-run\"},{\"text\":\"Panoramica di prodotto\",\"link\":\"/TECHNICAL_OVERVIEW\"}]},{\"text\":\"Creare con Claude Code\",\"items\":[{\"text\":\"Dal bisogno al processo\",\"link\":\"/guide/claude-code/\"},{\"text\":\"Comporre il prompt\",\"link\":\"/guide/claude-code/prompt\"},{\"text\":\"Skill e subagent\",\"link\":\"/guide/claude-code/strumenti\"},{\"text\":\"Guida allo sviluppo\",\"link\":\"/GUIDA_SVILUPPO\"}]},{\"text\":\"Concetti\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Versioni di pipeline\",\"link\":\"/conventions/versioni-di-pipeline\"},{\"text\":\"Descriptor dei nodi\",\"link\":\"/conventions/node-descriptor\"},{\"text\":\"Colonne dei nodi\",\"link\":\"/conventions/node-columns\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"}]},{\"text\":\"Tipi di nodo\",\"collapsed\":true,\"items\":[{\"text\":\"Cheatsheet\",\"link\":\"/nodes/README\"},{\"text\":\"action\",\"link\":\"/nodes/action\"},{\"text\":\"ai\",\"link\":\"/nodes/ai\"},{\"text\":\"join\",\"link\":\"/nodes/join\"},{\"text\":\"lookup\",\"link\":\"/nodes/lookup\"},{\"text\":\"pipeline\",\"link\":\"/nodes/pipeline\"},{\"text\":\"route\",\"link\":\"/nodes/route\"},{\"text\":\"sink\",\"link\":\"/nodes/sink\"},{\"text\":\"source\",\"link\":\"/nodes/source\"},{\"text\":\"task\",\"link\":\"/nodes/task\"},{\"text\":\"transform\",\"link\":\"/nodes/transform\"},{\"text\":\"try-catch\",\"link\":\"/nodes/try-catch\"},{\"text\":\"union\",\"link\":\"/nodes/union\"}]},{\"text\":\"Connettori\",\"collapsed\":true,\"items\":[{\"text\":\"Panoramica\",\"link\":\"/connectors/README\"},{\"text\":\"File (storage × codec)\",\"link\":\"/connectors/file\"},{\"text\":\"HTTP (API REST per i nodi lookup e action)\",\"link\":\"/connectors/http\"},{\"text\":\"IMAP (caselle di posta)\",\"link\":\"/connectors/imap\"},{\"text\":\"Jira Cloud (issue da una JQL o per chiave, liste di una issue, creazione, aggiornamento, transizioni, upsert, commenti, worklog e link)\",\"link\":\"/connectors/jira\"},{\"text\":\"Noeva (file dei workspace)\",\"link\":\"/connectors/noeva\"},{\"text\":\"OAuth2 per i connettori di posta\",\"link\":\"/connectors/oauth\"},{\"text\":\"PostgreSQL\",\"link\":\"/connectors/postgres\"},{\"text\":\"processo esterno\",\"link\":\"/connectors/process\"},{\"text\":\"SendGrid (mail via API REST)\",\"link\":\"/connectors/sendgrid\"},{\"text\":\"SMTP (notifiche email)\",\"link\":\"/connectors/smtp\"},{\"text\":\"SQL Server\",\"link\":\"/connectors/sqlserver\"}]},{\"text\":\"Pipeline pronte\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una pipeline\",\"link\":\"/pipelines/README\"},{\"text\":\"test-posta\",\"link\":\"/pipelines/test-posta\"}]},{\"text\":\"Esempi\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una sub-pipeline\",\"link\":\"/sub-pipelines/README\"},{\"text\":\"crm-leads-sync\",\"link\":\"/pipelines/crm-leads-sync\"},{\"text\":\"cross-workspace-csv-merge\",\"link\":\"/pipelines/cross-workspace-csv-merge\"},{\"text\":\"movimenti-per-conto\",\"link\":\"/pipelines/movimenti-per-conto\"},{\"text\":\"orders-enriched-daily\",\"link\":\"/pipelines/orders-enriched-daily\"},{\"text\":\"riepilogo-ordini\",\"link\":\"/sub-pipelines/riepilogo-ordini\"}]},{\"text\":\"Operatività\",\"collapsed\":true,\"items\":[{\"text\":\"aggiornare un deploy PM2 di un repo cliente\",\"link\":\"/runbooks/aggiornamento-pm2\"},{\"text\":\"distribuzione del runner ETL\",\"link\":\"/runbooks/deployment\"},{\"text\":\"worker etl worker (polling su processes)\",\"link\":\"/runbooks/etl-worker\"},{\"text\":\"server grafi etl serve (HTTP)\",\"link\":\"/runbooks/graph-server\"},{\"text\":\"chiavi di mask (creazione, rotazione, compromissione)\",\"link\":\"/runbooks/mask-key\"},{\"text\":\"OAuth2 per una casella Google (IMAP + SMTP)\",\"link\":\"/runbooks/oauth-google-posta\"},{\"text\":\"rollback di una pipeline\",\"link\":\"/runbooks/rollback-di-pipeline\"},{\"text\":\"rehash di una dimensione storicizzata\",\"link\":\"/runbooks/scd2-rehash\"},{\"text\":\"task SQL, truncate e scambio di tabelle\",\"link\":\"/runbooks/sql-task-truncate-swap\"},{\"text\":\"stato di pipeline e watermark\",\"link\":\"/runbooks/stato-incrementale\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
32
+ <script>window.__VP_HASH_MAP__=JSON.parse("{\"connectors_file.md\":\"B1NJe0VJ\",\"connectors_http.md\":\"B8utPijY\",\"connectors_imap.md\":\"CMMpZVXn\",\"connectors_jira.md\":\"0DJvrRXH\",\"connectors_noeva.md\":\"DkxCC8Ey\",\"connectors_oauth.md\":\"DUHajB0u\",\"connectors_postgres.md\":\"DPpHqXkc\",\"connectors_process.md\":\"lQLmWbGN\",\"connectors_readme.md\":\"ChyXSf73\",\"connectors_sendgrid.md\":\"dJzIWepq\",\"connectors_smtp.md\":\"DXXvaNxD\",\"connectors_sqlserver.md\":\"D1sYNLEq\",\"conventions_node-columns.md\":\"D9K1peUx\",\"conventions_node-descriptor.md\":\"D8Si7E2S\",\"conventions_run-report.md\":\"D_pG07VG\",\"conventions_run-trace.md\":\"nKS_RgLC\",\"conventions_variabili-del-core.md\":\"BU6BD6w_\",\"conventions_versioni-di-pipeline.md\":\"cy5nsizS\",\"guida_sviluppo.md\":\"D13C7Zwu\",\"guide_claude-code_index.md\":\"CxVSru8e\",\"guide_claude-code_prompt.md\":\"C7uETA9W\",\"guide_claude-code_strumenti.md\":\"BWhQnAlY\",\"guide_grafo.md\":\"Dy8_YMeh\",\"guide_usare_app-desktop.md\":\"CcDu8cJL\",\"guide_usare_esito-di-una-run.md\":\"DkvAOPBE\",\"guide_usare_index.md\":\"BJqi3P7J\",\"index.md\":\"kMhsF-sv\",\"nodes_action.md\":\"DOsTbV-i\",\"nodes_ai.md\":\"CVtP9gEJ\",\"nodes_join.md\":\"DSYbIDG6\",\"nodes_lookup.md\":\"BI8tgBIq\",\"nodes_pipeline.md\":\"DIMlyprm\",\"nodes_readme.md\":\"CHGy_go6\",\"nodes_route.md\":\"Bt9qH6OA\",\"nodes_sink.md\":\"yAf_z4wO\",\"nodes_source.md\":\"V_vlNfOz\",\"nodes_task.md\":\"Dk6VB7as\",\"nodes_transform.md\":\"Bv5fg2Xx\",\"nodes_try-catch.md\":\"DCYydDPm\",\"nodes_union.md\":\"CznVzHTK\",\"pipelines_crm-leads-sync.md\":\"BlZUnxYn\",\"pipelines_cross-workspace-csv-merge.md\":\"CsRE6GNe\",\"pipelines_movimenti-per-conto.md\":\"DRGfO1_5\",\"pipelines_orders-enriched-daily.md\":\"jESRtvBo\",\"pipelines_readme.md\":\"Ee6LS-SU\",\"pipelines_test-posta.md\":\"Cxo_DGBs\",\"runbooks_aggiornamento-pm2.md\":\"f3LAxif4\",\"runbooks_deployment.md\":\"DvIOOsoG\",\"runbooks_etl-worker.md\":\"Bu05cEgT\",\"runbooks_graph-server.md\":\"BOXZqdXC\",\"runbooks_mask-key.md\":\"nZkhAjBf\",\"runbooks_oauth-google-posta.md\":\"Bs7QTkmU\",\"runbooks_rollback-di-pipeline.md\":\"6US0Wsdc\",\"runbooks_scd2-rehash.md\":\"DtmuXA67\",\"runbooks_sql-task-truncate-swap.md\":\"C8viT-fp\",\"runbooks_stato-incrementale.md\":\"hGZ8FlbZ\",\"sub-pipelines_readme.md\":\"CF8gmNPU\",\"sub-pipelines_riepilogo-ordini.md\":\"qCBZJ4nh\",\"technical_overview.md\":\"DQP0pWc8\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"it-IT\",\"dir\":\"ltr\",\"title\":\"Noeva ETL\",\"titleTemplate\":\":title · Noeva ETL\",\"description\":\"Documentazione di Noeva ETL: come usare la piattaforma e come creare pipeline con Claude Code.\",\"base\":\"/guida/core/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":{\"light\":\"/logo-dark.png\",\"dark\":\"/logo-light.png\",\"alt\":\"Noeva\"},\"siteTitle\":false,\"footer\":{\"message\":\"Noeva è un marchio registrato di 4D S.R.L.\",\"copyright\":\"© 2026 4D S.R.L. · Gruppo4D\"},\"outline\":{\"level\":[2,3],\"label\":\"In questa pagina\"},\"docFooter\":{\"prev\":\"Pagina precedente\",\"next\":\"Pagina successiva\"},\"darkModeSwitchLabel\":\"Tema\",\"lightModeSwitchTitle\":\"Passa al tema chiaro\",\"darkModeSwitchTitle\":\"Passa al tema scuro\",\"sidebarMenuLabel\":\"Menu\",\"returnToTopLabel\":\"Torna su\",\"langMenuLabel\":\"Lingua\",\"notFound\":{\"title\":\"PAGINA NON TROVATA\",\"quote\":\"Il documento che cercavi non c'è più, o non è mai stato pubblicato qui.\",\"linkLabel\":\"Torna alla home\",\"linkText\":\"Torna alla home\"},\"search\":{\"provider\":\"local\",\"options\":{\"translations\":{\"button\":{\"buttonText\":\"Cerca\",\"buttonAriaLabel\":\"Cerca nella documentazione\"},\"modal\":{\"displayDetails\":\"Mostra i dettagli\",\"resetButtonTitle\":\"Azzera la ricerca\",\"backButtonTitle\":\"Chiudi la ricerca\",\"noResultsText\":\"Nessun risultato per\",\"footer\":{\"selectText\":\"per aprire\",\"selectKeyAriaLabel\":\"invio\",\"navigateText\":\"per spostarti\",\"navigateUpKeyAriaLabel\":\"freccia su\",\"navigateDownKeyAriaLabel\":\"freccia giù\",\"closeText\":\"per chiudere\",\"closeKeyAriaLabel\":\"esc\"}}}}},\"nav\":[{\"text\":\"Usare\",\"link\":\"/guide/usare/\",\"activeMatch\":\"^/guide/usare/\"},{\"text\":\"Creare con Claude Code\",\"link\":\"/guide/claude-code/\",\"activeMatch\":\"^/guide/claude-code/\"},{\"text\":\"Riferimento\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Tipi di nodo\",\"link\":\"/nodes/README\"},{\"text\":\"Connettori\",\"link\":\"/connectors/README\"},{\"text\":\"Pipeline pronte\",\"link\":\"/pipelines/README\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"},{\"text\":\"Operatività\",\"link\":\"/runbooks/graph-server\"}]}],\"sidebar\":[{\"text\":\"Usare Noeva ETL\",\"items\":[{\"text\":\"Come si usa\",\"link\":\"/guide/usare/\"},{\"text\":\"L'app desktop\",\"link\":\"/guide/usare/app-desktop\"},{\"text\":\"Leggere l'esito di una run\",\"link\":\"/guide/usare/esito-di-una-run\"},{\"text\":\"Panoramica di prodotto\",\"link\":\"/TECHNICAL_OVERVIEW\"}]},{\"text\":\"Creare con Claude Code\",\"items\":[{\"text\":\"Dal bisogno al processo\",\"link\":\"/guide/claude-code/\"},{\"text\":\"Comporre il prompt\",\"link\":\"/guide/claude-code/prompt\"},{\"text\":\"Skill e subagent\",\"link\":\"/guide/claude-code/strumenti\"},{\"text\":\"Guida allo sviluppo\",\"link\":\"/GUIDA_SVILUPPO\"}]},{\"text\":\"Concetti\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Versioni di pipeline\",\"link\":\"/conventions/versioni-di-pipeline\"},{\"text\":\"Descriptor dei nodi\",\"link\":\"/conventions/node-descriptor\"},{\"text\":\"Colonne dei nodi\",\"link\":\"/conventions/node-columns\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"}]},{\"text\":\"Tipi di nodo\",\"collapsed\":true,\"items\":[{\"text\":\"Cheatsheet\",\"link\":\"/nodes/README\"},{\"text\":\"action\",\"link\":\"/nodes/action\"},{\"text\":\"ai\",\"link\":\"/nodes/ai\"},{\"text\":\"join\",\"link\":\"/nodes/join\"},{\"text\":\"lookup\",\"link\":\"/nodes/lookup\"},{\"text\":\"pipeline\",\"link\":\"/nodes/pipeline\"},{\"text\":\"route\",\"link\":\"/nodes/route\"},{\"text\":\"sink\",\"link\":\"/nodes/sink\"},{\"text\":\"source\",\"link\":\"/nodes/source\"},{\"text\":\"task\",\"link\":\"/nodes/task\"},{\"text\":\"transform\",\"link\":\"/nodes/transform\"},{\"text\":\"try-catch\",\"link\":\"/nodes/try-catch\"},{\"text\":\"union\",\"link\":\"/nodes/union\"}]},{\"text\":\"Connettori\",\"collapsed\":true,\"items\":[{\"text\":\"Panoramica\",\"link\":\"/connectors/README\"},{\"text\":\"File (storage × codec)\",\"link\":\"/connectors/file\"},{\"text\":\"HTTP (API REST per i nodi lookup e action)\",\"link\":\"/connectors/http\"},{\"text\":\"IMAP (caselle di posta)\",\"link\":\"/connectors/imap\"},{\"text\":\"Jira Cloud (issue da una JQL o per chiave, liste di una issue, creazione, aggiornamento, transizioni, upsert, commenti, worklog e link)\",\"link\":\"/connectors/jira\"},{\"text\":\"Noeva (file dei workspace)\",\"link\":\"/connectors/noeva\"},{\"text\":\"OAuth2 per i connettori di posta\",\"link\":\"/connectors/oauth\"},{\"text\":\"PostgreSQL\",\"link\":\"/connectors/postgres\"},{\"text\":\"processo esterno\",\"link\":\"/connectors/process\"},{\"text\":\"SendGrid (mail via API REST)\",\"link\":\"/connectors/sendgrid\"},{\"text\":\"SMTP (notifiche email)\",\"link\":\"/connectors/smtp\"},{\"text\":\"SQL Server\",\"link\":\"/connectors/sqlserver\"}]},{\"text\":\"Pipeline pronte\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una pipeline\",\"link\":\"/pipelines/README\"},{\"text\":\"test-posta\",\"link\":\"/pipelines/test-posta\"}]},{\"text\":\"Esempi\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una sub-pipeline\",\"link\":\"/sub-pipelines/README\"},{\"text\":\"crm-leads-sync\",\"link\":\"/pipelines/crm-leads-sync\"},{\"text\":\"cross-workspace-csv-merge\",\"link\":\"/pipelines/cross-workspace-csv-merge\"},{\"text\":\"movimenti-per-conto\",\"link\":\"/pipelines/movimenti-per-conto\"},{\"text\":\"orders-enriched-daily\",\"link\":\"/pipelines/orders-enriched-daily\"},{\"text\":\"riepilogo-ordini\",\"link\":\"/sub-pipelines/riepilogo-ordini\"}]},{\"text\":\"Operatività\",\"collapsed\":true,\"items\":[{\"text\":\"aggiornare un deploy PM2 di un repo cliente\",\"link\":\"/runbooks/aggiornamento-pm2\"},{\"text\":\"distribuzione del runner ETL\",\"link\":\"/runbooks/deployment\"},{\"text\":\"worker etl worker (polling su processes)\",\"link\":\"/runbooks/etl-worker\"},{\"text\":\"server grafi etl serve (HTTP)\",\"link\":\"/runbooks/graph-server\"},{\"text\":\"chiavi di mask (creazione, rotazione, compromissione)\",\"link\":\"/runbooks/mask-key\"},{\"text\":\"OAuth2 per una casella Google (IMAP + SMTP)\",\"link\":\"/runbooks/oauth-google-posta\"},{\"text\":\"rollback di una pipeline\",\"link\":\"/runbooks/rollback-di-pipeline\"},{\"text\":\"rehash di una dimensione storicizzata\",\"link\":\"/runbooks/scd2-rehash\"},{\"text\":\"task SQL, truncate e scambio di tabelle\",\"link\":\"/runbooks/sql-task-truncate-swap\"},{\"text\":\"stato di pipeline e watermark\",\"link\":\"/runbooks/stato-incrementale\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
33
33
 
34
34
  </body>
35
35
  </html>
@@ -9,9 +9,9 @@
9
9
  <link rel="preload stylesheet" href="/guida/core/assets/style.BNn_AkzN.css" as="style">
10
10
  <link rel="preload stylesheet" href="/guida/core/vp-icons.css" as="style">
11
11
 
12
- <script type="module" src="/guida/core/assets/app.Bgu6oi0F.js"></script>
12
+ <script type="module" src="/guida/core/assets/app.BMz6ZZYF.js"></script>
13
13
  <link rel="preload" href="/guida/core/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
14
- <link rel="modulepreload" href="/guida/core/assets/chunks/theme.DvCzVyXX.js">
14
+ <link rel="modulepreload" href="/guida/core/assets/chunks/theme.DV62mViB.js">
15
15
  <link rel="modulepreload" href="/guida/core/assets/chunks/framework.qdetmeNX.js">
16
16
  <link rel="modulepreload" href="/guida/core/assets/guide_claude-code_index.md.CxVSru8e.lean.js">
17
17
  <link rel="icon" type="image/svg+xml" href="/guida/core/favicon.svg">
@@ -25,7 +25,7 @@
25
25
  <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .claude/worktrees/fatture-clienti-daily</span></span>
26
26
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span></span>
27
27
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">claude</span></span></code></pre></div><p>Il file <code>.env</code> con le credenziali serve solo se il processo va provato contro sistemi reali.</p><h2 id="i-sei-passi" tabindex="-1">I sei passi <a class="header-anchor" href="#i-sei-passi" aria-label="Permalink to &quot;I sei passi&quot;">​</a></h2><div class="etl-steps"><ol><li><p><strong>Descrivi il processo.</strong> Scrivi a Claude cosa deve fare il processo, con le decisioni di dominio già prese. Il <a href="./prompt">compositore del prompt</a> ti guida campo per campo e ti dice cosa manca.</p></li><li><p><strong>Lascia fare lo scaffold.</strong> <code>/new-pipeline &lt;nome&gt;</code> genera tutto ciò che un processo richiede: i contratti dati, il grafo, la prima versione del processo con lo snapshot del suo piano, il collegamento ai connettori reali, la voce nel catalogo di <code>etl.config.ts</code>, i test e la scheda di documentazione. Se la forma del processo è già decisa nei dettagli, Claude può affidarla al subagent <code>graph-builder</code>.</p></li><li><p><strong>Fai passare i test.</strong> Un processo è finito quando i test dimostrano che i record validi vengono caricati, quelli invalidi finiscono nello scarto, i contatori tornano e rieseguirlo non duplica dati. Prima della Pull Request fai girare i controlli della CI del repo: <code>pnpm exec etl ci</code>, la stessa sequenza della CI.</p></li><li><p><strong>Fai rivedere il lavoro.</strong> <code>/etl-review</code> controlla la correttezza del dato; i subagent <code>graph-auditor</code> e <code>schema-contract-auditor</code> guardano struttura del grafo e contratti. A lavoro finito, <code>/doc-sync</code> verifica che la documentazione dica ciò che il codice fa.</p></li><li><p><strong>Apri la Pull Request verso <code>dev</code>.</strong> Codice, test e documentazione viaggiano insieme. La promozione verso <code>staging</code> e <code>main</code> passa sempre da altre Pull Request.</p></li><li><p><strong>Porta il processo nell&#39;app.</strong> Dopo il deploy il server ETL va riavviato, perché l&#39;elenco dei grafi si costruisce all&#39;avvio; il pulsante <strong>Esegui</strong> si abilita da solo quando il worker riparte e dichiara al server Noeva i processi che sa eseguire. Vedi <a href="./../usare/app-desktop#avviare-una-run">L&#39;app desktop</a>.</p></li></ol></div><h2 id="cosa-ti-chiedera-l-agente" tabindex="-1">Cosa ti chiederà l&#39;agente <a class="header-anchor" href="#cosa-ti-chiedera-l-agente" aria-label="Permalink to &quot;Cosa ti chiederà l&#39;agente&quot;">​</a></h2><p>Sono le decisioni che fanno la differenza fra un processo corretto e uno che sembra funzionare:</p><table tabindex="0"><thead><tr><th>Decisione</th><th>Perché conta</th></tr></thead><tbody><tr><td>Da dove leggere</td><td>quale connettore, quale istanza, quali righe o file: definisce la sorgente e il suo filtro</td></tr><tr><td>Cosa trasformare</td><td>le regole di business, una per una: diventano nodi distinti, visibili nel grafo</td></tr><tr><td>Dove scrivere</td><td>destinazione e formato</td></tr><tr><td>Su quale chiave rendere idempotente</td><td>senza chiave naturale, rieseguire il processo duplica i dati</td></tr><tr><td>Cosa fare dei record invalidi</td><td>scarto e run che prosegue, oppure run che si ferma: dipende da cosa significa il dato</td></tr></tbody></table><p>Il <a href="./prompt">compositore del prompt</a> le raccoglie tutte e produce il testo da incollare.</p><div class="warning custom-block"><p class="custom-block-title">Cosa non chiedere</p><p>Alcune cose il core non le accetta, e l&#39;agente lo sa: una query dentro una trasformazione (per quello c&#39;è il nodo <code>lookup</code>), un record scartato senza lasciare traccia, una scrittura che duplica i dati a ogni riesecuzione, una credenziale nel codice. L&#39;elenco completo è nella <a href="./../../GUIDA_SVILUPPO#_9-cosa-non-fare-vincoli-non-negoziabili">guida allo sviluppo</a>.</p></div></div></div></main><footer class="VPDocFooter" data-v-303c7d43 data-v-64d0b887><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-64d0b887><span class="visually-hidden" id="doc-footer-aria-label" data-v-64d0b887>Pager</span><div class="pager" data-v-64d0b887><a class="VPLink link pager-link prev" href="/guida/core/TECHNICAL_OVERVIEW" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina precedente</span><span class="title" data-v-64d0b887>Panoramica di prodotto</span><!--]--></a></div><div class="pager" data-v-64d0b887><a class="VPLink link pager-link next" href="/guida/core/guide/claude-code/prompt" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina successiva</span><span class="title" data-v-64d0b887>Comporre il prompt</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooter has-sidebar" data-v-f5dee57d data-v-e10de3dd><div class="container" data-v-e10de3dd><p class="message" data-v-e10de3dd>Noeva è un marchio registrato di 4D S.R.L.</p><p class="copyright" data-v-e10de3dd>© 2026 4D S.R.L. · Gruppo4D</p></div></footer><!--[--><span hidden></span><!--]--></div></div>
28
- <script>window.__VP_HASH_MAP__=JSON.parse("{\"connectors_file.md\":\"B1NJe0VJ\",\"connectors_http.md\":\"B8utPijY\",\"connectors_imap.md\":\"CMMpZVXn\",\"connectors_jira.md\":\"0DJvrRXH\",\"connectors_noeva.md\":\"DkxCC8Ey\",\"connectors_oauth.md\":\"DUHajB0u\",\"connectors_postgres.md\":\"DPpHqXkc\",\"connectors_process.md\":\"lQLmWbGN\",\"connectors_readme.md\":\"ChyXSf73\",\"connectors_sendgrid.md\":\"dJzIWepq\",\"connectors_smtp.md\":\"DXXvaNxD\",\"connectors_sqlserver.md\":\"D1sYNLEq\",\"conventions_node-columns.md\":\"D9K1peUx\",\"conventions_node-descriptor.md\":\"D8Si7E2S\",\"conventions_run-report.md\":\"D_pG07VG\",\"conventions_run-trace.md\":\"nKS_RgLC\",\"conventions_variabili-del-core.md\":\"BU6BD6w_\",\"conventions_versioni-di-pipeline.md\":\"cy5nsizS\",\"guida_sviluppo.md\":\"B_lGYssk\",\"guide_claude-code_index.md\":\"CxVSru8e\",\"guide_claude-code_prompt.md\":\"C7uETA9W\",\"guide_claude-code_strumenti.md\":\"BWhQnAlY\",\"guide_grafo.md\":\"Dy8_YMeh\",\"guide_usare_app-desktop.md\":\"CcDu8cJL\",\"guide_usare_esito-di-una-run.md\":\"DkvAOPBE\",\"guide_usare_index.md\":\"BJqi3P7J\",\"index.md\":\"kMhsF-sv\",\"nodes_action.md\":\"DOsTbV-i\",\"nodes_ai.md\":\"CVtP9gEJ\",\"nodes_join.md\":\"DSYbIDG6\",\"nodes_lookup.md\":\"BI8tgBIq\",\"nodes_pipeline.md\":\"DIMlyprm\",\"nodes_readme.md\":\"CHGy_go6\",\"nodes_route.md\":\"Bt9qH6OA\",\"nodes_sink.md\":\"yAf_z4wO\",\"nodes_source.md\":\"V_vlNfOz\",\"nodes_task.md\":\"Dk6VB7as\",\"nodes_transform.md\":\"Bv5fg2Xx\",\"nodes_try-catch.md\":\"DCYydDPm\",\"nodes_union.md\":\"CznVzHTK\",\"pipelines_crm-leads-sync.md\":\"BlZUnxYn\",\"pipelines_cross-workspace-csv-merge.md\":\"CsRE6GNe\",\"pipelines_movimenti-per-conto.md\":\"DRGfO1_5\",\"pipelines_orders-enriched-daily.md\":\"jESRtvBo\",\"pipelines_readme.md\":\"Ee6LS-SU\",\"pipelines_test-posta.md\":\"Cxo_DGBs\",\"runbooks_aggiornamento-pm2.md\":\"f3LAxif4\",\"runbooks_deployment.md\":\"DvIOOsoG\",\"runbooks_etl-worker.md\":\"Bu05cEgT\",\"runbooks_graph-server.md\":\"BOXZqdXC\",\"runbooks_mask-key.md\":\"nZkhAjBf\",\"runbooks_oauth-google-posta.md\":\"Bs7QTkmU\",\"runbooks_rollback-di-pipeline.md\":\"6US0Wsdc\",\"runbooks_scd2-rehash.md\":\"DtmuXA67\",\"runbooks_sql-task-truncate-swap.md\":\"C8viT-fp\",\"runbooks_stato-incrementale.md\":\"hGZ8FlbZ\",\"sub-pipelines_readme.md\":\"CF8gmNPU\",\"sub-pipelines_riepilogo-ordini.md\":\"qCBZJ4nh\",\"technical_overview.md\":\"C9V6rGhh\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"it-IT\",\"dir\":\"ltr\",\"title\":\"Noeva ETL\",\"titleTemplate\":\":title · Noeva ETL\",\"description\":\"Documentazione di Noeva ETL: come usare la piattaforma e come creare pipeline con Claude Code.\",\"base\":\"/guida/core/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":{\"light\":\"/logo-dark.png\",\"dark\":\"/logo-light.png\",\"alt\":\"Noeva\"},\"siteTitle\":false,\"footer\":{\"message\":\"Noeva è un marchio registrato di 4D S.R.L.\",\"copyright\":\"© 2026 4D S.R.L. · Gruppo4D\"},\"outline\":{\"level\":[2,3],\"label\":\"In questa pagina\"},\"docFooter\":{\"prev\":\"Pagina precedente\",\"next\":\"Pagina successiva\"},\"darkModeSwitchLabel\":\"Tema\",\"lightModeSwitchTitle\":\"Passa al tema chiaro\",\"darkModeSwitchTitle\":\"Passa al tema scuro\",\"sidebarMenuLabel\":\"Menu\",\"returnToTopLabel\":\"Torna su\",\"langMenuLabel\":\"Lingua\",\"notFound\":{\"title\":\"PAGINA NON TROVATA\",\"quote\":\"Il documento che cercavi non c'è più, o non è mai stato pubblicato qui.\",\"linkLabel\":\"Torna alla home\",\"linkText\":\"Torna alla home\"},\"search\":{\"provider\":\"local\",\"options\":{\"translations\":{\"button\":{\"buttonText\":\"Cerca\",\"buttonAriaLabel\":\"Cerca nella documentazione\"},\"modal\":{\"displayDetails\":\"Mostra i dettagli\",\"resetButtonTitle\":\"Azzera la ricerca\",\"backButtonTitle\":\"Chiudi la ricerca\",\"noResultsText\":\"Nessun risultato per\",\"footer\":{\"selectText\":\"per aprire\",\"selectKeyAriaLabel\":\"invio\",\"navigateText\":\"per spostarti\",\"navigateUpKeyAriaLabel\":\"freccia su\",\"navigateDownKeyAriaLabel\":\"freccia giù\",\"closeText\":\"per chiudere\",\"closeKeyAriaLabel\":\"esc\"}}}}},\"nav\":[{\"text\":\"Usare\",\"link\":\"/guide/usare/\",\"activeMatch\":\"^/guide/usare/\"},{\"text\":\"Creare con Claude Code\",\"link\":\"/guide/claude-code/\",\"activeMatch\":\"^/guide/claude-code/\"},{\"text\":\"Riferimento\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Tipi di nodo\",\"link\":\"/nodes/README\"},{\"text\":\"Connettori\",\"link\":\"/connectors/README\"},{\"text\":\"Pipeline pronte\",\"link\":\"/pipelines/README\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"},{\"text\":\"Operatività\",\"link\":\"/runbooks/graph-server\"}]}],\"sidebar\":[{\"text\":\"Usare Noeva ETL\",\"items\":[{\"text\":\"Come si usa\",\"link\":\"/guide/usare/\"},{\"text\":\"L'app desktop\",\"link\":\"/guide/usare/app-desktop\"},{\"text\":\"Leggere l'esito di una run\",\"link\":\"/guide/usare/esito-di-una-run\"},{\"text\":\"Panoramica di prodotto\",\"link\":\"/TECHNICAL_OVERVIEW\"}]},{\"text\":\"Creare con Claude Code\",\"items\":[{\"text\":\"Dal bisogno al processo\",\"link\":\"/guide/claude-code/\"},{\"text\":\"Comporre il prompt\",\"link\":\"/guide/claude-code/prompt\"},{\"text\":\"Skill e subagent\",\"link\":\"/guide/claude-code/strumenti\"},{\"text\":\"Guida allo sviluppo\",\"link\":\"/GUIDA_SVILUPPO\"}]},{\"text\":\"Concetti\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Versioni di pipeline\",\"link\":\"/conventions/versioni-di-pipeline\"},{\"text\":\"Descriptor dei nodi\",\"link\":\"/conventions/node-descriptor\"},{\"text\":\"Colonne dei nodi\",\"link\":\"/conventions/node-columns\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"}]},{\"text\":\"Tipi di nodo\",\"collapsed\":true,\"items\":[{\"text\":\"Cheatsheet\",\"link\":\"/nodes/README\"},{\"text\":\"action\",\"link\":\"/nodes/action\"},{\"text\":\"ai\",\"link\":\"/nodes/ai\"},{\"text\":\"join\",\"link\":\"/nodes/join\"},{\"text\":\"lookup\",\"link\":\"/nodes/lookup\"},{\"text\":\"pipeline\",\"link\":\"/nodes/pipeline\"},{\"text\":\"route\",\"link\":\"/nodes/route\"},{\"text\":\"sink\",\"link\":\"/nodes/sink\"},{\"text\":\"source\",\"link\":\"/nodes/source\"},{\"text\":\"task\",\"link\":\"/nodes/task\"},{\"text\":\"transform\",\"link\":\"/nodes/transform\"},{\"text\":\"try-catch\",\"link\":\"/nodes/try-catch\"},{\"text\":\"union\",\"link\":\"/nodes/union\"}]},{\"text\":\"Connettori\",\"collapsed\":true,\"items\":[{\"text\":\"Panoramica\",\"link\":\"/connectors/README\"},{\"text\":\"File (storage × codec)\",\"link\":\"/connectors/file\"},{\"text\":\"HTTP (API REST per i nodi lookup e action)\",\"link\":\"/connectors/http\"},{\"text\":\"IMAP (caselle di posta)\",\"link\":\"/connectors/imap\"},{\"text\":\"Jira Cloud (issue da una JQL o per chiave, liste di una issue, creazione, aggiornamento, transizioni, upsert, commenti, worklog e link)\",\"link\":\"/connectors/jira\"},{\"text\":\"Noeva (file dei workspace)\",\"link\":\"/connectors/noeva\"},{\"text\":\"OAuth2 per i connettori di posta\",\"link\":\"/connectors/oauth\"},{\"text\":\"PostgreSQL\",\"link\":\"/connectors/postgres\"},{\"text\":\"processo esterno\",\"link\":\"/connectors/process\"},{\"text\":\"SendGrid (mail via API REST)\",\"link\":\"/connectors/sendgrid\"},{\"text\":\"SMTP (notifiche email)\",\"link\":\"/connectors/smtp\"},{\"text\":\"SQL Server\",\"link\":\"/connectors/sqlserver\"}]},{\"text\":\"Pipeline pronte\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una pipeline\",\"link\":\"/pipelines/README\"},{\"text\":\"test-posta\",\"link\":\"/pipelines/test-posta\"}]},{\"text\":\"Esempi\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una sub-pipeline\",\"link\":\"/sub-pipelines/README\"},{\"text\":\"crm-leads-sync\",\"link\":\"/pipelines/crm-leads-sync\"},{\"text\":\"cross-workspace-csv-merge\",\"link\":\"/pipelines/cross-workspace-csv-merge\"},{\"text\":\"movimenti-per-conto\",\"link\":\"/pipelines/movimenti-per-conto\"},{\"text\":\"orders-enriched-daily\",\"link\":\"/pipelines/orders-enriched-daily\"},{\"text\":\"riepilogo-ordini\",\"link\":\"/sub-pipelines/riepilogo-ordini\"}]},{\"text\":\"Operatività\",\"collapsed\":true,\"items\":[{\"text\":\"aggiornare un deploy PM2 di un repo cliente\",\"link\":\"/runbooks/aggiornamento-pm2\"},{\"text\":\"distribuzione del runner ETL\",\"link\":\"/runbooks/deployment\"},{\"text\":\"worker etl worker (polling su processes)\",\"link\":\"/runbooks/etl-worker\"},{\"text\":\"server grafi etl serve (HTTP)\",\"link\":\"/runbooks/graph-server\"},{\"text\":\"chiavi di mask (creazione, rotazione, compromissione)\",\"link\":\"/runbooks/mask-key\"},{\"text\":\"OAuth2 per una casella Google (IMAP + SMTP)\",\"link\":\"/runbooks/oauth-google-posta\"},{\"text\":\"rollback di una pipeline\",\"link\":\"/runbooks/rollback-di-pipeline\"},{\"text\":\"rehash di una dimensione storicizzata\",\"link\":\"/runbooks/scd2-rehash\"},{\"text\":\"task SQL, truncate e scambio di tabelle\",\"link\":\"/runbooks/sql-task-truncate-swap\"},{\"text\":\"stato di pipeline e watermark\",\"link\":\"/runbooks/stato-incrementale\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
28
+ <script>window.__VP_HASH_MAP__=JSON.parse("{\"connectors_file.md\":\"B1NJe0VJ\",\"connectors_http.md\":\"B8utPijY\",\"connectors_imap.md\":\"CMMpZVXn\",\"connectors_jira.md\":\"0DJvrRXH\",\"connectors_noeva.md\":\"DkxCC8Ey\",\"connectors_oauth.md\":\"DUHajB0u\",\"connectors_postgres.md\":\"DPpHqXkc\",\"connectors_process.md\":\"lQLmWbGN\",\"connectors_readme.md\":\"ChyXSf73\",\"connectors_sendgrid.md\":\"dJzIWepq\",\"connectors_smtp.md\":\"DXXvaNxD\",\"connectors_sqlserver.md\":\"D1sYNLEq\",\"conventions_node-columns.md\":\"D9K1peUx\",\"conventions_node-descriptor.md\":\"D8Si7E2S\",\"conventions_run-report.md\":\"D_pG07VG\",\"conventions_run-trace.md\":\"nKS_RgLC\",\"conventions_variabili-del-core.md\":\"BU6BD6w_\",\"conventions_versioni-di-pipeline.md\":\"cy5nsizS\",\"guida_sviluppo.md\":\"D13C7Zwu\",\"guide_claude-code_index.md\":\"CxVSru8e\",\"guide_claude-code_prompt.md\":\"C7uETA9W\",\"guide_claude-code_strumenti.md\":\"BWhQnAlY\",\"guide_grafo.md\":\"Dy8_YMeh\",\"guide_usare_app-desktop.md\":\"CcDu8cJL\",\"guide_usare_esito-di-una-run.md\":\"DkvAOPBE\",\"guide_usare_index.md\":\"BJqi3P7J\",\"index.md\":\"kMhsF-sv\",\"nodes_action.md\":\"DOsTbV-i\",\"nodes_ai.md\":\"CVtP9gEJ\",\"nodes_join.md\":\"DSYbIDG6\",\"nodes_lookup.md\":\"BI8tgBIq\",\"nodes_pipeline.md\":\"DIMlyprm\",\"nodes_readme.md\":\"CHGy_go6\",\"nodes_route.md\":\"Bt9qH6OA\",\"nodes_sink.md\":\"yAf_z4wO\",\"nodes_source.md\":\"V_vlNfOz\",\"nodes_task.md\":\"Dk6VB7as\",\"nodes_transform.md\":\"Bv5fg2Xx\",\"nodes_try-catch.md\":\"DCYydDPm\",\"nodes_union.md\":\"CznVzHTK\",\"pipelines_crm-leads-sync.md\":\"BlZUnxYn\",\"pipelines_cross-workspace-csv-merge.md\":\"CsRE6GNe\",\"pipelines_movimenti-per-conto.md\":\"DRGfO1_5\",\"pipelines_orders-enriched-daily.md\":\"jESRtvBo\",\"pipelines_readme.md\":\"Ee6LS-SU\",\"pipelines_test-posta.md\":\"Cxo_DGBs\",\"runbooks_aggiornamento-pm2.md\":\"f3LAxif4\",\"runbooks_deployment.md\":\"DvIOOsoG\",\"runbooks_etl-worker.md\":\"Bu05cEgT\",\"runbooks_graph-server.md\":\"BOXZqdXC\",\"runbooks_mask-key.md\":\"nZkhAjBf\",\"runbooks_oauth-google-posta.md\":\"Bs7QTkmU\",\"runbooks_rollback-di-pipeline.md\":\"6US0Wsdc\",\"runbooks_scd2-rehash.md\":\"DtmuXA67\",\"runbooks_sql-task-truncate-swap.md\":\"C8viT-fp\",\"runbooks_stato-incrementale.md\":\"hGZ8FlbZ\",\"sub-pipelines_readme.md\":\"CF8gmNPU\",\"sub-pipelines_riepilogo-ordini.md\":\"qCBZJ4nh\",\"technical_overview.md\":\"DQP0pWc8\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"it-IT\",\"dir\":\"ltr\",\"title\":\"Noeva ETL\",\"titleTemplate\":\":title · Noeva ETL\",\"description\":\"Documentazione di Noeva ETL: come usare la piattaforma e come creare pipeline con Claude Code.\",\"base\":\"/guida/core/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":{\"light\":\"/logo-dark.png\",\"dark\":\"/logo-light.png\",\"alt\":\"Noeva\"},\"siteTitle\":false,\"footer\":{\"message\":\"Noeva è un marchio registrato di 4D S.R.L.\",\"copyright\":\"© 2026 4D S.R.L. · Gruppo4D\"},\"outline\":{\"level\":[2,3],\"label\":\"In questa pagina\"},\"docFooter\":{\"prev\":\"Pagina precedente\",\"next\":\"Pagina successiva\"},\"darkModeSwitchLabel\":\"Tema\",\"lightModeSwitchTitle\":\"Passa al tema chiaro\",\"darkModeSwitchTitle\":\"Passa al tema scuro\",\"sidebarMenuLabel\":\"Menu\",\"returnToTopLabel\":\"Torna su\",\"langMenuLabel\":\"Lingua\",\"notFound\":{\"title\":\"PAGINA NON TROVATA\",\"quote\":\"Il documento che cercavi non c'è più, o non è mai stato pubblicato qui.\",\"linkLabel\":\"Torna alla home\",\"linkText\":\"Torna alla home\"},\"search\":{\"provider\":\"local\",\"options\":{\"translations\":{\"button\":{\"buttonText\":\"Cerca\",\"buttonAriaLabel\":\"Cerca nella documentazione\"},\"modal\":{\"displayDetails\":\"Mostra i dettagli\",\"resetButtonTitle\":\"Azzera la ricerca\",\"backButtonTitle\":\"Chiudi la ricerca\",\"noResultsText\":\"Nessun risultato per\",\"footer\":{\"selectText\":\"per aprire\",\"selectKeyAriaLabel\":\"invio\",\"navigateText\":\"per spostarti\",\"navigateUpKeyAriaLabel\":\"freccia su\",\"navigateDownKeyAriaLabel\":\"freccia giù\",\"closeText\":\"per chiudere\",\"closeKeyAriaLabel\":\"esc\"}}}}},\"nav\":[{\"text\":\"Usare\",\"link\":\"/guide/usare/\",\"activeMatch\":\"^/guide/usare/\"},{\"text\":\"Creare con Claude Code\",\"link\":\"/guide/claude-code/\",\"activeMatch\":\"^/guide/claude-code/\"},{\"text\":\"Riferimento\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Tipi di nodo\",\"link\":\"/nodes/README\"},{\"text\":\"Connettori\",\"link\":\"/connectors/README\"},{\"text\":\"Pipeline pronte\",\"link\":\"/pipelines/README\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"},{\"text\":\"Operatività\",\"link\":\"/runbooks/graph-server\"}]}],\"sidebar\":[{\"text\":\"Usare Noeva ETL\",\"items\":[{\"text\":\"Come si usa\",\"link\":\"/guide/usare/\"},{\"text\":\"L'app desktop\",\"link\":\"/guide/usare/app-desktop\"},{\"text\":\"Leggere l'esito di una run\",\"link\":\"/guide/usare/esito-di-una-run\"},{\"text\":\"Panoramica di prodotto\",\"link\":\"/TECHNICAL_OVERVIEW\"}]},{\"text\":\"Creare con Claude Code\",\"items\":[{\"text\":\"Dal bisogno al processo\",\"link\":\"/guide/claude-code/\"},{\"text\":\"Comporre il prompt\",\"link\":\"/guide/claude-code/prompt\"},{\"text\":\"Skill e subagent\",\"link\":\"/guide/claude-code/strumenti\"},{\"text\":\"Guida allo sviluppo\",\"link\":\"/GUIDA_SVILUPPO\"}]},{\"text\":\"Concetti\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Versioni di pipeline\",\"link\":\"/conventions/versioni-di-pipeline\"},{\"text\":\"Descriptor dei nodi\",\"link\":\"/conventions/node-descriptor\"},{\"text\":\"Colonne dei nodi\",\"link\":\"/conventions/node-columns\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"}]},{\"text\":\"Tipi di nodo\",\"collapsed\":true,\"items\":[{\"text\":\"Cheatsheet\",\"link\":\"/nodes/README\"},{\"text\":\"action\",\"link\":\"/nodes/action\"},{\"text\":\"ai\",\"link\":\"/nodes/ai\"},{\"text\":\"join\",\"link\":\"/nodes/join\"},{\"text\":\"lookup\",\"link\":\"/nodes/lookup\"},{\"text\":\"pipeline\",\"link\":\"/nodes/pipeline\"},{\"text\":\"route\",\"link\":\"/nodes/route\"},{\"text\":\"sink\",\"link\":\"/nodes/sink\"},{\"text\":\"source\",\"link\":\"/nodes/source\"},{\"text\":\"task\",\"link\":\"/nodes/task\"},{\"text\":\"transform\",\"link\":\"/nodes/transform\"},{\"text\":\"try-catch\",\"link\":\"/nodes/try-catch\"},{\"text\":\"union\",\"link\":\"/nodes/union\"}]},{\"text\":\"Connettori\",\"collapsed\":true,\"items\":[{\"text\":\"Panoramica\",\"link\":\"/connectors/README\"},{\"text\":\"File (storage × codec)\",\"link\":\"/connectors/file\"},{\"text\":\"HTTP (API REST per i nodi lookup e action)\",\"link\":\"/connectors/http\"},{\"text\":\"IMAP (caselle di posta)\",\"link\":\"/connectors/imap\"},{\"text\":\"Jira Cloud (issue da una JQL o per chiave, liste di una issue, creazione, aggiornamento, transizioni, upsert, commenti, worklog e link)\",\"link\":\"/connectors/jira\"},{\"text\":\"Noeva (file dei workspace)\",\"link\":\"/connectors/noeva\"},{\"text\":\"OAuth2 per i connettori di posta\",\"link\":\"/connectors/oauth\"},{\"text\":\"PostgreSQL\",\"link\":\"/connectors/postgres\"},{\"text\":\"processo esterno\",\"link\":\"/connectors/process\"},{\"text\":\"SendGrid (mail via API REST)\",\"link\":\"/connectors/sendgrid\"},{\"text\":\"SMTP (notifiche email)\",\"link\":\"/connectors/smtp\"},{\"text\":\"SQL Server\",\"link\":\"/connectors/sqlserver\"}]},{\"text\":\"Pipeline pronte\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una pipeline\",\"link\":\"/pipelines/README\"},{\"text\":\"test-posta\",\"link\":\"/pipelines/test-posta\"}]},{\"text\":\"Esempi\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una sub-pipeline\",\"link\":\"/sub-pipelines/README\"},{\"text\":\"crm-leads-sync\",\"link\":\"/pipelines/crm-leads-sync\"},{\"text\":\"cross-workspace-csv-merge\",\"link\":\"/pipelines/cross-workspace-csv-merge\"},{\"text\":\"movimenti-per-conto\",\"link\":\"/pipelines/movimenti-per-conto\"},{\"text\":\"orders-enriched-daily\",\"link\":\"/pipelines/orders-enriched-daily\"},{\"text\":\"riepilogo-ordini\",\"link\":\"/sub-pipelines/riepilogo-ordini\"}]},{\"text\":\"Operatività\",\"collapsed\":true,\"items\":[{\"text\":\"aggiornare un deploy PM2 di un repo cliente\",\"link\":\"/runbooks/aggiornamento-pm2\"},{\"text\":\"distribuzione del runner ETL\",\"link\":\"/runbooks/deployment\"},{\"text\":\"worker etl worker (polling su processes)\",\"link\":\"/runbooks/etl-worker\"},{\"text\":\"server grafi etl serve (HTTP)\",\"link\":\"/runbooks/graph-server\"},{\"text\":\"chiavi di mask (creazione, rotazione, compromissione)\",\"link\":\"/runbooks/mask-key\"},{\"text\":\"OAuth2 per una casella Google (IMAP + SMTP)\",\"link\":\"/runbooks/oauth-google-posta\"},{\"text\":\"rollback di una pipeline\",\"link\":\"/runbooks/rollback-di-pipeline\"},{\"text\":\"rehash di una dimensione storicizzata\",\"link\":\"/runbooks/scd2-rehash\"},{\"text\":\"task SQL, truncate e scambio di tabelle\",\"link\":\"/runbooks/sql-task-truncate-swap\"},{\"text\":\"stato di pipeline e watermark\",\"link\":\"/runbooks/stato-incrementale\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
29
29
 
30
30
  </body>
31
31
  </html>
@@ -9,9 +9,9 @@
9
9
  <link rel="preload stylesheet" href="/guida/core/assets/style.BNn_AkzN.css" as="style">
10
10
  <link rel="preload stylesheet" href="/guida/core/vp-icons.css" as="style">
11
11
 
12
- <script type="module" src="/guida/core/assets/app.Bgu6oi0F.js"></script>
12
+ <script type="module" src="/guida/core/assets/app.BMz6ZZYF.js"></script>
13
13
  <link rel="preload" href="/guida/core/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
14
- <link rel="modulepreload" href="/guida/core/assets/chunks/theme.DvCzVyXX.js">
14
+ <link rel="modulepreload" href="/guida/core/assets/chunks/theme.DV62mViB.js">
15
15
  <link rel="modulepreload" href="/guida/core/assets/chunks/framework.qdetmeNX.js">
16
16
  <link rel="modulepreload" href="/guida/core/assets/guide_claude-code_prompt.md.C7uETA9W.lean.js">
17
17
  <link rel="icon" type="image/svg+xml" href="/guida/core/favicon.svg">
@@ -25,7 +25,7 @@ Normalizza gli importi in centesimi interi." data-v-1448389e></textarea></label>
25
25
 
26
26
  Errori
27
27
  - Un errore di connessione deve far fallire la run (fail-fast).</code></pre><p class="builder__warning" data-v-1448389e> Mancano 5 decisioni: l&#39;agente si fermerà a chiederle. </p></div></div></div></div><h2 id="perche-queste-domande" tabindex="-1">Perché queste domande <a class="header-anchor" href="#perche-queste-domande" aria-label="Permalink to &quot;Perché queste domande&quot;">​</a></h2><ul><li><strong>Il nome</strong> diventa la cartella in <code>src/pipelines/</code> del repo cliente, la voce nel catalogo di <code>etl.config.ts</code> e il nome mostrato nell&#39;app. Si scrive in kebab-case, e cambiarlo dopo costa.</li><li><strong>La connessione</strong> è il nome di un&#39;istanza di connettore già configurata (per esempio <code>gestionale</code> o <code>dwh</code>): un processo non contiene credenziali, le trova nell&#39;ambiente.</li><li><strong>Le trasformazioni, una per riga</strong>, perché ognuna diventa un nodo del grafo. Un nodo per ogni passaggio è ciò che rende leggibile una run nell&#39;app.</li><li><strong>La chiave naturale</strong> è ciò che permette di rieseguire il processo senza duplicare dati: la scrittura aggiorna la riga esistente invece di aggiungerne una nuova.</li><li><strong>Dead-letter o fail-fast</strong> dipende da cosa significa un record invalido. Una fattura con un importo impossibile si può scartare e recuperare; un&#39;aggregazione a cui manca un pezzo darebbe un totale falso, quindi deve fermarsi.</li></ul><h2 id="dopo-aver-incollato-il-prompt" tabindex="-1">Dopo aver incollato il prompt <a class="header-anchor" href="#dopo-aver-incollato-il-prompt" aria-label="Permalink to &quot;Dopo aver incollato il prompt&quot;">​</a></h2><p>Claude usa <code>/new-pipeline</code> per generare lo scheletro e chiede ciò che manca. Rispondi con decisioni, non con codice: il codice lo scrive lui, secondo le regole del core. Poi segui <a href="./#i-sei-passi">i sei passi</a> fino alla Pull Request.</p></div></div></main><footer class="VPDocFooter" data-v-303c7d43 data-v-64d0b887><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-64d0b887><span class="visually-hidden" id="doc-footer-aria-label" data-v-64d0b887>Pager</span><div class="pager" data-v-64d0b887><a class="VPLink link pager-link prev" href="/guida/core/guide/claude-code/" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina precedente</span><span class="title" data-v-64d0b887>Dal bisogno al processo</span><!--]--></a></div><div class="pager" data-v-64d0b887><a class="VPLink link pager-link next" href="/guida/core/guide/claude-code/strumenti" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina successiva</span><span class="title" data-v-64d0b887>Skill e subagent</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooter has-sidebar" data-v-f5dee57d data-v-e10de3dd><div class="container" data-v-e10de3dd><p class="message" data-v-e10de3dd>Noeva è un marchio registrato di 4D S.R.L.</p><p class="copyright" data-v-e10de3dd>© 2026 4D S.R.L. · Gruppo4D</p></div></footer><!--[--><span hidden></span><!--]--></div></div>
28
- <script>window.__VP_HASH_MAP__=JSON.parse("{\"connectors_file.md\":\"B1NJe0VJ\",\"connectors_http.md\":\"B8utPijY\",\"connectors_imap.md\":\"CMMpZVXn\",\"connectors_jira.md\":\"0DJvrRXH\",\"connectors_noeva.md\":\"DkxCC8Ey\",\"connectors_oauth.md\":\"DUHajB0u\",\"connectors_postgres.md\":\"DPpHqXkc\",\"connectors_process.md\":\"lQLmWbGN\",\"connectors_readme.md\":\"ChyXSf73\",\"connectors_sendgrid.md\":\"dJzIWepq\",\"connectors_smtp.md\":\"DXXvaNxD\",\"connectors_sqlserver.md\":\"D1sYNLEq\",\"conventions_node-columns.md\":\"D9K1peUx\",\"conventions_node-descriptor.md\":\"D8Si7E2S\",\"conventions_run-report.md\":\"D_pG07VG\",\"conventions_run-trace.md\":\"nKS_RgLC\",\"conventions_variabili-del-core.md\":\"BU6BD6w_\",\"conventions_versioni-di-pipeline.md\":\"cy5nsizS\",\"guida_sviluppo.md\":\"B_lGYssk\",\"guide_claude-code_index.md\":\"CxVSru8e\",\"guide_claude-code_prompt.md\":\"C7uETA9W\",\"guide_claude-code_strumenti.md\":\"BWhQnAlY\",\"guide_grafo.md\":\"Dy8_YMeh\",\"guide_usare_app-desktop.md\":\"CcDu8cJL\",\"guide_usare_esito-di-una-run.md\":\"DkvAOPBE\",\"guide_usare_index.md\":\"BJqi3P7J\",\"index.md\":\"kMhsF-sv\",\"nodes_action.md\":\"DOsTbV-i\",\"nodes_ai.md\":\"CVtP9gEJ\",\"nodes_join.md\":\"DSYbIDG6\",\"nodes_lookup.md\":\"BI8tgBIq\",\"nodes_pipeline.md\":\"DIMlyprm\",\"nodes_readme.md\":\"CHGy_go6\",\"nodes_route.md\":\"Bt9qH6OA\",\"nodes_sink.md\":\"yAf_z4wO\",\"nodes_source.md\":\"V_vlNfOz\",\"nodes_task.md\":\"Dk6VB7as\",\"nodes_transform.md\":\"Bv5fg2Xx\",\"nodes_try-catch.md\":\"DCYydDPm\",\"nodes_union.md\":\"CznVzHTK\",\"pipelines_crm-leads-sync.md\":\"BlZUnxYn\",\"pipelines_cross-workspace-csv-merge.md\":\"CsRE6GNe\",\"pipelines_movimenti-per-conto.md\":\"DRGfO1_5\",\"pipelines_orders-enriched-daily.md\":\"jESRtvBo\",\"pipelines_readme.md\":\"Ee6LS-SU\",\"pipelines_test-posta.md\":\"Cxo_DGBs\",\"runbooks_aggiornamento-pm2.md\":\"f3LAxif4\",\"runbooks_deployment.md\":\"DvIOOsoG\",\"runbooks_etl-worker.md\":\"Bu05cEgT\",\"runbooks_graph-server.md\":\"BOXZqdXC\",\"runbooks_mask-key.md\":\"nZkhAjBf\",\"runbooks_oauth-google-posta.md\":\"Bs7QTkmU\",\"runbooks_rollback-di-pipeline.md\":\"6US0Wsdc\",\"runbooks_scd2-rehash.md\":\"DtmuXA67\",\"runbooks_sql-task-truncate-swap.md\":\"C8viT-fp\",\"runbooks_stato-incrementale.md\":\"hGZ8FlbZ\",\"sub-pipelines_readme.md\":\"CF8gmNPU\",\"sub-pipelines_riepilogo-ordini.md\":\"qCBZJ4nh\",\"technical_overview.md\":\"C9V6rGhh\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"it-IT\",\"dir\":\"ltr\",\"title\":\"Noeva ETL\",\"titleTemplate\":\":title · Noeva ETL\",\"description\":\"Documentazione di Noeva ETL: come usare la piattaforma e come creare pipeline con Claude Code.\",\"base\":\"/guida/core/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":{\"light\":\"/logo-dark.png\",\"dark\":\"/logo-light.png\",\"alt\":\"Noeva\"},\"siteTitle\":false,\"footer\":{\"message\":\"Noeva è un marchio registrato di 4D S.R.L.\",\"copyright\":\"© 2026 4D S.R.L. · Gruppo4D\"},\"outline\":{\"level\":[2,3],\"label\":\"In questa pagina\"},\"docFooter\":{\"prev\":\"Pagina precedente\",\"next\":\"Pagina successiva\"},\"darkModeSwitchLabel\":\"Tema\",\"lightModeSwitchTitle\":\"Passa al tema chiaro\",\"darkModeSwitchTitle\":\"Passa al tema scuro\",\"sidebarMenuLabel\":\"Menu\",\"returnToTopLabel\":\"Torna su\",\"langMenuLabel\":\"Lingua\",\"notFound\":{\"title\":\"PAGINA NON TROVATA\",\"quote\":\"Il documento che cercavi non c'è più, o non è mai stato pubblicato qui.\",\"linkLabel\":\"Torna alla home\",\"linkText\":\"Torna alla home\"},\"search\":{\"provider\":\"local\",\"options\":{\"translations\":{\"button\":{\"buttonText\":\"Cerca\",\"buttonAriaLabel\":\"Cerca nella documentazione\"},\"modal\":{\"displayDetails\":\"Mostra i dettagli\",\"resetButtonTitle\":\"Azzera la ricerca\",\"backButtonTitle\":\"Chiudi la ricerca\",\"noResultsText\":\"Nessun risultato per\",\"footer\":{\"selectText\":\"per aprire\",\"selectKeyAriaLabel\":\"invio\",\"navigateText\":\"per spostarti\",\"navigateUpKeyAriaLabel\":\"freccia su\",\"navigateDownKeyAriaLabel\":\"freccia giù\",\"closeText\":\"per chiudere\",\"closeKeyAriaLabel\":\"esc\"}}}}},\"nav\":[{\"text\":\"Usare\",\"link\":\"/guide/usare/\",\"activeMatch\":\"^/guide/usare/\"},{\"text\":\"Creare con Claude Code\",\"link\":\"/guide/claude-code/\",\"activeMatch\":\"^/guide/claude-code/\"},{\"text\":\"Riferimento\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Tipi di nodo\",\"link\":\"/nodes/README\"},{\"text\":\"Connettori\",\"link\":\"/connectors/README\"},{\"text\":\"Pipeline pronte\",\"link\":\"/pipelines/README\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"},{\"text\":\"Operatività\",\"link\":\"/runbooks/graph-server\"}]}],\"sidebar\":[{\"text\":\"Usare Noeva ETL\",\"items\":[{\"text\":\"Come si usa\",\"link\":\"/guide/usare/\"},{\"text\":\"L'app desktop\",\"link\":\"/guide/usare/app-desktop\"},{\"text\":\"Leggere l'esito di una run\",\"link\":\"/guide/usare/esito-di-una-run\"},{\"text\":\"Panoramica di prodotto\",\"link\":\"/TECHNICAL_OVERVIEW\"}]},{\"text\":\"Creare con Claude Code\",\"items\":[{\"text\":\"Dal bisogno al processo\",\"link\":\"/guide/claude-code/\"},{\"text\":\"Comporre il prompt\",\"link\":\"/guide/claude-code/prompt\"},{\"text\":\"Skill e subagent\",\"link\":\"/guide/claude-code/strumenti\"},{\"text\":\"Guida allo sviluppo\",\"link\":\"/GUIDA_SVILUPPO\"}]},{\"text\":\"Concetti\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Versioni di pipeline\",\"link\":\"/conventions/versioni-di-pipeline\"},{\"text\":\"Descriptor dei nodi\",\"link\":\"/conventions/node-descriptor\"},{\"text\":\"Colonne dei nodi\",\"link\":\"/conventions/node-columns\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"}]},{\"text\":\"Tipi di nodo\",\"collapsed\":true,\"items\":[{\"text\":\"Cheatsheet\",\"link\":\"/nodes/README\"},{\"text\":\"action\",\"link\":\"/nodes/action\"},{\"text\":\"ai\",\"link\":\"/nodes/ai\"},{\"text\":\"join\",\"link\":\"/nodes/join\"},{\"text\":\"lookup\",\"link\":\"/nodes/lookup\"},{\"text\":\"pipeline\",\"link\":\"/nodes/pipeline\"},{\"text\":\"route\",\"link\":\"/nodes/route\"},{\"text\":\"sink\",\"link\":\"/nodes/sink\"},{\"text\":\"source\",\"link\":\"/nodes/source\"},{\"text\":\"task\",\"link\":\"/nodes/task\"},{\"text\":\"transform\",\"link\":\"/nodes/transform\"},{\"text\":\"try-catch\",\"link\":\"/nodes/try-catch\"},{\"text\":\"union\",\"link\":\"/nodes/union\"}]},{\"text\":\"Connettori\",\"collapsed\":true,\"items\":[{\"text\":\"Panoramica\",\"link\":\"/connectors/README\"},{\"text\":\"File (storage × codec)\",\"link\":\"/connectors/file\"},{\"text\":\"HTTP (API REST per i nodi lookup e action)\",\"link\":\"/connectors/http\"},{\"text\":\"IMAP (caselle di posta)\",\"link\":\"/connectors/imap\"},{\"text\":\"Jira Cloud (issue da una JQL o per chiave, liste di una issue, creazione, aggiornamento, transizioni, upsert, commenti, worklog e link)\",\"link\":\"/connectors/jira\"},{\"text\":\"Noeva (file dei workspace)\",\"link\":\"/connectors/noeva\"},{\"text\":\"OAuth2 per i connettori di posta\",\"link\":\"/connectors/oauth\"},{\"text\":\"PostgreSQL\",\"link\":\"/connectors/postgres\"},{\"text\":\"processo esterno\",\"link\":\"/connectors/process\"},{\"text\":\"SendGrid (mail via API REST)\",\"link\":\"/connectors/sendgrid\"},{\"text\":\"SMTP (notifiche email)\",\"link\":\"/connectors/smtp\"},{\"text\":\"SQL Server\",\"link\":\"/connectors/sqlserver\"}]},{\"text\":\"Pipeline pronte\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una pipeline\",\"link\":\"/pipelines/README\"},{\"text\":\"test-posta\",\"link\":\"/pipelines/test-posta\"}]},{\"text\":\"Esempi\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una sub-pipeline\",\"link\":\"/sub-pipelines/README\"},{\"text\":\"crm-leads-sync\",\"link\":\"/pipelines/crm-leads-sync\"},{\"text\":\"cross-workspace-csv-merge\",\"link\":\"/pipelines/cross-workspace-csv-merge\"},{\"text\":\"movimenti-per-conto\",\"link\":\"/pipelines/movimenti-per-conto\"},{\"text\":\"orders-enriched-daily\",\"link\":\"/pipelines/orders-enriched-daily\"},{\"text\":\"riepilogo-ordini\",\"link\":\"/sub-pipelines/riepilogo-ordini\"}]},{\"text\":\"Operatività\",\"collapsed\":true,\"items\":[{\"text\":\"aggiornare un deploy PM2 di un repo cliente\",\"link\":\"/runbooks/aggiornamento-pm2\"},{\"text\":\"distribuzione del runner ETL\",\"link\":\"/runbooks/deployment\"},{\"text\":\"worker etl worker (polling su processes)\",\"link\":\"/runbooks/etl-worker\"},{\"text\":\"server grafi etl serve (HTTP)\",\"link\":\"/runbooks/graph-server\"},{\"text\":\"chiavi di mask (creazione, rotazione, compromissione)\",\"link\":\"/runbooks/mask-key\"},{\"text\":\"OAuth2 per una casella Google (IMAP + SMTP)\",\"link\":\"/runbooks/oauth-google-posta\"},{\"text\":\"rollback di una pipeline\",\"link\":\"/runbooks/rollback-di-pipeline\"},{\"text\":\"rehash di una dimensione storicizzata\",\"link\":\"/runbooks/scd2-rehash\"},{\"text\":\"task SQL, truncate e scambio di tabelle\",\"link\":\"/runbooks/sql-task-truncate-swap\"},{\"text\":\"stato di pipeline e watermark\",\"link\":\"/runbooks/stato-incrementale\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
28
+ <script>window.__VP_HASH_MAP__=JSON.parse("{\"connectors_file.md\":\"B1NJe0VJ\",\"connectors_http.md\":\"B8utPijY\",\"connectors_imap.md\":\"CMMpZVXn\",\"connectors_jira.md\":\"0DJvrRXH\",\"connectors_noeva.md\":\"DkxCC8Ey\",\"connectors_oauth.md\":\"DUHajB0u\",\"connectors_postgres.md\":\"DPpHqXkc\",\"connectors_process.md\":\"lQLmWbGN\",\"connectors_readme.md\":\"ChyXSf73\",\"connectors_sendgrid.md\":\"dJzIWepq\",\"connectors_smtp.md\":\"DXXvaNxD\",\"connectors_sqlserver.md\":\"D1sYNLEq\",\"conventions_node-columns.md\":\"D9K1peUx\",\"conventions_node-descriptor.md\":\"D8Si7E2S\",\"conventions_run-report.md\":\"D_pG07VG\",\"conventions_run-trace.md\":\"nKS_RgLC\",\"conventions_variabili-del-core.md\":\"BU6BD6w_\",\"conventions_versioni-di-pipeline.md\":\"cy5nsizS\",\"guida_sviluppo.md\":\"D13C7Zwu\",\"guide_claude-code_index.md\":\"CxVSru8e\",\"guide_claude-code_prompt.md\":\"C7uETA9W\",\"guide_claude-code_strumenti.md\":\"BWhQnAlY\",\"guide_grafo.md\":\"Dy8_YMeh\",\"guide_usare_app-desktop.md\":\"CcDu8cJL\",\"guide_usare_esito-di-una-run.md\":\"DkvAOPBE\",\"guide_usare_index.md\":\"BJqi3P7J\",\"index.md\":\"kMhsF-sv\",\"nodes_action.md\":\"DOsTbV-i\",\"nodes_ai.md\":\"CVtP9gEJ\",\"nodes_join.md\":\"DSYbIDG6\",\"nodes_lookup.md\":\"BI8tgBIq\",\"nodes_pipeline.md\":\"DIMlyprm\",\"nodes_readme.md\":\"CHGy_go6\",\"nodes_route.md\":\"Bt9qH6OA\",\"nodes_sink.md\":\"yAf_z4wO\",\"nodes_source.md\":\"V_vlNfOz\",\"nodes_task.md\":\"Dk6VB7as\",\"nodes_transform.md\":\"Bv5fg2Xx\",\"nodes_try-catch.md\":\"DCYydDPm\",\"nodes_union.md\":\"CznVzHTK\",\"pipelines_crm-leads-sync.md\":\"BlZUnxYn\",\"pipelines_cross-workspace-csv-merge.md\":\"CsRE6GNe\",\"pipelines_movimenti-per-conto.md\":\"DRGfO1_5\",\"pipelines_orders-enriched-daily.md\":\"jESRtvBo\",\"pipelines_readme.md\":\"Ee6LS-SU\",\"pipelines_test-posta.md\":\"Cxo_DGBs\",\"runbooks_aggiornamento-pm2.md\":\"f3LAxif4\",\"runbooks_deployment.md\":\"DvIOOsoG\",\"runbooks_etl-worker.md\":\"Bu05cEgT\",\"runbooks_graph-server.md\":\"BOXZqdXC\",\"runbooks_mask-key.md\":\"nZkhAjBf\",\"runbooks_oauth-google-posta.md\":\"Bs7QTkmU\",\"runbooks_rollback-di-pipeline.md\":\"6US0Wsdc\",\"runbooks_scd2-rehash.md\":\"DtmuXA67\",\"runbooks_sql-task-truncate-swap.md\":\"C8viT-fp\",\"runbooks_stato-incrementale.md\":\"hGZ8FlbZ\",\"sub-pipelines_readme.md\":\"CF8gmNPU\",\"sub-pipelines_riepilogo-ordini.md\":\"qCBZJ4nh\",\"technical_overview.md\":\"DQP0pWc8\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"it-IT\",\"dir\":\"ltr\",\"title\":\"Noeva ETL\",\"titleTemplate\":\":title · Noeva ETL\",\"description\":\"Documentazione di Noeva ETL: come usare la piattaforma e come creare pipeline con Claude Code.\",\"base\":\"/guida/core/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":{\"light\":\"/logo-dark.png\",\"dark\":\"/logo-light.png\",\"alt\":\"Noeva\"},\"siteTitle\":false,\"footer\":{\"message\":\"Noeva è un marchio registrato di 4D S.R.L.\",\"copyright\":\"© 2026 4D S.R.L. · Gruppo4D\"},\"outline\":{\"level\":[2,3],\"label\":\"In questa pagina\"},\"docFooter\":{\"prev\":\"Pagina precedente\",\"next\":\"Pagina successiva\"},\"darkModeSwitchLabel\":\"Tema\",\"lightModeSwitchTitle\":\"Passa al tema chiaro\",\"darkModeSwitchTitle\":\"Passa al tema scuro\",\"sidebarMenuLabel\":\"Menu\",\"returnToTopLabel\":\"Torna su\",\"langMenuLabel\":\"Lingua\",\"notFound\":{\"title\":\"PAGINA NON TROVATA\",\"quote\":\"Il documento che cercavi non c'è più, o non è mai stato pubblicato qui.\",\"linkLabel\":\"Torna alla home\",\"linkText\":\"Torna alla home\"},\"search\":{\"provider\":\"local\",\"options\":{\"translations\":{\"button\":{\"buttonText\":\"Cerca\",\"buttonAriaLabel\":\"Cerca nella documentazione\"},\"modal\":{\"displayDetails\":\"Mostra i dettagli\",\"resetButtonTitle\":\"Azzera la ricerca\",\"backButtonTitle\":\"Chiudi la ricerca\",\"noResultsText\":\"Nessun risultato per\",\"footer\":{\"selectText\":\"per aprire\",\"selectKeyAriaLabel\":\"invio\",\"navigateText\":\"per spostarti\",\"navigateUpKeyAriaLabel\":\"freccia su\",\"navigateDownKeyAriaLabel\":\"freccia giù\",\"closeText\":\"per chiudere\",\"closeKeyAriaLabel\":\"esc\"}}}}},\"nav\":[{\"text\":\"Usare\",\"link\":\"/guide/usare/\",\"activeMatch\":\"^/guide/usare/\"},{\"text\":\"Creare con Claude Code\",\"link\":\"/guide/claude-code/\",\"activeMatch\":\"^/guide/claude-code/\"},{\"text\":\"Riferimento\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Tipi di nodo\",\"link\":\"/nodes/README\"},{\"text\":\"Connettori\",\"link\":\"/connectors/README\"},{\"text\":\"Pipeline pronte\",\"link\":\"/pipelines/README\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"},{\"text\":\"Operatività\",\"link\":\"/runbooks/graph-server\"}]}],\"sidebar\":[{\"text\":\"Usare Noeva ETL\",\"items\":[{\"text\":\"Come si usa\",\"link\":\"/guide/usare/\"},{\"text\":\"L'app desktop\",\"link\":\"/guide/usare/app-desktop\"},{\"text\":\"Leggere l'esito di una run\",\"link\":\"/guide/usare/esito-di-una-run\"},{\"text\":\"Panoramica di prodotto\",\"link\":\"/TECHNICAL_OVERVIEW\"}]},{\"text\":\"Creare con Claude Code\",\"items\":[{\"text\":\"Dal bisogno al processo\",\"link\":\"/guide/claude-code/\"},{\"text\":\"Comporre il prompt\",\"link\":\"/guide/claude-code/prompt\"},{\"text\":\"Skill e subagent\",\"link\":\"/guide/claude-code/strumenti\"},{\"text\":\"Guida allo sviluppo\",\"link\":\"/GUIDA_SVILUPPO\"}]},{\"text\":\"Concetti\",\"items\":[{\"text\":\"Il grafo, nodo per nodo\",\"link\":\"/guide/grafo\"},{\"text\":\"Il report di run\",\"link\":\"/conventions/run-report\"},{\"text\":\"La traccia di una run\",\"link\":\"/conventions/run-trace\"},{\"text\":\"Versioni di pipeline\",\"link\":\"/conventions/versioni-di-pipeline\"},{\"text\":\"Descriptor dei nodi\",\"link\":\"/conventions/node-descriptor\"},{\"text\":\"Colonne dei nodi\",\"link\":\"/conventions/node-columns\"},{\"text\":\"Variabili d'ambiente del core\",\"link\":\"/conventions/variabili-del-core\"}]},{\"text\":\"Tipi di nodo\",\"collapsed\":true,\"items\":[{\"text\":\"Cheatsheet\",\"link\":\"/nodes/README\"},{\"text\":\"action\",\"link\":\"/nodes/action\"},{\"text\":\"ai\",\"link\":\"/nodes/ai\"},{\"text\":\"join\",\"link\":\"/nodes/join\"},{\"text\":\"lookup\",\"link\":\"/nodes/lookup\"},{\"text\":\"pipeline\",\"link\":\"/nodes/pipeline\"},{\"text\":\"route\",\"link\":\"/nodes/route\"},{\"text\":\"sink\",\"link\":\"/nodes/sink\"},{\"text\":\"source\",\"link\":\"/nodes/source\"},{\"text\":\"task\",\"link\":\"/nodes/task\"},{\"text\":\"transform\",\"link\":\"/nodes/transform\"},{\"text\":\"try-catch\",\"link\":\"/nodes/try-catch\"},{\"text\":\"union\",\"link\":\"/nodes/union\"}]},{\"text\":\"Connettori\",\"collapsed\":true,\"items\":[{\"text\":\"Panoramica\",\"link\":\"/connectors/README\"},{\"text\":\"File (storage × codec)\",\"link\":\"/connectors/file\"},{\"text\":\"HTTP (API REST per i nodi lookup e action)\",\"link\":\"/connectors/http\"},{\"text\":\"IMAP (caselle di posta)\",\"link\":\"/connectors/imap\"},{\"text\":\"Jira Cloud (issue da una JQL o per chiave, liste di una issue, creazione, aggiornamento, transizioni, upsert, commenti, worklog e link)\",\"link\":\"/connectors/jira\"},{\"text\":\"Noeva (file dei workspace)\",\"link\":\"/connectors/noeva\"},{\"text\":\"OAuth2 per i connettori di posta\",\"link\":\"/connectors/oauth\"},{\"text\":\"PostgreSQL\",\"link\":\"/connectors/postgres\"},{\"text\":\"processo esterno\",\"link\":\"/connectors/process\"},{\"text\":\"SendGrid (mail via API REST)\",\"link\":\"/connectors/sendgrid\"},{\"text\":\"SMTP (notifiche email)\",\"link\":\"/connectors/smtp\"},{\"text\":\"SQL Server\",\"link\":\"/connectors/sqlserver\"}]},{\"text\":\"Pipeline pronte\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una pipeline\",\"link\":\"/pipelines/README\"},{\"text\":\"test-posta\",\"link\":\"/pipelines/test-posta\"}]},{\"text\":\"Esempi\",\"collapsed\":true,\"items\":[{\"text\":\"Le schede di una sub-pipeline\",\"link\":\"/sub-pipelines/README\"},{\"text\":\"crm-leads-sync\",\"link\":\"/pipelines/crm-leads-sync\"},{\"text\":\"cross-workspace-csv-merge\",\"link\":\"/pipelines/cross-workspace-csv-merge\"},{\"text\":\"movimenti-per-conto\",\"link\":\"/pipelines/movimenti-per-conto\"},{\"text\":\"orders-enriched-daily\",\"link\":\"/pipelines/orders-enriched-daily\"},{\"text\":\"riepilogo-ordini\",\"link\":\"/sub-pipelines/riepilogo-ordini\"}]},{\"text\":\"Operatività\",\"collapsed\":true,\"items\":[{\"text\":\"aggiornare un deploy PM2 di un repo cliente\",\"link\":\"/runbooks/aggiornamento-pm2\"},{\"text\":\"distribuzione del runner ETL\",\"link\":\"/runbooks/deployment\"},{\"text\":\"worker etl worker (polling su processes)\",\"link\":\"/runbooks/etl-worker\"},{\"text\":\"server grafi etl serve (HTTP)\",\"link\":\"/runbooks/graph-server\"},{\"text\":\"chiavi di mask (creazione, rotazione, compromissione)\",\"link\":\"/runbooks/mask-key\"},{\"text\":\"OAuth2 per una casella Google (IMAP + SMTP)\",\"link\":\"/runbooks/oauth-google-posta\"},{\"text\":\"rollback di una pipeline\",\"link\":\"/runbooks/rollback-di-pipeline\"},{\"text\":\"rehash di una dimensione storicizzata\",\"link\":\"/runbooks/scd2-rehash\"},{\"text\":\"task SQL, truncate e scambio di tabelle\",\"link\":\"/runbooks/sql-task-truncate-swap\"},{\"text\":\"stato di pipeline e watermark\",\"link\":\"/runbooks/stato-incrementale\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
29
29
 
30
30
  </body>
31
31
  </html>