Dominio `fin` — Panoramica sviluppatore

🎯 Cosa fa

Il dominio fin (funded projects) gestisce i progetti formativi finanziati da FondItalia: ciclo di vita del progetto, fasi, moduli, edizioni, aziende partecipanti, rendicontazione.

Dominio grande: ~29 tabelle. Questa pagina copre il core F2 (7 tabelle): progetti, fasi, moduli, edizioni, aziende, adesioni. Le aree restanti (spese, staff, documenti, integrazioni, anagrafiche di supporto) saranno documentate in spec successive.

Le iscrizioni dei lavoratori alle edizioni FondItalia vivono in edu.workerTrainingDetails (con trainingSessionId = fin.editions.id via shared PK). Le presenze sono tracciate dalle colonne attendanceHours, attendanceRate e passed della stessa tabella. La tabella fin.enrollments è stata rimossa.

🗺️ Mappa moduli

Database — `TrainingHub.Database/fin/`

Core in questa documentazione (7):

Area	Tabella	Ruolo
Progetti	`fin.projects`	Progetto formativo finanziato
Progetti	`fin.phases`	Anagrafica fasi (ordinate, con managedType)
Progetti	`fin.projectPhases`	Istanza fase per progetto (stato + completionRate)
Struttura	`fin.modules`	Moduli formativi del progetto
Struttura	`fin.editions`	Edizioni del modulo (replicazioni)
Partecipazione	`fin.projectCompanies`	N:N progetto ↔ azienda + regime aiuto
Partecipazione	`fin.companyMemberships`	Adesione azienda al fondo

Estensioni coperte lato utente (dettaglio dev pianificato come lavoro futuro):

Area	Tabelle	Pagina utente
Documenti & compliance	`companyDocuments`, `projectDocuments`, `staffDocuments`, `documentTypes`	Documenti di progetto
Fondi & bandi	`accounts`, `budgets`, `cofinancing`, `contributions`, `notices`	Fondi, bandi e budget
Spese	`expenses`, `expenseCategories`, `expenseDocuments`	Spese e rendicontazione
Staff & sessioni	`staff` (FK nullable `userId → kset.users` per riuso identità / email / ruoli), `projectStaff`, `sessions`, `attendanceRegisters`, `phaseRequirements`, `projectHistory`	Staff e sessioni
Anagrafiche & integrazioni	`teachingMethods`, `thematicAreas`, `integrationRequests`	Anagrafiche e integrazioni

Schema DB dettagliato di queste estensioni non incluso in Schema DB (focus sulle 8 core).

Documentazione pregressa

Ricco materiale disponibile in:

docs/fonditalia-client-overview.md — panoramica cliente-friendly delle fasi (call 03/04/2026).
docs/fonditalia-technical-overview.md — overview tecnica.
docs/fonditalia_context_for_claude_code.md — contesto storico.
docs/superpowers/specs/2026-04-02-fonditalia-integration-design.md e 2026-04-03-fonditalia-v2-design.md — spec iniziali.

UI CRUD — `TrainingHub.BackOffice/Components/CRUD/fin/`

~29 entità CRUD auto-generate. Pattern identico a inv/reg/edu/job (vedi componenti UI inv).

Le 7 entità core:

Project, Phase, ProjectPhase
Module, Edition
ProjectCompany, CompanyMembership

🔧 Enum e stati

Dal file TrainingHub.Shared/Enums.cs:

public enum AccountType { rete, monoaziendale }
public enum PhaseManagedType { active, tracking, tracking_readonly }
public enum PhaseRequirementType { document, data_field, action }
public enum ProjectStatus { BOZZA, IN_CONFIGURAZIONE, ANALISI_FABBISOGNI,
    IN_COMPOSIZIONE, PRESENTATO, IN_CONDIVISIONE, CONDIVISIONE_OK,
    CONDIVISIONE_NEGATA, INVIO_ALLEGATI_AZIENDE, IN_APPROVAZIONE,
    APPROVATO, APPROVATO_CON_MODIFICHE, RIGETTATO, IN_PREPARAZIONE,
    IN_EROGAZIONE, EROGAZIONE_COMPLETATA, IN_RENDICONTAZIONE,
    RENDICONTAZIONE_INVIATA, CHIUSO, IN_INTEGRAZIONI, SALDO,
    REVOCATO, RINUNCIATO }
public enum AidRegime { de_minimis, aiuti_formazione }
public enum ProjectPhaseStatus { not_started, in_progress, completed, skipped }
public enum MembershipStatus { active, ceased }
public enum DocumentStatus { da_richiedere, richiesto, ricevuto, approvato, scaduto }
public enum DocumentSubject { azienda, progetto, docente, modulo, sessione, corsista, spesa }
public enum AllocationMode { total, pro_quota }
public enum ExpenseDocumentRole { costo, pagamento }

🧩 Pattern chiave

Ciclo a fasi

Il progetto segue una sequenza di fasi regolamentate. Ogni fase ha:

Un managedType: active (gestita nel sistema), tracking (solo stato), tracking_readonly (esterna, no dati).
Requisiti (phaseRequirements fuori scope): documenti, campi dati, azioni richieste per chiudere la fase.
Un flag hideable che permette di saltarla.

