feat: implement training notification management and new training pages
This commit is contained in:
@@ -0,0 +1,122 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Implementazione Modulo Formazione Obbligatoria (Mandatory Training)
|
||||
|
||||
## Stato: Completato
|
||||
|
||||
Ho completato l'implementazione del modulo Formazione Obbligatoria seguendo le specifiche definite in `2025-12-13-164500_mandatory_training_specs.md`.
|
||||
|
||||
## Modifiche Apportate
|
||||
|
||||
### Backend
|
||||
1. **Entities**:
|
||||
- Creata `TrainingNotification` in `Zentral.Domain` per gestire la coda di notifiche.
|
||||
- Aggiornato `ZentralDbContext` (DbSet).
|
||||
- Creata migrazione `AddTrainingNotifications`.
|
||||
2. **Services**:
|
||||
- Creato `TrainingNotificationService`:
|
||||
- Logica `GenerateNotificationsAsync`: raggruppa scadenze per Cliente, crea notifiche `Pending`.
|
||||
- Logica `SendApprovedNotificationsAsync`: invia email per notifiche `Approved`.
|
||||
- Generazione corpo email HTML con tabella riepilogativa.
|
||||
- Registrato servizio in `Program.cs`.
|
||||
3. **Controllers**:
|
||||
- Creato `TrainingNotificationsController`:
|
||||
- Endpoints per Listing, Generazione, Approvazione, Modifica e Invio.
|
||||
- Aggiornato `AppService` (verifica esistenza modulo, usato nei service).
|
||||
|
||||
### Frontend
|
||||
1. **Pagine Nuove (App Training)**:
|
||||
- `TrainingDeadlinesPage`: Scadenzario tabellare con indicatori di stato.
|
||||
- `NotificationCenterPage`: Gestione coda notifiche (Approvazione/Modifica/Invio).
|
||||
- `WorkersRegistryPage`: Registro lavoratori con stato formativo aggregato.
|
||||
- `DataExchangePage`: Placeholder per Import/Export.
|
||||
2. **Navigazione**:
|
||||
- Aggiornato `Sidebar.tsx` con le nuove voci di menu sotto "Formazione" ("Lavoratori", "Scadenze", "Notifiche", "Import/Export").
|
||||
- Aggiornato `routes.tsx` con le relative rotte.
|
||||
|
||||
## Note per il Testing
|
||||
- Per testare le notifiche:
|
||||
1. Andare in "Notifiche".
|
||||
2. Cliccare "Genera".
|
||||
3. Verificare la creazione di notifiche per le aziende con scadenze.
|
||||
4. Approvare una notifica.
|
||||
5. Cliccare "Invia Approvate".
|
||||
- Assicurarsi che il modulo "Comunicazioni" sia attivo e configurato (SMTP).
|
||||
Reference in New Issue
Block a user