Runbook: verifica bump versione file Noeva

Sintesi

• Cosa fa: test di integrazione manuale che scarica prova-etl.json da un workspace Noeva reale, incrementa/inizializza la proprietà version, e lo ricarica come nuova versione — verifica end-to-end del connettore noeva (scheda ADR) contro l'API vera, non contro un client fake.
• Owner: team BI/ETL.
• Schedulazione: solo manuale, mai in CI (vedi "Effetto collaterale" sotto).
• Criticità: bassa — è un test di verifica, non un processo che serve a valle.

Esecuzione normale

pnpm exec vitest run --config vitest.integration.config.ts \
  tests/integration/noeva-file-version-bump.integration.test.ts

• Variabili d'ambiente richieste (in .env, vedi .env.example): NOEVA_API_BASE_URL, NOEVA_API_KEY (service-role), NOEVA_WORKSPACE_ID.
• Senza queste variabili il test si skippa silenziosamente (describe.skipIf) — non fallisce la build né pnpm run check/pnpm run test:integration in CI.
• Prerequisito: il file prova-etl.json deve già esistere nel workspace indicato (il test recupera per nome esatto, non crea il file da zero).
• Output atteso: 1 test verde; il file ricaricato ha version pari a (version precedente + 1), o 0 se il file non aveva ancora la proprietà.

Effetto collaterale (importante)

Ogni esecuzione crea davvero una nuova versione reale di prova-etl.json nel workspace configurato — non è un'operazione a costo zero né reversibile via codice. Per questo:

• non va aggiunto a nessuna pipeline CI schedulata;
• va eseguito solo quando serve verificare esplicitamente il connettore contro l'API reale;
• se le versioni si accumulano nel workspace, la pulizia va fatta manualmente dall'app Noeva.

Procedure di recovery

Il test fallisce con "Nessun file con nome esatto prova-etl.json"

Il file non esiste ancora nel workspace configurato. Non viene creato automaticamente dal test. Per crearlo la prima volta, usare noevaFileSink in modalità overwrite con un contenuto JSON iniziale (es. {}), poi rilanciare il test.

Il test fallisce per errori di rete/autenticazione

Verificare che NOEVA_API_KEY sia una chiave service-role (non per-utente, vedi ADR 0014 punto 5) — una chiave per-utente non vede i file di altri utenti nel workspace.

Escalation

• Primo livello: owner del connettore noeva (team BI/ETL).