Lo stato del progetto (projects.status) è sincronizzato con la fase attiva, ma con più granularità (23 stati vs ~12 fasi). La logica di sincronizzazione non è documentata — candidata a una pagina Logica applicativa in spec successiva.

Multi-progetto per azienda

Un'azienda può partecipare a più progetti contemporaneamente via projectCompanies. La disponibilità sul conto (companyMemberships.availableBalance) è condivisa: il sistema dovrebbe scalarla con l'avvio di nuovi progetti, ma la logica non è chiara.

Integrazione esterna FemiWeb

Presentazione, rendicontazione e comunicazioni con FondItalia passano da FemiWeb (piattaforma esterna). Il sistema esporta/importa dati con FemiWeb — la tabella integrationRequests (fuori scope) traccia queste comunicazioni.

📦 Dipendenze

Brighela.SimpleCRUD — CRUD base
UI stack standard (DevExpress, Tabiot)
Cross-dominio:
- fin.projectCompanies.companyId → reg.companies(id)
- fin.companyMemberships.companyId → reg.companies(id)
- edu.workerTrainingDetails.trainingSessionId → fin.editions(id) (iscrizioni lavoratori)

📁 File chiave

Database/fin/Tables/*.sql (~29)
BackOffice/Components/CRUD/fin/*.razor (~29)
Shared/Enums.cs — enum progetto, fase, regime, stato
docs/fonditalia-*.md — documentazione storica

⚠️ Domande aperte / debito tecnico

Sincronizzazione projects.status ↔ projectPhases.status. Logica non documentata. Chi aggiorna chi?
Transizioni stato progetto. Macchina a stati formale vs transizioni ad hoc nel code-behind? Verificare.
Validazione saldo disponibile. Un progetto che supera la disponibilità dell'azienda non è bloccato automaticamente.
fin.editions vs edu.trainingSessions. Risolto: le edizioni FondItalia condividono la PK con edu.trainingSessions via pattern di ereditarietà; le iscrizioni lavoratori vivono in edu.workerTrainingDetails.
Integrazione FemiWeb. Gestita via integrationRequests ma non esiste documentazione di protocollo/payload.
phaseRequirements (fuori scope). Logica di validazione "fase completabile solo se requisiti OK": dov'è?

🔁 Workflow di promozione edu → fin

Un corso/sessione/appuntamento di edu può essere "promosso" alla controparte FondItalia in fin (shared PK):

Origine `edu`	Target `fin`	Tab UI	Servizio
`courses`	`modules`	"Progetto FondItalia" sulla pagina Course	`IFundedTrainingService.PromoteCourseToModuleAsync`
`trainingSessions`	`editions`	"Edizione FondItalia" sulla pagina TrainingSession	`PromoteSessionToEditionAsync`
`appointments`	`sessions`	"Sessione FondItalia" sulla pagina Appointment	`PromoteAppointmentToFinSessionAsync`
(n/a — workflow inverso)	aggancio bulk	"Aggancia corso esistente" sulla pagina Project	usa `PromoteCourseToModuleAsync` per ogni course selezionato

Stati progetto ammessi alla promozione (hard-coded in FundedTrainingService.PromotableStatuses): BOZZA, IN_CONFIGURAZIONE, ANALISI_FABBISOGNI, IN_COMPOSIZIONE, IN_PREPARAZIONE. Gli stati post-presentazione (PRESENTATO in avanti) richiederebbero una richiesta formale di modifica al fondo, quindi sono esclusi.

Vincoli a catena: per promuovere un appointment a fin.sessions la session parent deve essere già promossa a fin.editions. Analogamente, per promuovere una session a fin.editions almeno uno dei suoi corsi deve essere già promosso a fin.modules. I tab UI mostrano un messaggio informativo se il prerequisito manca, invece di abilitare il bottone.

Iscrizione worker in regime finanziato: EnrollWorkerInEditionAsync(workerId, editionId) valida che la company del worker sia fra le projectCompanies del progetto a cui appartiene l'edition; se sì, crea/aggiorna edu.workersTrainings + edu.workerTrainingDetails (la fundedness si deriva via shared PK, niente flag denormalizzato).

Authorization: i tab riusano policy esistenti — page-fin-modules_R per visualizzare il tab Course→Module, page-fin-modules_C per la promozione effettiva (e analoghi per editions/sessions). Niente policy custom.

🔗 Vedi anche

Schema DB
Aggiungere un campo
Guida utente: Panoramica formazione finanziata (docs-site-user)
Dominio reg: panoramica (aziende partecipanti)
Dominio job: panoramica (lavoratori iscritti)
Dominio edu: panoramica (formazione ordinaria — relazione da chiarire)

🎯 Cosa fa​

🗺️ Mappa moduli​

Database — TrainingHub.Database/fin/​

Documentazione pregressa​

UI CRUD — TrainingHub.BackOffice/Components/CRUD/fin/​

🔧 Enum e stati​

🧩 Pattern chiave​

Ciclo a fasi​

Multi-progetto per azienda​

Integrazione esterna FemiWeb​

📦 Dipendenze​

📁 File chiave​

⚠️ Domande aperte / debito tecnico​

🔁 Workflow di promozione edu → fin​

🔗 Vedi anche​