Supportare output multi-anno espliciti nel toolkit

[Gabrymi93]

Problema

Nel toolkit attuale, raw, clean e mart sono eseguiti per singolo year.

Questo funziona bene per pipeline annuali, ma non copre bene un caso ormai ricorrente: dataset con years dichiarati che hanno bisogno anche di un output finale multi-anno.

Caso reale:

• IRPEF comunale 2019-2023
• pipeline annuale stabile
• per rispondere alla domanda analitica serve un output unico cross-year con:
  • serie storica
  • delta vs anno precedente
  • ranking nel tempo
  • quote territoriali nel tempo

Oggi questo richiede uno step esplicito di progetto fuori dal contract nativo del toolkit.

Proposta

Aggiungere un supporto esplicito e opzionale per output multi-anno, per esempio:

cross_year:
  tables:
    - name: irpef_capacita_fiscale_multi_anno
      sql: sql/mart_multi_anno.sql
      source_layer: clean

Vincoli della feature

• non automatico per tutti i dataset con years
• esecuzione una sola volta per dataset
• dopo il completamento degli anni richiesti
• input annuali leggibili da clean o mart
• output scritto fuori dalle cartelle annuali

Perché non automatico

Il multi-anno non ha una semantica unica:

• a volte basta UNION ALL
• a volte servono delta
• a volte serve un subset stabile di territori
• non tutti i dataset multi-year vogliono un output cross-year

Quindi il supporto deve essere dichiarativo, non implicito.

Caso di riferimento

IRPEF comunale 2019-2023 in dataciviclab/preanalysis

Stato attuale:

• pipeline annuale nel dataset.yml
• output multi-anno come step esplicito di progetto
• soluzione funzionante, ma non ancora nativa nel toolkit

Criteri di chiusura

• esiste un modo dichiarativo per definire output multi-anno
• il toolkit li esegue una sola volta
• il layer può leggere input annuali da clean o mart
• l’output viene scritto in un path non annuale coerente
• il caso IRPEF può migrare dal runner di progetto al supporto nativo

[Gabrymi93]

Primo punto di design da fissare: path di output e trigger di esecuzione.

1. Path di output

Per gli output multi-anno conviene usare un layer separato, non una cartella anno e non un sotto-caso implicito del mart annuale.

Proposta:

• _out/data/cross/<dataset>/<table>.parquet

Esempio:

• _out/data/cross/irpef_comunale_2019_2023/irpef_capacita_fiscale_multi_anno.parquet

Motivo:

• rende visibile che questo output non e legato a un singolo anno
• non si confonde con il loop annuale di raw/clean/mart
• mantiene il contract piu leggibile nei log e nei path

2. Trigger di esecuzione

Per la v1, meglio una esecuzione esplicita.

Proposta:

• toolkit run cross_year

Non lo integrerei subito in run all, perche il supporto deve restare opzionale e dichiarativo.

Questo permette di:

• evitare automatismi impliciti
• semplificare la prima implementazione
• usare il caso IRPEF come riferimento reale senza allargare troppo lo scope

Se il pattern regge su piu dataset, si potra valutare dopo una integrazione piu stretta con run all.