dnviti/zentral
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
34f954f494a921f41330aa19ef35295246f2f690
zentral/docs/development/devlog/2025-12-13-164500_mandatory_training_specs.md

6.9 KiB
Raw Blame History

Analisi Funzionale e Piano di Implementazione: Modulo Formazione Obbligatoria

1. Introduzione e Obiettivi

La presente analisi definisce le specifiche per l'estensione del sistema Zentral (progetto "OBIS" nel contesto cliente) con un modulo dedicato alla Gestione della Formazione Obbligatoria. L'obiettivo è integrare nativamente la gestione di aziende, lavoratori, corsi, scadenze e attestati, automatizzando il calcolo delle validità e il workflow di notifica ai referenti aziendali.

2. Requisiti Funzionali

2.1 Gestione Anagrafiche

Il sistema deve sfruttare le entità esistenti estendendone la logica di presentazione e filtraggio.

  • Aziende e Sedi: Mapping su Cliente.
    • Funzionalità: Attivazione/disattivazione (campo Attivo), storicizzazione (implicita nel non cancellare i dati), gestione sedi (già presente o gestibile tramite indirizzi multipli/destinazioni o clienti gerarchici. Decisione: Usare Cliente standard. Se necessario "Sede", si useranno i campi indirizzo o clienti collegati).
  • Lavoratori: Mapping su ClienteContatto.
    • Funzionalità: Ricerca trasversale (Global Search), filtri per Azienda, Ruolo, Stato Formativo.
    • Dati: Nome, Cognome, Ruolo (es. "Saldatore", "Impiegato"), Email, Telefono.

2.2 Catalogo Corsi

Il catalogo corsi è il "motore" delle regole di scadenza.

  • Mapping: Articolo con Categoria "Formazione".
  • Configurazione:
    • Tipologia: Definita tramite sottocategorie merceologiche (es. Sicurezza > Basso Rischio).
    • Validità: Campo GiorniValidita (già implementato) per calcolo automatico scadenza.
    • Logica Aggiornamento: Definizione se un corso è aggiornamento di un altro (facoltativo, logica avanzata).

2.3 Registro Formazione ed Eventi

Centralizzazione dello storico formativo.

  • Mapping: TrainingRecord.
  • Funzionalità:
    • Registrazione partecipazione lavoratore a corso.
    • Calcolo Stati:
      • Valido: Corso effettuato e non scaduto.
      • In Pre-scadenza: Meno di X giorni alla scadenza (configurabile, es. 30 o 60 gg).
      • Scaduto: Data odierna > Data Scadenza.
    • Attestati: Upload PDF/JPG, anteprima, download, archiviazione.

2.4 Scadenzario Interattivo (Dashboard)

Strumento principale per l'operatore.

  • Visualizzazione: Tabellare avanzata (Data Grid).
  • Colonne Chiave: Lavoratore, Azienda, Corso, Data Esecuzione, Data Scadenza, Stato, Azioni.
  • Filtri:
    • Per Azienda/Sede.
    • Per Tipologia Corso.
    • Range Date Scadenza.
    • Stato (Mostra solo Scaduti/In Scadenza).
  • Export: Funzione diretta "Esporta in Excel" della vista filtrata.

2.5 Sistema di Notifiche (Workflow Approvativo)

Il sistema non deve inviare email "a pioggia" ai lavoratori, ma notifiche controllate ai referenti.

  • Target: Referente Aziendale (identificato nel Cliente o un ClienteContatto specifico marcato come "Referente Formazione").
  • Tipologie:
    • Pre-scadenza: Avviso X giorni prima.
    • Scadenza: Avviso il giorno stesso o settimana stessa.
    • Post-scadenza: Sollecito.
  • Coda di Invio (Queue):
    • Le email non partono subito. Vengono generate in stato Pending in una tabella dedicata (TrainingNotificationQueue).
    • Interfaccia di Review: L'operatore vede le email pronte, può selezionarle, modificarle (opzionale) e approvarne l'invio.
  • Template:
    • Supporto per template standard (Oggetto e Corpo configurabili con placeholder {Azienda}, {Lavoratore}, {Corso}, {Scadenza}).

