@noeva/etl-core 1.0.0-next.1 → 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.
- package/dist/cli.js +103 -103
- package/dist/guida/404.html +2 -2
- package/dist/guida/GUIDA_SVILUPPO.html +5 -5
- package/dist/guida/TECHNICAL_OVERVIEW.html +3 -3
- package/dist/guida/assets/{GUIDA_SVILUPPO.md.Dj20s7gS.js → GUIDA_SVILUPPO.md.D13C7Zwu.js} +1 -1
- package/dist/guida/assets/{app.vAJRZtow.js → app.BMz6ZZYF.js} +1 -1
- package/dist/guida/assets/chunks/@localSearchIndexroot.B3bE99g8.js +1 -0
- package/dist/guida/assets/chunks/{VPLocalSearchBox.D3nX303F.js → VPLocalSearchBox.D8gO6gDY.js} +1 -1
- package/dist/guida/assets/chunks/{theme.Bq6mfDhZ.js → theme.DV62mViB.js} +2 -2
- package/dist/guida/connectors/README.html +3 -3
- package/dist/guida/connectors/file.html +3 -3
- package/dist/guida/connectors/http.html +3 -3
- package/dist/guida/connectors/imap.html +3 -3
- package/dist/guida/connectors/jira.html +3 -3
- package/dist/guida/connectors/noeva.html +3 -3
- package/dist/guida/connectors/oauth.html +3 -3
- package/dist/guida/connectors/postgres.html +3 -3
- package/dist/guida/connectors/process.html +3 -3
- package/dist/guida/connectors/sendgrid.html +3 -3
- package/dist/guida/connectors/smtp.html +3 -3
- package/dist/guida/connectors/sqlserver.html +3 -3
- package/dist/guida/conventions/node-columns.html +3 -3
- package/dist/guida/conventions/node-descriptor.html +3 -3
- package/dist/guida/conventions/run-report.html +3 -3
- package/dist/guida/conventions/run-trace.html +3 -3
- package/dist/guida/conventions/variabili-del-core.html +3 -3
- package/dist/guida/conventions/versioni-di-pipeline.html +3 -3
- package/dist/guida/guide/claude-code/index.html +3 -3
- package/dist/guida/guide/claude-code/prompt.html +3 -3
- package/dist/guida/guide/claude-code/strumenti.html +3 -3
- package/dist/guida/guide/grafo.html +3 -3
- package/dist/guida/guide/usare/app-desktop.html +3 -3
- package/dist/guida/guide/usare/esito-di-una-run.html +3 -3
- package/dist/guida/guide/usare/index.html +3 -3
- package/dist/guida/hashmap.json +1 -1
- package/dist/guida/index.html +3 -3
- package/dist/guida/nodes/README.html +3 -3
- package/dist/guida/nodes/action.html +3 -3
- package/dist/guida/nodes/ai.html +3 -3
- package/dist/guida/nodes/join.html +3 -3
- package/dist/guida/nodes/lookup.html +3 -3
- package/dist/guida/nodes/pipeline.html +3 -3
- package/dist/guida/nodes/route.html +3 -3
- package/dist/guida/nodes/sink.html +3 -3
- package/dist/guida/nodes/source.html +3 -3
- package/dist/guida/nodes/task.html +3 -3
- package/dist/guida/nodes/transform.html +3 -3
- package/dist/guida/nodes/try-catch.html +3 -3
- package/dist/guida/nodes/union.html +3 -3
- package/dist/guida/pipelines/README.html +3 -3
- package/dist/guida/pipelines/crm-leads-sync.html +3 -3
- package/dist/guida/pipelines/cross-workspace-csv-merge.html +3 -3
- package/dist/guida/pipelines/movimenti-per-conto.html +3 -3
- package/dist/guida/pipelines/orders-enriched-daily.html +3 -3
- package/dist/guida/pipelines/test-posta.html +3 -3
- package/dist/guida/runbooks/aggiornamento-pm2.html +3 -3
- package/dist/guida/runbooks/deployment.html +3 -3
- package/dist/guida/runbooks/etl-worker.html +3 -3
- package/dist/guida/runbooks/graph-server.html +3 -3
- package/dist/guida/runbooks/mask-key.html +3 -3
- package/dist/guida/runbooks/oauth-google-posta.html +3 -3
- package/dist/guida/runbooks/rollback-di-pipeline.html +3 -3
- package/dist/guida/runbooks/scd2-rehash.html +3 -3
- package/dist/guida/runbooks/sql-task-truncate-swap.html +3 -3
- package/dist/guida/runbooks/stato-incrementale.html +3 -3
- package/dist/guida/sub-pipelines/README.html +3 -3
- package/dist/guida/sub-pipelines/riepilogo-ordini.html +3 -3
- package/package.json +1 -1
- package/dist/guida/assets/chunks/@localSearchIndexroot.Bhyx8u0i.js +0 -1
- /package/dist/guida/assets/{GUIDA_SVILUPPO.md.Dj20s7gS.lean.js → GUIDA_SVILUPPO.md.D13C7Zwu.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.
|
|
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.
|
|
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/pipelines_orders-enriched-daily.md.jESRtvBo.lean.js">
|
|
17
17
|
<link rel="icon" type="image/svg+xml" href="/guida/core/favicon.svg">
|
|
@@ -62,7 +62,7 @@ memory
|
|
|
62
62
|
orders_dead_letter — dead-letter
|
|
63
63
|
memory
|
|
64
64
|
</title><rect class="dag-node__halo" x="496" y="102" width="198" height="74" rx="12" data-v-340130bc></rect><!----><rect class="dag-node__card" x="500" y="106" width="190" height="66" rx="9" data-v-340130bc></rect><rect class="dag-node__accent" x="500" y="112" width="3" height="54" rx="1.5" data-v-340130bc></rect><text class="dag-node__label" x="512" y="125" data-v-340130bc>orders_dead_letter</text><text class="dag-node__kind" x="680" y="125" text-anchor="end" data-v-340130bc>dead-letter</text><!--[--><text class="dag-node__sub" x="512" y="141" data-v-340130bc>memory</text><!--]--><!--[--><!--]--></g><!--]--><!--[--><!--]--></svg><!--[--><!--]--><!----></div><!----><figcaption class="graph-demo__footer" data-v-fc9b2f46><span class="graph-demo__progress" aria-hidden="true" data-v-fc9b2f46><span style="width:0%;" data-v-fc9b2f46></span></span><span class="graph-demo__caption" aria-live="polite" data-v-fc9b2f46><!--[--> Scegli una scena e premi ▶ per guardarla scorrere, oppure → per andare avanti un passo alla volta. <!--]--></span></figcaption></figure><figure class="level-nav__purposes" data-v-c981a055><figcaption id="level-nav-purposes-v-0" class="level-nav__purposes-title" data-v-c981a055> Lo scopo dei nodi </figcaption><table aria-labelledby="level-nav-purposes-v-0" data-v-c981a055><thead data-v-c981a055><tr data-v-c981a055><th scope="col" data-v-c981a055>Nodo</th><th scope="col" data-v-c981a055>Tipo</th><th scope="col" data-v-c981a055>Scopo</th></tr></thead><tbody data-v-c981a055><!--[--><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>orders</code></td><td data-v-c981a055><code data-v-c981a055>source</code></td><td data-v-c981a055>Legge gli ordini di prova della dimostrazione, ognuno con il cliente che l'ha fatto, l'importo e la data.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>customers</code></td><td data-v-c981a055><code data-v-c981a055>source</code></td><td data-v-c981a055>Legge l'anagrafica di prova dei clienti, con il nome e la fascia di ciascuno, che servono a completare gli ordini.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>validate-orders</code></td><td data-v-c981a055><code data-v-c981a055>transform</code></td><td data-v-c981a055>Controlla che ogni ordine abbia cliente, importo e data validi. Un ordine fuori regola viene messo da parte fra gli scarti, e gli altri proseguono.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>validate-customers</code></td><td data-v-c981a055><code data-v-c981a055>transform</code></td><td data-v-c981a055>Controlla che ogni cliente abbia un nome e una fascia ammessa. Un cliente fuori regola ferma la run: gli ordini completati con un'anagrafica sbagliata sarebbero sbagliati anche loro.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>enrich</code></td><td data-v-c981a055><code data-v-c981a055>join</code></td><td data-v-c981a055>Completa ogni ordine con il nome e la fascia del suo cliente. Un ordine il cui cliente non è in anagrafica prosegue lo stesso, senza nome né fascia.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>guard</code></td><td data-v-c981a055><code data-v-c981a055>try-catch</code></td><td data-v-c981a055>Protegge, ordine per ordine, il riepilogo e il salvataggio: un ordine rifiutato più avanti, come quello con un importo non positivo, finisce fra gli errori e la run prosegue con gli altri.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>riepilogo-ordini</code></td><td data-v-c981a055><code data-v-c981a055>pipeline</code></td><td data-v-c981a055>Prepara i due risultati della giornata a partire dagli ordini completati: gli ordini controllati, pronti da salvare, e il riepilogo per fascia cliente.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>enriched_orders</code></td><td data-v-c981a055><code data-v-c981a055>sink</code></td><td data-v-c981a055>Salva gli ordini della giornata completati con i dati del cliente, uno per ordine: è il dettaglio su cui si appoggia ogni analisi.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>tier_summary</code></td><td data-v-c981a055><code data-v-c981a055>sink</code></td><td data-v-c981a055>Salva il riepilogo della giornata per fascia cliente, con quanti ordini e quale importo totale per ciascuna.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>log-errors</code></td><td data-v-c981a055><code data-v-c981a055>transform</code></td><td data-v-c981a055>Registra nel log ogni ordine finito fra gli errori, con il passo in cui l'errore è nato e il motivo, così si capisce che cosa è andato storto.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>caught_errors</code></td><td data-v-c981a055><code data-v-c981a055>sink</code></td><td data-v-c981a055>Conserva gli errori registrati, ognuno con l'ordine che l'ha causato, per poterli esaminare dopo la run.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>recover-orders</code></td><td data-v-c981a055><code data-v-c981a055>transform</code></td><td data-v-c981a055>Fra gli errori, tiene solo gli ordini che non si sono potuti salvare: sono gli unici da recuperare. Gli altri errori restano solo nel log.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>restore-order</code></td><td data-v-c981a055><code data-v-c981a055>transform</code></td><td data-v-c981a055>Riprende l'ordine com'era prima del salvataggio non riuscito, per poterlo salvare altrove.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>orders-fallback</code></td><td data-v-c981a055><code data-v-c981a055>sink</code></td><td data-v-c981a055>Salva in un archivio di riserva gli ordini che non si sono potuti salvare al loro posto, così nessun ordine va perso.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>orders_dead_letter</code></td><td data-v-c981a055><code data-v-c981a055>dead-letter</code></td><td data-v-c981a055>Raccoglie i record scartati dai nodi di questa pipeline, ognuno con il motivo dello scarto.</td></tr><!--]--></tbody></table></figure></div><blockquote><p>Il grafo qui sopra è disegnato dalla topologia reale della pipeline (<code>getSpec()</code>): nodi, archi, dead-letter e ramo catch sono quelli eseguiti. Premi ▶ per far passare un record, o → per avanzare un passo alla volta.</p></blockquote><p>Due sorgenti indipendenti confluiscono in un <strong>join a chiave</strong> (<code>enrich</code>), il cui output entra nell'istanza <code>riepilogo-ordini</code> della sub-pipeline omonima. Il suo confine d'ingresso valida l'ordine arricchito e fa <strong>fan-out</strong> sulle due uscite dell'istanza, due rami che non si influenzano a vicenda, salvo un errore fatale, che ferma la run: il fatto arricchito (<code>riepilogo-ordini</code> → <code>riepilogo-ordini/fatti</code> → <code>enriched_orders</code>) e un riepilogo aggregato per tier cliente (<code>riepilogo-ordini</code> → <code>riepilogo-ordini/tier-summary</code> → <code>riepilogo-ordini/per-tier</code> → <code>tier_summary</code>).</p><p>Il riepilogo è una <a href="./../sub-pipelines/riepilogo-ordini">sub-pipeline</a> istanziata col nodo <a href="./../nodes/pipeline"><code>pipeline</code></a>: alla costruzione si appiattisce nei suoi nodi, con gli id qualificati. Il grafo qui sopra mostra l'istanza come un nodo chiuso, in cui si entra col doppio click o da «Entra» (il link <code>?istanza=riepilogo-ordini</code> apre la scheda già dentro); il report mostra i nodi interni con l'id qualificato. La root cabla le due uscite con <code>fromPort: "fatti"</code> e <code>fromPort: "per-tier"</code>.</p><p>Codice: <code>src/pipelines/orders-enriched-daily/</code> · DSL a grafo: <code>src/core/graph-builder.ts</code>.</p><h2 id="sorgenti" tabindex="-1">Sorgenti <a class="header-anchor" href="#sorgenti" aria-label="Permalink to "Sorgenti""></a></h2><table tabindex="0"><thead><tr><th>Sistema</th><th>Schema/tabella</th><th>Chiave naturale</th><th>Modalità</th></tr></thead><tbody><tr><td>In-memory (demo)</td><td>ordini grezzi (<code>orders</code>)</td><td><code>order_id</code></td><td>full (dataset fisso in <code>run.ts</code>)</td></tr><tr><td>In-memory (demo)</td><td>anagrafica clienti (<code>customers</code>)</td><td><code>customer_id</code></td><td>full (dataset fisso in <code>run.ts</code>)</td></tr></tbody></table><h2 id="sink" tabindex="-1">Sink <a class="header-anchor" href="#sink" aria-label="Permalink to "Sink""></a></h2><table tabindex="0"><thead><tr><th>Sistema</th><th>Destinazione</th><th>Idempotenza</th></tr></thead><tbody><tr><td>In-memory (demo)</td><td><code>enriched_orders</code></td><td>n/a (demo — in un caso reale: upsert su <code>order_id</code>)</td></tr><tr><td>In-memory (demo)</td><td><code>tier_summary</code></td><td>n/a (demo — in un caso reale: upsert su <code>tier</code>)</td></tr><tr><td>In-memory (demo)</td><td><code>caught_errors</code></td><td>n/a (demo) — ramo <code>catch</code> del <code>guard</code> (<code>log-errors</code>): gli errori catturati, col loro <code>raw</code></td></tr><tr><td>In-memory (demo)</td><td><code>orders-fallback</code></td><td>n/a (demo) — ramo <code>catch</code>: gli ordini che <code>enriched_orders</code> ha rifiutato (<code>recover-orders</code> → <code>restore-order</code>)</td></tr><tr><td>In-memory (demo)</td><td><code>orders_dead_letter</code></td><td>n/a (demo) — dead-letter di <code>validate-orders</code>, opzionale</td></tr></tbody></table><h2 id="trasformazioni-e-regole-di-business" tabindex="-1">Trasformazioni e regole di business <a class="header-anchor" href="#trasformazioni-e-regole-di-business" aria-label="Permalink to "Trasformazioni e regole di business""></a></h2><p>Lo scopo di ogni nodo è nella tabella sotto il grafo, presa dal piano. Qui le regole che i nodi applicano.</p><ul><li><p><strong><code>validate-orders</code></strong> (contratto <code>raw-order-contract</code>) — valida l'ordine grezzo (<code>rawOrderSchema</code>): id non vuoti, <code>amount</code> numerico, <code>created_at</code> coercibile a data. Isolato su dead-letter <strong>per nodo</strong> (<code>ordersDeadLetter</code>, opzionale).</p></li><li><p><strong><code>validate-customers</code></strong> (contratto <code>raw-customer-contract</code>) — valida il cliente grezzo (<code>rawCustomerSchema</code>): id/nome non vuoti, <code>tier</code> in <code>gold|silver|bronze</code>.</p></li><li><p><strong><code>enrich</code></strong> — <code>hashJoin</code> a chiave (<code>build</code> = clienti in memoria, <code>probe</code> = ordini in streaming, <strong>pompato in concorrenza</strong> mentre la tabella di build si materializza), <code>how: "left"</code>: un ordine senza cliente noto sopravvive con <code>customer_name</code>/<code>tier</code> a <code>null</code>. Non solleva errori (il join si limita ad arricchire); entrambe le sorgenti validate vi confluiscono simmetricamente.</p></li><li><p><strong><code>guard</code></strong> — nodo <strong>try/catch</strong> subito <strong>dopo</strong> <code>enrich</code>: nel suo scope stanno l'istanza <code>riepilogo-ordini</code> e i sink a valle.</p></li><li><p><strong><code>riepilogo-ordini</code></strong> — istanza della sub-pipeline <a href="./../sub-pipelines/riepilogo-ordini"><code>riepilogo-ordini</code></a>, alimentata dal <code>guard</code>. Usa il parametro <code>tierMancante</code> al default, <code>"unknown"</code>, quindi si istanzia senza parametri; il piano lo mostra risolto in <code>instances[].params</code>. Appiattita, diventa quattro nodi:</p><ul><li><strong><code>riepilogo-ordini</code></strong>, il confine d'ingresso, che valida l'ordine arricchito (<code>enrichedOrderSchema</code>, <code>amount</code> <strong>positivo</strong>) e fa da gate/fan-out verso le due uscite. Era il nodo <code>fact-contract</code> della root, che l'istanza ha assorbito: il contratto del fatto non si ripete più a monte dell'istanza. <code>riepilogo-ordini:extracted</code> conta gli ordini entrati nell'istanza. Un ordine con <code>amount <= 0</code> passa il join ma viene qui respinto (<code>ValidationError</code>); essendo a valle del <code>guard</code>, l'errore è <strong>catturato dal <code>guard</code></strong> e instradato sul ramo <code>catch</code> (<code>log-errors</code> → <code>caught_errors</code>) invece di abortire. Il guard è <strong>per-record</strong>: <strong>tutti</strong> gli ordini con <code>amount <= 0</code> finiscono nel <code>catch</code> (col loro <code>raw</code>) e i validi continuano a essere caricati;</li><li><strong><code>riepilogo-ordini/fatti</code></strong>, il confine dell'uscita <code>fatti</code>, alimentato direttamente dall'ingresso, verso <code>enriched_orders</code>;</li><li><strong><code>riepilogo-ordini/tier-summary</code></strong>, <code>groupBy</code> <strong>stateful</strong> per tier cliente (<code>order_count</code>, <code>total_amount</code>, gli ordini senza cliente noto sotto il valore di <code>tierMancante</code>, <code>unknown</code>); come ogni aggregazione, è fail-fast (nessun dead-letter per-record: l'aggregazione bufferizza l'intero stream). Essendo stateful non viene mai isolato per-record, quindi un suo errore arriva al <code>catch</code> con <code>raw: undefined</code>; porta però <code>lastConsumed</code>, l'ultimo ordine consumato dal nodo — esatto se l'errore emerge durante il consumo dello stream, assente se emerge in fase di emissione. L'aggregazione di questa demo non ha punti in cui sollevare, quindi il caso è coperto dai test del core e non dalla demo;</li><li><strong><code>riepilogo-ordini/per-tier</code></strong>, il confine dell'uscita <code>per-tier</code>, che rivalida il riepilogo (<code>tierSummarySchema</code>) prima del sink. Era il nodo <code>tier-summary-contract</code>.</li></ul><p>Il <code>guard</code> sta a monte dell'istanza, quindi la copre per intero: un errore nato in uno di questi quattro nodi arriva al suo ramo <code>catch</code> col proprio id qualificato in <code>error.context.nodeId</code>.</p><p>Il caso dell'errore <strong>in emissione</strong> (e quello di un nodo a valle dell'aggregazione, dove <code>raw</code> è l'aggregato e non gli ordini) è coperto dalla lineage dei record: attivando <code>recordIds: true</code> sul grafo e <code>guardSnapshots: true</code> sul guard, il <code>catch</code> riceve <code>guardSnapshots</code> con gli <strong>ordini originali</strong> del gruppo colpevole. Questa pipeline <strong>non</strong> li attiva, per lo stesso motivo per cui il caso non è dimostrato qui: manca un punto di fallimento realistico nell'aggregazione, e gli snapshot terrebbero payload in memoria senza che serva a nulla.</p></li><li><p><strong><code>recover-orders</code> / <code>restore-order</code></strong> — <strong>path di fallback</strong> sul ramo <code>catch</code>. Il sink <code>enriched_orders</code> sta dentro lo scope del <code>guard</code>: se implementa <code>loadOne</code> è <strong>isolabile per-record</strong>, quindi un fallimento di scrittura non aborta la run ma finisce sul ramo <code>catch</code> <strong>portando con sé l'ordine</strong> (<code>DeadLetter.raw</code>). <code>recover-orders</code> filtra i soli errori provenienti da quel sink, <code>restore-order</code> ne estrae il payload e lo carica sul sink <code>orders-fallback</code>. Gli altri errori catturati (contratto, aggregazione, sink opachi) non hanno un ordine da recuperare e sono filtrati via.</p></li></ul><h2 id="contratti-schema-zod" tabindex="-1">Contratti (schema Zod) <a class="header-anchor" href="#contratti-schema-zod" aria-label="Permalink to "Contratti (schema Zod)""></a></h2><p>Definiti in <code>schema.ts</code>:</p><ul><li>Input: <code>rawOrderSchema</code>, <code>rawCustomerSchema</code>.</li><li>Intermedio/output: <code>enrichedOrderSchema</code> (fatto arricchito), <code>tierSummarySchema</code> (riepilogo per tier). Sono i contratti d'ingresso e d'uscita della sub-pipeline <code>riepilogo-ordini</code>: si definiscono in <code>src/sub-pipelines/riepilogo-ordini/schema.ts</code> e <code>schema.ts</code> li riesporta.</li></ul><p><strong>Colonne nel piano (<code>getSpec</code>)</strong>: da questi contratti l'introspezione Zod ricava le <code>columns</code> dei nodi mostrate nella UI del DAG. I nodi <code>validate()</code> (<code>validate-orders</code>, <code>validate-customers</code>) e i confini dell'istanza (<code>riepilogo-ordini</code>, <code>riepilogo-ordini/fatti</code>, <code>riepilogo-ordini/per-tier</code>) espongono le colonne del proprio schema; i sink (<code>enriched_orders</code>, <code>tier_summary</code>) le <strong>ereditano</strong> dal contratto a monte per propagazione. Il join <code>enrich</code> (predecessori discordi) e le source in-memory restano senza colonne. Il <code>groupBy</code> <code>riepilogo-ordini/tier-summary</code> dichiara <code>tierSummarySchema</code> come <code>outputSchema</code>, quindi mostra l'aggregato e non gli ordini che riceve. Il ramo <code>catch</code> non eredita (porta <code>DeadLetter</code>): <code>log-errors</code>, <code>caught_errors</code> e <code>recover-orders</code> restano senza colonne, finché <code>restore-order</code> riporta il record a un ordine e lo dichiara con <code>enrichedOrderSchema</code>. Vedi <code>columnsFromZodObject</code> e <code>toPlanSpec</code> in <code>src/core/</code>.</p><h2 id="parametri-ed-env" tabindex="-1">Parametri ed env <a class="header-anchor" href="#parametri-ed-env" aria-label="Permalink to "Parametri ed env""></a></h2><ul><li><code>ctx.params</code>: nessuno (dataset demo fisso in <code>run.ts</code>).</li><li>Variabili d'ambiente: nessuna — pipeline interamente in-memory, non richiede <code>.env.example</code>. <blockquote><p><strong>Nota storica.</strong> In passato questa pipeline aveva un'opzione <code>stepDelayMs</code> che inseriva un ritardo artificiale nel <code>writeReport</code> di ogni nodo, per rendere osservabile l'avanzamento in UI. Era una pezza a un buco nell'osservabilità: il runner notificava solo <code>onNodeComplete</code>, quindi la UI non aveva modo di sapere quali nodi stessero girando e senza ritardo la run finiva entro un singolo intervallo di polling. Con <code>onNodeStart</code> il segnale c'è davvero, e il ritardo — che stava <strong>nel percorso dati</strong> e bloccava anche il downstream — è stato rimosso.</p></blockquote></li></ul><h2 id="gestione-errori" tabindex="-1">Gestione errori <a class="header-anchor" href="#gestione-errori" aria-label="Permalink to "Gestione errori""></a></h2><ul><li><strong>Dead-letter per nodo</strong> (scelta di design del DSL a grafo): <code>validate-orders</code> ha il proprio sink di dead-letter (<code>ordersDeadLetter</code>, opzionale) che isola gli ordini grezzi non conformi <strong>record-by-record</strong>, continuando con i record buoni.</li><li><strong>Try/catch (per-record)</strong>: il nodo <code>guard</code> (dopo <code>enrich</code>) protegge l'istanza <code>riepilogo-ordini</code> e i nodi a valle. <strong>Ogni</strong> record che solleva un <code>EtlError</code> in un nodo protetto a valle del guard è deviato sul ramo <code>catch</code> (<code>errorLog</code>, opzionale; default: sink interno in memoria) come envelope <code>DeadLetter { raw, error }</code>, dopo essere stato loggato da <code>log-errors</code>, e lo stream <strong>continua</strong> (N record → N nel <code>catch</code>). La run <strong>non</strong> abortisce; lo stato diventa <code>partial</code>. Il comportamento "fermati al primo errore" è opt-in via <code>.tryCatch(..., { mode: "circuit-breaker" })</code>. Le transform <strong>stateful</strong> (es. <code>riepilogo-ordini/tier-summary</code>, un group-by) restano streaming, mai isolate.</li><li><strong>Errori a monte del guard</strong>: il guard cattura solo gli errori nati a valle di sé. Un cliente non conforme in <code>validate-customers</code> (senza dead-letter) o un errore del <code>join</code><code>enrich</code> fanno abortire la run, anche se l'errore attraversa l'istanza <code>riepilogo-ordini</code>.</li><li><strong><code>riepilogo-ordini/tier-summary</code></strong> resta fail-fast: essendo stateful, un errore qui aborta l'intera run (come ogni aggregazione).</li><li>Il <code>RunReport</code> (<code>GraphRunReport</code>) espone <code>status: "partial"</code> quando almeno un nodo ha scarti (<code>rejected</code>) o il try/catch ha catturato errori (<code>caught</code>), con <code>nodes[].rejected</code>/<code>rejectedReasons</code> e <code>nodes[].caught</code> per nodo — mai il payload del record (quello vive solo nel dead-letter/errorLog sink).</li><li><strong>Visibile nella DAG</strong>: <code>getSpec()</code> collega sia il dead-letter sia il ramo catch nella topologia statica, così la UI mostra i <strong>branch d'errore</strong> — da <code>validate-orders</code> verso <code>orders_dead_letter</code> (reject di schema, <code>stepType: "dead-letter"</code>) e dal nodo <code>guard</code> (<code>stepType: "try-catch"</code>) verso <code>log-errors</code> (<code>kind: "catch"</code>) — con edge tratteggiato destructive.</li></ul><h2 id="test" tabindex="-1">Test <a class="header-anchor" href="#test" aria-label="Permalink to "Test""></a></h2><ul><li>Unit pipeline: <code>pipeline.test.ts</code> — join <code>left</code>, fan-out su entrambi i sink, dead-letter per-record su <code>validate-orders</code>, cattura via <strong>try/catch</strong> dell'importo non positivo respinto dal confine d'ingresso <code>riepilogo-ordini</code>, instradato sul ramo catch, forma della topologia reale (<code>nodes</code>/<code>edges</code>, incl. <code>guard</code>, ramo catch e nodi dell'istanza <code>riepilogo-ordini</code>) nel report, riepilogo il cui totale trabocca rifiutato da <code>riepilogo-ordini/per-tier</code> e catturato dal <code>guard</code>.</li><li>Sub-pipeline: <code>sub-pipeline.test.ts</code> prova <code>riepilogo-ordini</code> da sola con <code>runSubPipeline</code>.</li><li>Esecuzione manuale: <code>pnpm run etl run orders-enriched-daily</code> stampa il <code>GraphRunReport</code> completo su stdout (vedi <a href="./../conventions/run-report"><code>docs/conventions/run-report.md</code></a>).</li></ul><h2 id="versioni" tabindex="-1">Versioni <a class="header-anchor" href="#versioni" aria-label="Permalink to "Versioni""></a></h2><p>La storia della pipeline, dalla versione più recente: la voce di changelog di ogni versione (<code>src/pipelines/orders-enriched-daily/changelog.ts</code>) e, sotto, cosa è cambiato nel piano rispetto alla precedente. Vedi <a href="./../conventions/versioni-di-pipeline">versioni di pipeline</a>.</p><div class="pipeline-versions" data-v-cdcb1722><!--[--><article class="pipeline-versions__entry" data-v-cdcb1722><header class="pipeline-versions__header" data-v-cdcb1722><strong class="pipeline-versions__number" data-v-cdcb1722>v3</strong><span class="pipeline-versions__meta" data-v-cdcb1722>2026-10-09 · ETL-193, ETL-195</span><!----></header><!----><!--[--><!--[--><!----><!--]--><!--[--><div class="pipeline-versions__list" data-v-cdcb1722><span class="pipeline-versions__list-title" data-v-cdcb1722>Modifiche</span><ul data-v-cdcb1722><!--[--><li data-v-cdcb1722>Nessun cambio di comportamento: il piano è identico alla v2. Gli import seguono l'infrastruttura (changelog, configurazione delle istanze, report di volume) uscita da `src/pipelines/` (ADR-0093 §1), e la pipeline si dichiara nel catalogo di `etl.config.ts` invece che in un registro (ADR-0093 §2)</li><!--]--></ul></div><!--]--><!--[--><!----><!--]--><!--]--><div class="pipeline-versions__diff" data-v-cdcb1722><p class="pipeline-versions__note" data-v-cdcb1722> Il piano non cambia rispetto alla v2. </p></div></article><article class="pipeline-versions__entry" data-v-cdcb1722><header class="pipeline-versions__header" data-v-cdcb1722><strong class="pipeline-versions__number" data-v-cdcb1722>v2</strong><span class="pipeline-versions__meta" data-v-cdcb1722>2026-10-05 · ETL-85, ETL-87, ETL-88</span><!----></header><!----><!--[--><!--[--><!----><!--]--><!--[--><div class="pipeline-versions__list" data-v-cdcb1722><span class="pipeline-versions__list-title" data-v-cdcb1722>Modifiche</span><ul data-v-cdcb1722><!--[--><li data-v-cdcb1722>Contratto del fatto e riepilogo per tier passano nella sub-pipeline `riepilogo-ordini`, istanziata da un nodo `pipeline` (ADR-0079): `fact-contract`, `tier-summary` e `tier-summary-contract` lasciano il posto ai nodi dell'istanza, e i due sink leggono dalle sue uscite `fatti` e `per-tier`</li><li data-v-cdcb1722>Un ordine con importo non positivo è rifiutato al confine d'ingresso dell'istanza invece che da `fact-contract`; il `guard` lo cattura e lo instrada sul ramo `catch` come prima</li><!--]--></ul></div><!--]--><!--[--><!----><!--]--><!--]--><div class="pipeline-versions__diff" data-v-cdcb1722><!--[--><p class="pipeline-versions__note" data-v-cdcb1722> Il piano rispetto alla v1: </p><dl data-v-cdcb1722><!----><!--[--><!--[--><dt data-v-cdcb1722>Nodi <!----></dt><dd data-v-cdcb1722><ul data-v-cdcb1722><!--[--><li class="is-added" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>+</span><code data-v-cdcb1722>riepilogo-ordini</code><span data-v-cdcb1722>transform</span></li><li class="is-added" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>+</span><code data-v-cdcb1722>riepilogo-ordini/tier-summary</code><span data-v-cdcb1722>transform</span></li><li class="is-added" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>+</span><code data-v-cdcb1722>riepilogo-ordini/per-tier</code><span data-v-cdcb1722>transform</span></li><li class="is-added" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>+</span><code data-v-cdcb1722>riepilogo-ordini/fatti</code><span data-v-cdcb1722>transform</span></li><li class="is-removed" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>−</span><code data-v-cdcb1722>fact-contract</code><span data-v-cdcb1722>transform</span></li><li class="is-removed" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>−</span><code data-v-cdcb1722>tier-summary</code><span data-v-cdcb1722>transform</span></li><li class="is-removed" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>−</span><code data-v-cdcb1722>tier-summary-contract</code><span data-v-cdcb1722>transform</span></li><!--]--></ul></dd><!--]--><!--[--><dt data-v-cdcb1722>Archi <!----></dt><dd data-v-cdcb1722><ul data-v-cdcb1722><!--[--><li class="is-added" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>+</span><code data-v-cdcb1722>guard → riepilogo-ordini</code><span data-v-cdcb1722>porta out</span></li><li class="is-added" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>+</span><code data-v-cdcb1722>riepilogo-ordini/fatti → enriched_orders</code><!----></li><li class="is-added" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>+</span><code data-v-cdcb1722>riepilogo-ordini/per-tier → tier_summary</code><!----></li><li class="is-added" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>+</span><code data-v-cdcb1722>riepilogo-ordini → riepilogo-ordini/tier-summary</code><!----></li><li class="is-added" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>+</span><code data-v-cdcb1722>riepilogo-ordini/tier-summary → riepilogo-ordini/per-tier</code><!----></li><li class="is-added" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>+</span><code data-v-cdcb1722>riepilogo-ordini → riepilogo-ordini/fatti</code><!----></li><li class="is-removed" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>−</span><code data-v-cdcb1722>guard → fact-contract</code><span data-v-cdcb1722>porta out</span></li><li class="is-removed" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>−</span><code data-v-cdcb1722>fact-contract → enriched_orders</code><!----></li><li class="is-removed" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>−</span><code data-v-cdcb1722>fact-contract → tier-summary</code><!----></li><li class="is-removed" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>−</span><code data-v-cdcb1722>tier-summary → tier-summary-contract</code><!----></li><li class="is-removed" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>−</span><code data-v-cdcb1722>tier-summary-contract → tier_summary</code><!----></li><!--]--></ul></dd><!--]--><!--]--></dl><!--]--></div></article><article class="pipeline-versions__entry" data-v-cdcb1722><header class="pipeline-versions__header" data-v-cdcb1722><strong class="pipeline-versions__number" data-v-cdcb1722>v1</strong><span class="pipeline-versions__meta" data-v-cdcb1722>2026-10-05 · ETL-120</span><!----></header><!----><!--[--><!--[--><div class="pipeline-versions__list" data-v-cdcb1722><span class="pipeline-versions__list-title" data-v-cdcb1722>Aggiunte</span><ul data-v-cdcb1722><!--[--><li data-v-cdcb1722>Versione iniziale sotto versionamento (ADR-0086)</li><!--]--></ul></div><!--]--><!--[--><!----><!--]--><!--[--><!----><!--]--><!--]--><div class="pipeline-versions__diff" data-v-cdcb1722><p class="pipeline-versions__note" data-v-cdcb1722> Prima versione: non c'è una versione precedente da confrontare. </p></div></article><!--]--></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/pipelines/movimenti-per-conto" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina precedente</span><span class="title" data-v-64d0b887>movimenti-per-conto</span><!--]--></a></div><div class="pager" data-v-64d0b887><a class="VPLink link pager-link next" href="/guida/core/sub-pipelines/riepilogo-ordini" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina successiva</span><span class="title" data-v-64d0b887>riepilogo-ordini</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>
|
|
65
|
-
<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\":\"
|
|
65
|
+
<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>
|
|
66
66
|
|
|
67
67
|
</body>
|
|
68
68
|
</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.
|
|
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.
|
|
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/pipelines_test-posta.md.Cxo_DGBs.lean.js">
|
|
17
17
|
<link rel="icon" type="image/svg+xml" href="/guida/core/favicon.svg">
|
|
@@ -40,7 +40,7 @@ host: smtp.esempio
|
|
|
40
40
|
porta: 587
|
|
41
41
|
mittente: noeva@esempio
|
|
42
42
|
</title><rect class="dag-node__halo" x="738" y="12" width="198" height="74" rx="12" data-v-340130bc></rect><!----><rect class="dag-node__card" x="742" y="16" width="190" height="66" rx="9" data-v-340130bc></rect><rect class="dag-node__accent" x="742" y="22" width="3" height="54" rx="1.5" data-v-340130bc></rect><text class="dag-node__label" x="754" y="35" data-v-340130bc>notifica</text><text class="dag-node__kind" x="922" y="35" text-anchor="end" data-v-340130bc>sink</text><!--[--><text class="dag-node__sub" x="754" y="51" data-v-340130bc>smtp</text><text class="is-detail dag-node__sub" x="754" y="64" data-v-340130bc>host: smtp.esempio</text><!--]--><!--[--><!--]--></g><!--]--><!--[--><!--]--></svg><!--[--><!--]--><!----></div><!----><figcaption class="graph-demo__footer" data-v-fc9b2f46><span class="graph-demo__progress" aria-hidden="true" data-v-fc9b2f46><span style="width:0%;" data-v-fc9b2f46></span></span><span class="graph-demo__caption" aria-live="polite" data-v-fc9b2f46><!--[--> Scegli una scena e premi ▶ per guardarla scorrere, oppure → per andare avanti un passo alla volta. <!--]--></span></figcaption></figure><figure class="level-nav__purposes" data-v-c981a055><figcaption id="level-nav-purposes-v-0" class="level-nav__purposes-title" data-v-c981a055> Lo scopo dei nodi </figcaption><table aria-labelledby="level-nav-purposes-v-0" data-v-c981a055><thead data-v-c981a055><tr data-v-c981a055><th scope="col" data-v-c981a055>Nodo</th><th scope="col" data-v-c981a055>Tipo</th><th scope="col" data-v-c981a055>Scopo</th></tr></thead><tbody data-v-c981a055><!--[--><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>casella-prova</code></td><td data-v-c981a055><code data-v-c981a055>source</code></td><td data-v-c981a055>Legge alcune mail dalla cartella di posta configurata, senza segnarle come lette né spostarle. Se questo passo riesce, l'accesso alla casella funziona.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>salva-eml</code></td><td data-v-c981a055><code data-v-c981a055>action</code></td><td data-v-c981a055>Salva una copia di ogni mail letta nella cartella locale dell'installazione, per controllare che cosa è arrivato. Rilanciando la prova, le stesse mail riscrivono gli stessi file.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>riepilogo</code></td><td data-v-c981a055><code data-v-c981a055>transform</code></td><td data-v-c981a055>Riunisce le mail salvate in un unico riepilogo, con quante sono e quanto pesano. Serve perché la prova mandi una mail sola invece di una per messaggio.</td></tr><tr data-v-c981a055><td data-v-c981a055><code data-v-c981a055>notifica</code></td><td data-v-c981a055><code data-v-c981a055>sink</code></td><td data-v-c981a055>Manda l'unica mail di riepilogo della prova. Se arriva, l'invio della posta da questa installazione funziona.</td></tr><!--]--></tbody></table></figure></div><p>Lo scopo di ogni nodo è nella tabella sotto il grafo, presa dal piano. Qui il dettaglio tecnico che lo scopo non dice:</p><table tabindex="0"><thead><tr><th>Nodo</th><th>Tipo</th><th>Dettaglio tecnico</th></tr></thead><tbody><tr><td><code>posta</code></td><td><code>source</code></td><td>IMAP, cartella configurata, al più <code>MAX_MESSAGES</code> mail</td></tr><tr><td><code>salva-eml</code></td><td><code>action</code></td><td>File <code><uid a 8 cifre>-<oggetto ripulito>.eml</code>, vedi <a href="#idempotenza">Idempotenza</a></td></tr><tr><td><code>riepilogo</code></td><td><code>transform</code></td><td><code>groupBy</code> su chiave costante: N messaggi → un record</td></tr><tr><td><code>notifica</code></td><td><code>sink</code></td><td>SMTP</td></tr></tbody></table><p>La chiave del <code>groupBy</code> di <code>riepilogo</code> è costante proprio perché il gruppo dev'essere uno solo.</p><h2 id="che-cosa-non-fa" tabindex="-1">Che cosa <strong>non</strong> fa <a class="header-anchor" href="#che-cosa-non-fa" aria-label="Permalink to "Che cosa **non** fa""></a></h2><p><strong>Non tocca la casella.</strong> Niente <code>\Seen</code>, niente keyword, niente spostamenti: dopo la run la cartella è esattamente com'era. È ciò che la rende rilanciabile quante volte serve mentre si sistema una configurazione — al contrario di una pipeline che usa la cartella come coda, dove lo spostamento in <code>Done</code> è il commit e una mail si lavora una volta sola.</p><p><strong>Non salva gli allegati.</strong> Sono dentro l'<code>.eml</code>, che è il messaggio RFC 822 integro; il riepilogo ne dichiara il numero per messaggio. Se serve verificarne i byte su disco, si apre l'<code>.eml</code>.</p><p><strong>Non elenca più di 50 messaggi nella mail.</strong> Oltre quella soglia il corpo tronca e lo dichiara («… e altri N messaggi»). Col tetto di default — 5 — non succede mai; succede se alzi <code>TEST_POSTA_MAX_MESSAGES</code>.</p><p><strong>Non ha dead-letter, e non è una dimenticanza.</strong> Un errore ferma la run e arriva intero nel report. In una pipeline di produzione mettere da parte il record rotto è giusto; qui il record rotto <strong>è</strong> il risultato dell'esperimento, e archiviarlo farebbe passare per riuscita una prova che non lo è. Un messaggio che IMAP non riesce a scaricare (<code>eml</code> nullo) alza <code>ExtractError</code> e nessuna mail parziale parte.</p><h2 id="idempotenza" tabindex="-1">Idempotenza <a class="header-anchor" href="#idempotenza" aria-label="Permalink to "Idempotenza""></a></h2><p>Il nome del file è <code><uid a 8 cifre>-<oggetto ripulito>.eml</code>. Due run sulla stessa casella riscrivono gli stessi file, non ne accumulano copie. Lo zero padding serve alla lettura a occhio: senza, <code>10.eml</code> verrebbe prima di <code>9.eml</code>.</p><p>L'oggetto che entra nel nome perde tutto ciò che non è lettera, cifra o trattino basso — punti e separatori di percorso compresi. Un oggetto costruito apposta (<code>../../etc/passwd</code>) non può quindi far uscire il file dalla cartella di destinazione.</p><h2 id="casella-vuota" tabindex="-1">Casella vuota <a class="header-anchor" href="#casella-vuota" aria-label="Permalink to "Casella vuota""></a></h2><p>Nessun messaggio letto significa nessuna mail inviata: il <code>groupBy</code> non ha gruppi da emettere. <strong>La run resta un successo</strong>, e che la casella fosse vuota si legge dal report (<code>extracted: 0</code>), non dall'assenza della mail. Vale la pena saperlo prima di concludere che SMTP non funziona.</p><p>È il limite di questa prova, e va conosciuto: su casella vuota dimostra metà della tesi — che IMAP si collega e non trova nulla — e di SMTP non dice niente. Per provare anche l'invio serve almeno un messaggio nella cartella.</p><h2 id="configurazione" tabindex="-1">Configurazione <a class="header-anchor" href="#configurazione" aria-label="Permalink to "Configurazione""></a></h2><p>Tutte le variabili stanno in <code>.env</code>, nessun indirizzo e nessun percorso è nel codice. I valori fittizi sono in <code>.env.example</code>.</p><table tabindex="0"><thead><tr><th>Variabile</th><th>Obbl.</th><th>Default</th><th>Che cos'è</th></tr></thead><tbody><tr><td><code>TEST_POSTA_CARTELLA_LOCALE</code></td><td>sì</td><td>—</td><td>Dove finiscono gli <code>.eml</code></td></tr><tr><td><code>TEST_POSTA_DESTINATARIO</code></td><td>sì</td><td>—</td><td>L'unico destinatario del riepilogo</td></tr><tr><td><code>TEST_POSTA_IMAP_INSTANCE</code></td><td>no</td><td><code>default</code></td><td>Istanza IMAP nel registry</td></tr><tr><td><code>TEST_POSTA_SMTP_INSTANCE</code></td><td>no</td><td><code>default</code></td><td>Istanza SMTP nel registry</td></tr><tr><td><code>TEST_POSTA_CARTELLA</code></td><td>no</td><td><code>INBOX</code></td><td>Cartella IMAP da leggere</td></tr><tr><td><code>TEST_POSTA_MAX_MESSAGES</code></td><td>no</td><td><code>5</code></td><td>Tetto ai messaggi per run</td></tr></tbody></table><p>Host, porte e credenziali vengono dai registry dei connettori (<code>IMAP_*</code>, <code>SMTP_*</code>). <strong>Usa le stesse istanze della pipeline vera</strong>: provare istanze diverse da quelle che userà la pipeline di produzione non prova niente di ciò che interessa.</p><p>Su Gmail, Workspace e Microsoft 365 la password via IMAP e SMTP non esiste più: l'autenticazione passa da OAuth2, e questa pipeline è il modo di verificarla. Vedi il runbook <a href="./../runbooks/oauth-google-posta">oauth-google-posta.md</a>.</p><p>Il mittente non è configurabile qui: è <code>SMTP_FROM</code> dell'istanza, perché un'identità diversa è un'altra istanza.</p><p>Con variabili mancanti la run si ferma prima di toccare la casella, con <strong>un</strong> <code>ConfigError</code> che le elenca tutte insieme, della pipeline e dei connettori: si corregge il <code>.env</code> in un giro solo. Le stesse si vedono prima di lanciarla con <code>pnpm run etl env check</code>: la pipeline dichiara le variabili che legge (<code>environment</code>), compresi l'utente della casella e, se la casella è su OAuth2 senza token, l'identità <code>OAUTH_*</code> che lo rinnova.</p><h3 id="che-cosa-mostra-il-dag" tabindex="-1">Che cosa mostra il DAG <a class="header-anchor" href="#che-cosa-mostra-il-dag" aria-label="Permalink to "Che cosa mostra il DAG""></a></h3><p>Il pannello di ogni nodo dice, per ogni valore, da quale variabile arriva e la sua origine: <code>env</code> (impostata), <code>default</code> (presa dal codice), <code>mancante</code> (obbligatoria e assente), <code>non impostata</code> (facoltativa). Host e porta sono righe distinte, e la credenziale è una riga a parte che dice solo la variante in uso: password, access token o identità OAuth2. Con OAuth2 dice anche se l'identità <code>OAUTH_*</code> che rinnova il token è completa, o quali sue variabili mancano; un <code>IMAP_USER</code> mancante, che non ha una riga sua, lo segnala questa stessa riga.</p><p>Il piano ricade sull'esempio <strong>un'istanza alla volta</strong>. Se manca <code>TEST_POSTA_CARTELLA_LOCALE</code>, solo <code>salva-eml</code> mostra <code>/percorso/di/esempio</code>, con la variabile marcata <code>mancante</code>; la casella IMAP e il server SMTP mostrano i valori veri del <code>.env</code>. Allo stesso modo, un'istanza IMAP rotta non trascina le altre: se <code>TEST_POSTA_IMAP_INSTANCE</code> indica una casella sana, il nodo la mostra anche quando un'altra casella del registry è incompleta. Se una casella non si costruisce per un valore non valido (password e token impostati insieme, una porta non numerica), il suo nodo porta la riga <code>configurazione: non valida</code>, con i nomi delle variabili da controllare.</p><p>A nodo non selezionato, il piano porta la <strong>configurazione della pipeline</strong>: tutte le variabili <code>TEST_POSTA_*</code>, con valore e origine. È l'unico posto in cui compare <code>TEST_POSTA_DESTINATARIO</code>, che non è il dettaglio di nessun nodo. Una variabile <code>mancante</code> non ha valore: qui non c'è un segnaposto d'esempio.</p><p>Il server dei grafi calcola il piano all'avvio: dopo una modifica al <code>.env</code> va riavviato. L'ora di calcolo del piano dice se il riavvio è avvenuto (<a href="./../runbooks/graph-server">runbook del server</a>).</p><p><code>test-posta</code> è una pipeline pronta: un repo cliente la usa dichiarandola nel catalogo del suo <code>etl.config.ts</code>. Se l'installazione limita le pipeline per workspace con <code>ETL_PIPELINE_WORKSPACES</code>, va assegnata anche ai workspace in cui deve girare, altrimenti lì non compare nella UI e il worker rifiuta un processo che la chiede. Da CLI funziona comunque: <code>etl run</code> risolve per nome senza passare dal filtro.</p><h2 id="come-si-lancia" tabindex="-1">Come si lancia <a class="header-anchor" href="#come-si-lancia" aria-label="Permalink to "Come si lancia""></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;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> test-posta</span></span></code></pre></div><p>Che cosa guardare, in ordine:</p><ol><li><strong>Il report</strong>: <code>extracted</code> sono le mail lette, <code>written</code> le mail <strong>inviate</strong> (quindi <code>1</code>, non il numero di file scritti), <code>rejected</code> gli scarti. Se <code>extracted</code> è 0 la casella era vuota e il resto non dimostra nulla. I file scritti si contano in <code>nodes[]</code>, alla voce <code>salva-eml</code>.</li><li><strong>La cartella locale</strong>: un <code>.eml</code> per messaggio, apribile con un client di posta.</li><li><strong>La mail</strong>: arriva al destinatario configurato, con mittente, data, numero di allegati e percorso per ciascun messaggio (fino a 50). Se gli accenti si leggono, la codifica ha attraversato IMAP e SMTP intatta. Una riga <code>ATTENZIONE: non interpretabile</code> segnala un messaggio che il parser ha rifiutato: l'<code>.eml</code> è stato comunque salvato, ma i suoi campi nel riepilogo sono vuoti perché non si sono potuti leggere, non perché la mail fosse vuota.</li></ol><h2 id="test" tabindex="-1">Test <a class="header-anchor" href="#test" aria-label="Permalink to "Test""></a></h2><table tabindex="0"><thead><tr><th>File</th><th>Che cosa copre</th></tr></thead><tbody><tr><td><code>config.test.ts</code></td><td>Variabili obbligatorie, default, <code>MAX_MESSAGES</code> non valido, tutte le mancanti in <code>ConfigError.mancanti</code>, configurazione d'esempio del piano</td></tr><tr><td><code>salvataggio.test.ts</code></td><td>Sanificazione dell'oggetto (compreso <code>../../etc/passwd</code>), zero padding, idempotenza per uid, <code>eml</code> nullo, motivo di parsing riportato</td></tr><tr><td><code>notifica.test.ts</code></td><td>Corpo della mail, troncamento a 50 righe, riga di attenzione, assenza di <code>chiave</code></td></tr><tr><td><code>pipeline.test.ts</code></td><td>End-to-end con <code>arraySource</code>/<code>arraySink</code>: N messaggi → <strong>una</strong> mail, casella vuota, messaggio illeggibile che ferma la run, topologia</td></tr><tr><td><code>run.test.ts</code></td><td>Registrazione, ricaduta per istanza (cartella locale mancante, istanza IMAP rotta), variabile e origine per riga, riga <code>credenziale</code>, configurazione della pipeline nel piano, piano deterministico senza <code>.env</code>, run fail-fast con l'elenco completo</td></tr></tbody></table><h2 id="versioni" tabindex="-1">Versioni <a class="header-anchor" href="#versioni" aria-label="Permalink to "Versioni""></a></h2><p>La storia della pipeline, dalla versione più recente: la voce di changelog di ogni versione (<code>src/pipelines/test-posta/changelog.ts</code>) e, sotto, cosa è cambiato nel piano rispetto alla precedente. Vedi <a href="./../conventions/versioni-di-pipeline">versioni di pipeline</a>.</p><div class="pipeline-versions" data-v-cdcb1722><!--[--><article class="pipeline-versions__entry" data-v-cdcb1722><header class="pipeline-versions__header" data-v-cdcb1722><strong class="pipeline-versions__number" data-v-cdcb1722>v3</strong><span class="pipeline-versions__meta" data-v-cdcb1722>2026-10-09 · ETL-193, ETL-194, ETL-195, ETL-202</span><!----></header><!----><!--[--><!--[--><!----><!--]--><!--[--><div class="pipeline-versions__list" data-v-cdcb1722><span class="pipeline-versions__list-title" data-v-cdcb1722>Modifiche</span><ul data-v-cdcb1722><!--[--><li data-v-cdcb1722>Nessun cambio di comportamento: il piano è identico alla v2. Gli import seguono l'infrastruttura (changelog, configurazione delle istanze, report di volume) uscita da `src/pipelines/` (ADR-0093 §1), e la pipeline si dichiara nel catalogo di `etl.config.ts` invece che in un registro (ADR-0093 §2)</li><li data-v-cdcb1722>Porta il marchio di pipeline pronta del core, che il caricamento del catalogo riconosce (ADR-0094 §2): il piano non cambia</li><li data-v-cdcb1722>Dichiara le variabili d'ambiente che legge (`environment`) per `etl env check`, dagli stessi manifest della run: casella IMAP, server SMTP, identità OAuth2 se la casella la usa, e `TEST_POSTA_*` (ADR-0094 §1). Il piano non cambia</li><!--]--></ul></div><!--]--><!--[--><!----><!--]--><!--]--><div class="pipeline-versions__diff" data-v-cdcb1722><p class="pipeline-versions__note" data-v-cdcb1722> Il piano non cambia rispetto alla v2. </p></div></article><article class="pipeline-versions__entry" data-v-cdcb1722><header class="pipeline-versions__header" data-v-cdcb1722><strong class="pipeline-versions__number" data-v-cdcb1722>v2</strong><span class="pipeline-versions__meta" data-v-cdcb1722>2026-10-05 · ETL-150, ETL-152, ETL-154</span><!----></header><!----><!--[--><!--[--><div class="pipeline-versions__list" data-v-cdcb1722><span class="pipeline-versions__list-title" data-v-cdcb1722>Aggiunte</span><ul data-v-cdcb1722><!--[--><li data-v-cdcb1722>Variabile e origine (env, default, mancante, non impostata) su ogni riga dei connettori IMAP, SMTP e della cartella locale (ADR-0089)</li><li data-v-cdcb1722>Riga `credenziale` con la variante in uso e il suo stato, mai il valore</li><li data-v-cdcb1722>Configurazione della pipeline nel piano: tutte le variabili `TEST_POSTA_*` con valore e origine, compreso il destinatario che nessun nodo mostra</li><!--]--></ul></div><!--]--><!--[--><div class="pipeline-versions__list" data-v-cdcb1722><span class="pipeline-versions__list-title" data-v-cdcb1722>Modifiche</span><ul data-v-cdcb1722><!--[--><li data-v-cdcb1722>Il piano ricade sulla configurazione d'esempio per istanza di connettore, non per l'intero piano: una cartella locale mancante non nasconde IMAP e SMTP</li><li data-v-cdcb1722>Host e porta sono righe separate</li><li data-v-cdcb1722>Con un utente IMAP mancante, la riga `credenziale` lo dice; con OAuth2, dice se l'identità che rinnova il token è completa</li><!--]--></ul></div><!--]--><!--[--><!----><!--]--><!--]--><div class="pipeline-versions__diff" data-v-cdcb1722><!--[--><p class="pipeline-versions__note" data-v-cdcb1722> Il piano rispetto alla v1: </p><dl data-v-cdcb1722><!----><!--[--><!--[--><dt data-v-cdcb1722>Nodi <!----></dt><dd data-v-cdcb1722><ul data-v-cdcb1722><!--[--><li class="is-changed" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>~</span><code data-v-cdcb1722>posta</code><span data-v-cdcb1722>connettore</span></li><li class="is-changed" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>~</span><code data-v-cdcb1722>salva-eml</code><span data-v-cdcb1722>connettore</span></li><li class="is-changed" data-v-cdcb1722><span class="pipeline-versions__sign" data-v-cdcb1722>~</span><code data-v-cdcb1722>notifica</code><span data-v-cdcb1722>connettore</span></li><!--]--></ul></dd><!--]--><!--]--></dl><!--]--></div></article><article class="pipeline-versions__entry" data-v-cdcb1722><header class="pipeline-versions__header" data-v-cdcb1722><strong class="pipeline-versions__number" data-v-cdcb1722>v1</strong><span class="pipeline-versions__meta" data-v-cdcb1722>2026-10-05 · ETL-120</span><!----></header><!----><!--[--><!--[--><div class="pipeline-versions__list" data-v-cdcb1722><span class="pipeline-versions__list-title" data-v-cdcb1722>Aggiunte</span><ul data-v-cdcb1722><!--[--><li data-v-cdcb1722>Versione iniziale sotto versionamento (ADR-0086)</li><!--]--></ul></div><!--]--><!--[--><!----><!--]--><!--[--><!----><!--]--><!--]--><div class="pipeline-versions__diff" data-v-cdcb1722><p class="pipeline-versions__note" data-v-cdcb1722> Prima versione: non c'è una versione precedente da confrontare. </p></div></article><!--]--></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/pipelines/README" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina precedente</span><span class="title" data-v-64d0b887>Le schede di una pipeline</span><!--]--></a></div><div class="pager" data-v-64d0b887><a class="VPLink link pager-link next" href="/guida/core/sub-pipelines/README" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina successiva</span><span class="title" data-v-64d0b887>Le schede di una sub-pipeline</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>
|
|
43
|
-
<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\":\"
|
|
43
|
+
<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>
|
|
44
44
|
|
|
45
45
|
</body>
|
|
46
46
|
</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.
|
|
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.
|
|
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/runbooks_aggiornamento-pm2.md.f3LAxif4.lean.js">
|
|
17
17
|
<link rel="icon" type="image/svg+xml" href="/guida/core/favicon.svg">
|
|
@@ -45,7 +45,7 @@
|
|
|
45
45
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> checkout</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --detach</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sha-precedent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span>
|
|
46
46
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --frozen-lockfile</span></span>
|
|
47
47
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> docs</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build</span></span></code></pre></div><p>Ripristina la copia di <code>.env</code> salvata al § 4: con il codice vecchio una variabile nuova è inutile, ma in <code>ETL_PIPELINE_WORKSPACES</code> una pipeline che il codice vecchio non conosce ferma l'avvio. Poi <code>pm2 reload ecosystem.config.cjs</code> e le verifiche del § 5, che ora si aspettano la release <code>git:<sha-precedente></code>, il core e le versioni di pipeline di prima.</p><p>Il rollback del deploy riporta indietro il codice, non i dati:</p><ul><li>i dati già scritti dal rilascio ritirato restano dove sono;</li><li>lo stato di pipeline non torna indietro. Se il rilascio ritirato ha avanzato un watermark, o ha cambiato cosa misura, valuta un reset con <a href="./stato-incrementale#reset">stato incrementale § Reset</a>;</li><li>il deploy ora è <strong>dietro</strong> <code>main</code>. Il prossimo aggiornamento riporta il rilascio ritirato, quindi la correzione va su <code>main</code> prima di riaggiornare.</li></ul><h3 id="una-pipeline-sola-o-il-core" tabindex="-1">Una pipeline sola, o il core <a class="header-anchor" href="#una-pipeline-sola-o-il-core" aria-label="Permalink to "Una pipeline sola, o il core""></a></h3><p>Se a regredire è una pipeline sola, non serve riportare indietro tutto il deploy: il <strong>rollback di pipeline</strong> (<code>pnpm exec etl versions rollback <pipeline> <N> --motivo "…" --ticket <chiave></code>) prepara un <code>hotfix/*</code> da <code>main</code> che riporta solo la cartella della pipeline a una sua versione precedente, come versione nuova. Se a regredire è il core, il <strong>downgrade del core</strong> è una PR <code>hotfix/*</code> che abbassa <code>@noeva/etl-core</code> nel <code>package.json</code>. Le procedure sono in <a href="./rollback-di-pipeline#tre-rollback-tre-nomi">Rollback di una pipeline</a>; dopo il merge su <code>main</code>, l'hotfix arriva al deploy con questo stesso runbook.</p><h2 id="escalation" tabindex="-1">Escalation <a class="header-anchor" href="#escalation" aria-label="Permalink to "Escalation""></a></h2><ul><li>Primo livello: chi mantiene il repo cliente, con lo SHA di partenza e d'arrivo, l'output di <code>pm2 ls</code> e di <code>pnpm exec etl env check</code>, e le ultime righe di <code>logs/noeva-etl-error.log</code>.</li><li>Un problema che viene dal core (un <code>ConfigError</code> del core dopo un bump, una regressione dopo «Cambia il piano»): il team del core, con la versione di partenza e d'arrivo di <code>@noeva/etl-core</code>.</li><li>Una run interrotta dall'aggiornamento con effetti esterni dubbi: l'owner della pipeline, dalla sua scheda in <code>docs/pipelines/</code>, prima di rimetterla in coda.</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/sub-pipelines/riepilogo-ordini" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina precedente</span><span class="title" data-v-64d0b887>riepilogo-ordini</span><!--]--></a></div><div class="pager" data-v-64d0b887><a class="VPLink link pager-link next" href="/guida/core/runbooks/deployment" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina successiva</span><span class="title" data-v-64d0b887>distribuzione del runner ETL</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>
|
|
48
|
-
<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\":\"
|
|
48
|
+
<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>
|
|
49
49
|
|
|
50
50
|
</body>
|
|
51
51
|
</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.
|
|
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.
|
|
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/runbooks_deployment.md.DvIOOsoG.lean.js">
|
|
17
17
|
<link rel="icon" type="image/svg+xml" href="/guida/core/favicon.svg">
|
|
@@ -35,7 +35,7 @@
|
|
|
35
35
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --rm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --env-file</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .env</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">imag</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</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;">></span></span></code></pre></div><blockquote><p><strong>Pipeline incrementali:</strong> senza <code>--workspace</code> lo stato di pipeline è un file in <code>ETL_STATE_DIR</code> (default <code>.state/</code>), e il filesystem di un container <code>--rm</code> si perde a ogni run: la pipeline ripartirebbe sempre da <code>initial</code>. Usare <code>run <pipeline> --workspace <id></code> (stato su <code>noeva-server-api</code>, lo stesso del worker), oppure montare un volume scrivibile dall'utente del container su <code>ETL_STATE_DIR</code>. Vedi <a href="./stato-incrementale">stato incrementale</a>.</p></blockquote><p>Variabili richieste: quelle della pipeline, elencate nella sua <a href="./../pipelines/README">scheda</a> e in <code>.env.example</code>, più quelle del core (<a href="./../conventions/variabili-del-core">Variabili d'ambiente del core</a>). In produzione iniettarle da un <strong>secret manager</strong> (AWS Secrets Manager / SSM), non da <code>.env</code>.</p><h2 id="modelli-di-deploy-per-cliente" tabindex="-1">Modelli di deploy per cliente <a class="header-anchor" href="#modelli-di-deploy-per-cliente" aria-label="Permalink to "Modelli di deploy per cliente""></a></h2><p>Il servizio gira tipicamente sull'<strong>infra del cliente</strong>. L'immagine abilita i primi tre modelli; PM2 gira dai sorgenti, senza immagine:</p><table tabindex="0"><thead><tr><th>Modello</th><th>Come</th><th>Note</th></tr></thead><tbody><tr><td><strong>Gestito da noi</strong></td><td>Un servizio ECS per cliente con <code>etl serve</code>, definito in Terraform</td><td>Il job parte dallo scheduler di Noeva</td></tr><tr><td><strong>ECS del cliente</strong></td><td>Stessa immagine, task definition nel loro account</td><td>Solo accesso al registry + secrets del cliente</td></tr><tr><td><strong>Docker locale del cliente</strong></td><td><code>docker run</code> schedulato da cron sul loro host</td><td>Più semplice; idempotenza rende sicuri retry/sovrapposizioni</td></tr><tr><td><strong>PM2 dai sorgenti</strong></td><td><code>ecosystem()</code> del pacchetto: <code>etl serve</code> dal repo, senza build</td><td>Per un server Windows senza Docker</td></tr></tbody></table><h2 id="scheduling" tabindex="-1">Scheduling <a class="header-anchor" href="#scheduling" aria-label="Permalink to "Scheduling""></a></h2><p>La pipeline è <strong>idempotente</strong> (upsert/MERGE su chiave naturale): rieseguire o sovrapporre run non duplica dati. Quindi lo scheduler può essere semplice:</p><ul><li><strong>cron</strong> che lancia <code>docker run ... run <pipeline></code>;</li><li><strong>ECS Scheduled Task</strong> (cron via EventBridge);</li><li>per dipendenze/backfill complessi in futuro → orchestratore (es. Temporal TS).</li></ul><h2 id="networking" tabindex="-1">Networking <a class="header-anchor" href="#networking" aria-label="Permalink to "Networking""></a></h2><p>Il container deve raggiungere <strong>sorgente e sink</strong> (PG e SQL Server), che possono stare su host/VPC diversi. In locale, dai container verso DB sull'host: usare <code>host.docker.internal</code> come <code>*HOST</code>. In cloud: curare security group / routing verso entrambi i DB.</p><h2 id="osservabilita-—-il-report-di-run-e-il-risultato" tabindex="-1">Osservabilità — il report di run è il risultato <a class="header-anchor" href="#osservabilita-—-il-report-di-run-e-il-risultato" aria-label="Permalink to "Osservabilità — il report di run è il risultato""></a></h2><p>Il servizio è <strong>stateless</strong>: emette un <strong>report</strong> e termina (niente DB lato servizio).</p><ul><li><strong><code>stdout</code></strong> = il report in JSON (un oggetto). <strong><code>stderr</code></strong> = log umani.</li><li><strong>exit code</strong>: <code>0</code> se <code>success</code>/<code>partial</code>, <code>≠0</code> se <code>failed</code> (utile per alerting dello scheduler).</li><li>Anche in errore viene emesso un report <code>status: "failed"</code>.</li></ul><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:#6A737D;--shiki-dark:#6A737D;"># cattura il report e i log separatamente</span></span>
|
|
36
36
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./run-ecr.sh</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</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;">></span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> report.json</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> 2></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run.log</span></span>
|
|
37
37
|
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># archivialo dove vuoi (è il chiamante a deciderlo): file, S3, CloudWatch, ...</span></span></code></pre></div><p>Schema completo e semantica: <a href="./../conventions/run-report">docs/conventions/run-report.md</a>.</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/runbooks/aggiornamento-pm2" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina precedente</span><span class="title" data-v-64d0b887>aggiornare un deploy PM2 di un repo cliente</span><!--]--></a></div><div class="pager" data-v-64d0b887><a class="VPLink link pager-link next" href="/guida/core/runbooks/etl-worker" data-v-64d0b887><!--[--><span class="desc" data-v-64d0b887>Pagina successiva</span><span class="title" data-v-64d0b887>worker etl worker (polling su processes)</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>
|
|
38
|
-
<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\":\"
|
|
38
|
+
<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>
|
|
39
39
|
|
|
40
40
|
</body>
|
|
41
41
|
</html>
|