La chiusura mensile

Come si passa dalle misure di un mese alle bozze di fattura, per un parco di qualunque dimensione.

I cinque passi

1  GET  /v1/metering/stato?mese=2026-09          le misure sono complete?
2  POST /v1/fatturazione/calcola                 una chiamata per fetta → scrive CSV su S3
3  POST /v1/fatturazione/chiusura                 avvia il travaso
4  GET  /v1/fatturazione/chiusura?mese=2026-09   finché non è «conclusa»
5  POST /v1/fatture/{id}/emetti                  da bozza a fattura, con numero

Il passo 2 si ripete una volta per fetta, e le fette possono andare tutte insieme. Il passo 3 si chiama una volta sola, quando tutte le fette hanno finito.

Passo 2 · il calcolo, a fette

POST /v1/fatturazione/calcola
{ "mese": "2026-09", "destinazione": "s3", "salto": 0, "limite": 2000 }

salto e limite definiscono la fetta. Per 200.000 punti: cento chiamate con salto 0, 2000, 4000… Ognuna scrive un file su S3 e risponde con un riepilogo, non col dettaglio.

Perché su S3 e non direttamente nelle tabelle. Misurato su questo impianto:

via	righe al secondo	4,4 milioni di righe
scrittura diretta, 1 processo	399	3 ore
scrittura diretta, 20 insieme	2.598	28 minuti
scrittura diretta, 40 insieme	si rompe	—
passando da S3	319.647	14 secondi

S3 non ha contesa: le fette scrivono tutte insieme senza ostacolarsi. È la ragione per cui questa forma esiste.

Senza destinazione la stessa chiamata resta un'anteprima: restituisce il dettaglio e non scrive niente. Il tetto è 500 punti, ed è la dimensione della risposta — ogni punto produce una ventina di righe. In modalità S3 il tetto sale a 5.000, perché la risposta è un riepilogo.

Passo 3 · il travaso

POST /v1/fatturazione/chiusura
{ "mese": "2026-09", "conferma": true }

conferma: true è obbligatorio: una chiusura mensile non si avvia per distrazione.

La chiamata avvia e non attende — risponde in un paio di secondi, il lavoro continua altrove.

Dentro, in una sola transazione:

1. una tabella di appoggio non journalizzata
2. la COPY dei CSV da S3
3. un indice sulla tabella di appoggio
4. gli aggregati per contratto, a scaglioni
5. le bozze precedenti dello stesso periodo, rimosse
6. le testate, una per contratto
7. le righe, a scaglioni, agganciate alle testate

Perché a scaglioni

Ogni singola istruzione ha un tetto di 45 secondi. Basta una che lo sfondi per far cadere tutta la chiusura. Misurato su 4,4 milioni di righe:

istruzione	durata
COPY da S3	23,1 s	dentro
indice	5,6 s	dentro
aggregati in un colpo solo	49,5 s	fuori
gli stessi aggregati a scaglioni	~2 s ciascuno	dentro
righe a scaglioni	<1 s	dentro

Il collo non era la COPY né le righe: era l'aggregazione.

Come si tagliano gli scaglioni

Sul conteggio delle righe, non sull'intervallo degli identificativi. La differenza non è teorica: gli id dei contratti non sono distribuiti uniformemente, e tagliando lo span in parti uguali una fetta si prende quasi tutto.

intervalli di id uguali        conteggio di righe
  fetta 1: 3.960.000  ← 8,1×     tutte: 488.8xx  ← 1,0×
  fette 2-9: ~60.000

I confini si prendono con una scansione di solo indice: otto confini costano quattro secondi.

Passo 4 · controllare

GET /v1/fatturazione/chiusura?mese=2026-09

Gli stati sono avviata, conclusa, fallita. Su una conclusa, esito dice quanti file sono stati caricati, quante bozze precedenti rimosse, quante fatture e righe create. Su una fallita, il motivo.

Rieseguirla è sicuro

Una chiusura ripetuta sullo stesso mese rifà le bozze invece di raddoppiarle. E le fatture già emesse non vengono toccate: hanno un numero, e un numero non si ritira cancellando una riga — per quello esiste la nota di credito.

Un fallimento a metà non lascia niente di mezzo: il travaso è una sola transazione.

Una fattura per contratto

Le righe si calcolano per punto, la fattura è per contratto. Il raggruppamento avviene nel travaso e non nel calcolo, perché i punti di uno stesso contratto possono cadere in fette diverse: raggrupparli prima produrrebbe due fatture per lo stesso contratto.

L'IVA si calcola sul totale del contratto, non sommando quelle dei punti.

Quanto dura

Misurato su 4,4 milioni di righe: 230 secondi, con 97 MB di memoria usati su 1024.

Proiezione per 200.000 punti — i pezzi sono misurati, la somma è una proiezione:

fase	tempo
calcolo e scrittura, 100 fette a 20 per volta	~50 s
travaso	230 s
200.000 testate invece di 278	+17 s
totale	~5 minuti