Rimpatrio del dominio nel verticale

Questa sezione è il registro operativo dell'attuazione di ADR-002: lo spostamento della logica di dominio da backbone-core/services/data-service al repository rendicontazione.

È scritta per essere letta senza contesto. Chi la apre — persona o assistente che riprende il lavoro dopo un'interruzione — deve poter capire cosa è stato fatto, cosa manca e con quale metodo, senza ricostruirlo dai commit.

Ultimo aggiornamento: 16 agosto 2026. Il rimpatrio è completo.

Dove siamo

routes/rendicontazione.js all'inizio	3.581 righe, 37 rotte
oggi	1.204 righe, 12 rotte
test data-service	113 pass, 0 fail
test verticale	157 pass, 0 fail, 0 todo

Nessuna delle dodici rotte rimaste contiene regole di dominio: contesto, identità, CRUD generico, lettura multipla, righe di previsione, stato operativo, lotti di import.

Onde

onda	modulo	righe	stato
1	projects — elenco, dettaglio, validazione, export	355	completata
2	workforce — dipendenti, presenze, ore giornaliere, associazioni, livelli	328	completata
3	forecasting — ricalcolo per progetto e globale	275	completata
4	data-exchange — workbook diff, apply, riconciliazione identità	897	completata
5	actuals — import presenze, rollback, motore di allocazione	1.797	completata

Con l'Onda 5 è sparita anche la directory modules/rendicontazione/ dentro data-service. Era l'anomalia da cui era partita l'analisi iniziale: Rendicontazione era l'unico verticale ad avere codice proprio dentro un servizio di piattaforma.

Il metodo

Sei passi, nell'ordine. È stato applicato cinque volte e ha trovato difetti ogni volta.

1. Caratterizzare la funzione dove si trova, prima di toccarla. Golden test con fixture in memoria: un [pinning] che registra l'output e degli [invariante] che dichiarano cosa deve restare vero.
2. Spostare il codice nel verticale, cambiando l'accesso ai dati — da letture separate a POST /rendicontazione/query — e non il calcolo.
3. Verificare l'equivalenza contro gli stessi snapshot, copiati senza modifiche. Se il file prodotto coincide, lo spostamento non ha cambiato niente.
4. Ricablare le rotte del verticale sui moduli locali.
5. Cancellare l'originale e gli helper rimasti orfani.
6. Perturbare il codice per verificare che i test siano vivi. È il passo che si tende a saltare, ed è quello che ha reso utile tutto il resto.

Perché il passo 6 conta

Ogni onda ha avuto almeno un test che sembrava coprire qualcosa e non lo copriva:

• Onda 1 — togliendo il filtro sui mesi consolidati i test restavano verdi: la fixture non aveva righe capaci di distinguerlo.
• Onda 2 — un ricalcolo dopo la consegna sostituiva il mese consolidato, e una previsione compariva accanto al dato reale. Entrambi invisibili perché la fixture non aveva i casi.
• Onda 3 — il tetto di budget non era vincolante su nessun progetto, e il ripiego «assegnazione senza fine → vale fino a fine progetto» non era esercitato da nessuna fixture.
• Onda 4 — la normalizzazione degli accenti nelle chiavi di import non era coperta (nessun nome accentato nella fixture), e l'ordine delle cancellazioni non era vincolante perché la fixture non aveva ore mensili preesistenti.
• Onda 5 — nessuna lacuna nelle fixture, ma l'equivalenza ha colto due omissioni nel codice spostato: il ripiego sui periodi di rapporto e il ramo che cancella i dipendenti creati dall'import.

Un test che passa sempre non è una rete, è una decorazione.

Sugli snapshot

Finché esistono due implementazioni, gli snapshot sono prova di equivalenza. Cancellata l'originale, diventano pinning: l'unico documento di cosa la funzione produceva prima. Per questo nel verticale non esiste GOLDEN_UPDATE — aggiornarli richiede di riscriverli a mano e di dire nel commit perché.

Cosa resta

Il rimpatrio è finito. Restano tre cose, nessuna delle quali è un'onda.

I difetti noti. I due che erano attivi sono stati corretti a rimpatrio finito, quando la ragione per lasciarli — non confondere trasloco e correzione — era scaduta. Gli altri quattro restano, con il momento in cui ognuno diventa reale: tre si chiudono con la riscrittura del forecasting, uno con il collegamento dipendente-account.

L'adattatore table. Il motore di allocazione accede ai dati con la forma table(nome) invece che con il client, tramite creaAdattatoreTabella. Non è un debito da saldare in fretta — funziona ed è coperto — ma è l'unico punto del verticale dove leggiInsieme non è esprimibile, quindi ogni lettura del motore è un giro di rete a sé. Si chiude con la riscrittura del forecasting.

resetRendicontazioneData è rimasta in data-service. Cancella dati di tutte le tabelle del verticale, e vi resta perché è un'operazione di piattaforma — non perché era comoda lasciarla lì. Vale la pena riguardarla quando si toccherà l'amministrazione.

Pagine di questa sezione

• Contratti di data-service — gli endpoint che rendono possibile il rimpatrio, e perché ognuno esiste
• Difetti noti — trovati durante il rimpatrio e non corretti, con il motivo
• Come si lavora — eseguire i test senza il registry privato, verificare che siano vivi, ricostruire dopo uno spostamento, e cosa resta in sospeso