2.6 Import/Export Anagrafiche

  • Import Massivo: Upload file Excel per popolare/aggiornare ClienteContatto (Lavoratori) e storico TrainingRecord.
  • Export E-learning: Esportazione CSV/XLS su tracciati specifici (da definire, genericamente "Campi Anagrafici Base") per import su piattaforme esterne.

3. Piano di Implementazione Tecnico

Phase 1: Backend Extension & Data Model

  1. Entities:
    • Verificare TrainingRecord (già esistente).
    • Creare TrainingNotification (Queue):
      • Id, TrainingRecordId, RecipientEmail, Subject, Body, ScheduledDate, SentDate, Status (Pending, Approved, Sent, Error).
    • Creare ImportJob (opzionale, o gestione diretta API).
  2. API Controllers:
    • TrainingController:
      • Endpoint GetDeadlines: Query complessa con filtri, paginazione ordinamento.
      • Endpoint ExportDeadlines: Generazione Excel.
      • Endpoint ImportData: Parsing Excel e bulk insert.
      • Endpoint GenerateNotifications: Job (o trigger) per popolare la coda notifiche in base alle scadenze.
      • Endpoint SendNotifications: Invio massivo delle notifiche approvate.

Phase 2: Frontend Implementation (App training)

  1. Views (Pagine):
    • Scadenzario (TrainingDeadlinesPage):
      • Datagrid avanzata (libreria UI o custom table con filtri).
      • Bottone "Esporta Excel".
    • Code Notifiche (NotificationCenterPage):
      • Lista email in attesa.
      • Checkbox selezione multipla -> Azione "Approva e Invia".
      • Preview email side-by-side.
    • Registro Lavoratori (WorkersRegistryPage):
      • Vista incentrata sui ClienteContatto con focus formazione (colonne: Ultimi corsi, Stato generale).
    • Import/Export Utility (DataExchangePage):
      • Upload file Excel, mapping colonne (semplificato), log risultati import.

Phase 3: Integration & Logic

  1. Notification Logic:
    • Service che scansiona TrainingRecord ogni notte (o on-demand), calcola scadenze, controlla se notifica già generata, crea record in TrainingNotification.
    • Logica di raggruppamento: Se un'azienda ha 10 lavoratori in scadenza, inviare 1 email cumulativa al referente o 10 email separate? Specifiche attuali: "email... indirizzate ai referenti... non ai singoli lavoratori".
    • Decisione Progettuale: Email Raggruppata per Referente. Il sistema deve raggruppare le scadenze per Azienda e generare una sola notifica con la lista dei lavoratori in scadenza.

4. Nuove Rotte e Struttura File (Preview)

Backend

  • src/backend/Zentral.Domain/Entities/Training/TrainingNotification.cs
  • src/backend/Zentral.API/Modules/Training/Controllers/TrainingNotificationsController.cs
  • src/backend/Zentral.API/Modules/Training/Services/NotificationGeneratorService.cs
  • src/backend/Zentral.API/Modules/Training/Services/ExcelImportService.cs

Frontend

  • src/frontend/src/apps/training/pages/TrainingDeadlinesPage.tsx
  • src/frontend/src/apps/training/pages/NotificationCenterPage.tsx
  • src/frontend/src/apps/training/pages/WorkersRegistryPage.tsx
  • src/frontend/src/apps/training/pages/DataExchangePage.tsx

5. Note Operative

  • Utilizzare libreria EPPlus o ClosedXML lato server per Excel, o SheetJS lato client se l'export è puramente visivo (preferibile server-side per grandi moli di dati).
  • Per le Importazioni: Validazione rigorosa Codici Fiscali o Email univoche per evitare duplicati anagrafiche.