Architettura e confini applicativi

Decisione consigliata

Nel passaggio al MVP avanzato mantenere un solo deployment rendicontazione-service, trasformandolo in un monolite modulare per sottodomini. Separare ora quattro o più microservizi aumenterebbe deployment, contratti distribuiti, consistenza e osservabilità prima che volumi e team boundary siano noti.

La suddivisione per dominio è preferibile a quella puramente tecnica/per funzionalità perché tiene insieme regole, dati e casi d'uso che cambiano per la stessa ragione.

Moduli target

Modulo	Responsabilità	Non possiede
workforce	Dipendenti/risorse, società, sedi e storico assegnazione, ruoli, livelli, reporting line, costi, ferie, self-service	Autenticazione di piattaforma
projects	Progetti, sede opzionale, finanziatori, tariffe standard, associazioni, compatibilità città e limiti ore	Algoritmo di forecast
actuals	Presenze, ore effettive, riconciliazione identità, cursore consuntivo, consegna periodi	Formati specifici dei file
forecasting	Capacità, domanda, vincoli, scenari, run e spiegazioni	CRUD anagrafiche
data-exchange	Contratti canonici, registry adapter, staging, diff, import/export	Regole HR/progetto duplicate
reporting	Report utente/progetto, snapshot consegnati, export documentale	Modifica dei consuntivi
shared-kernel	Organization context, money/time primitives, audit envelope, domain events	Business logic dei moduli

Ogni modulo espone application service/contract interni. È vietato accedere direttamente alle tabelle di un altro modulo dal layer HTTP; le dipendenze devono essere esplicite e testabili.

Infrastruttura di piattaforma

• La UI continua a usare data-service per dati applicativi e autorizzazione frontend-facing.
• auth-service/identità resta proprietario di utenti, organizzazioni, membership e permessi.
• datahub resta il layer interno di persistenza, non raggiungibile dal browser.
• File persistenti e report passano da docs-service; job pianificati da scheduler; notifiche asincrone dal bus/bridge condiviso.
• I ricalcoli lunghi diventano job asincroni idempotenti con progress e retry; non timer locali al processo.

Eventi di dominio

Eventi minimi, sempre con eventId, organizationId, occurredAt, actor, correlationId, versione schema e aggregate/version:

• EmployeeCreated, EmployeeEmploymentChanged, EmployeeCostChanged, EmployeeSiteChanged;
• SiteCreated, SiteUpdated, ProjectSiteChanged;
• LeavePlanChanged, LeaveBalanceChanged;
• ProjectCreated, ProjectDatesChanged, ProjectCapacityLimitChanged;
• ProjectAssignmentChanged, FundingRateChanged;
• ActualHoursChanged, ActualCursorMoved, PeriodDelivered;
• ForecastRecalculationRequested, ForecastCompleted, ForecastInfeasible.

Gli eventi che invalidano il forecast confluiscono in una coda/outbox e vengono coalesciti per organizzazione e intervallo temporale, evitando ricalcoli duplicati durante import massivi.

Quando estrarre un microservizio

Valutare l'estrazione solo se almeno uno di questi segnali è misurato:

• forecasting richiede scaling/worker/runtime indipendente;
• data exchange ha connettori, SLA e release cadence propri;
• un team possiede stabilmente un bounded context;
• isolamento di failure o sicurezza non è ottenibile nel deployment corrente;
• il volume rende inefficiente il database/processo condiviso.

Il primo candidato naturale è forecasting-worker; il secondo data-exchange. Workforce, projects e actuals richiedono transazioni fortemente correlate e non vanno separati prematuramente.

ADR da produrre

1. ADR-001: tenant source of truth e strategia di propagazione.
2. ADR-002: monolite modulare e regole tra moduli.
3. ADR-003: modello temporale e policy intervalli non sovrapposti.
4. ADR-004: doppio cursore, consegna e correzione retroattiva.
5. ADR-005: strategie dipendente vs freelancer.
6. ADR-006: algoritmo forecast, funzione obiettivo e gestione infeasibilità.
7. ADR-007: adapter import/export e versioning.