# 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.