Formazione - percorso corso e archivio ricostruibile¶

Obiettivo¶

Rendere ogni corso ricostruibile nel tempo: stato operativo, passaggi fatti, evidenze raccolte, documenti prodotti e pacchetto finale archiviato.

La vista "percorso corso" non deve duplicare la gestione esistente. Deve leggere i dati gia presenti e, dove serve, aggiungere solo record di stato/audit per sapere cosa manca e chi ha chiuso il corso.

Principio dati¶

Il fulcro resta il corso (corso) con le sue relazioni:

data_corso: calendario, aula, slot mattina/pomeriggio, orari.
dipendente_corso: iscrizioni/corsisti collegati al corso.
dipendente: anagrafica discente.
cliente: azienda o aziende del corso.
docente: docente interno/esterno.
dipendente_corso_firma: firme tablet e orario firma.
documento / document_version: registro generato, registro firmato, attestati, allegati.
formazione_external_enrollment_map: origine WooCommerce e stato sync.
formazione_quote_*: preventivo, posti prenotati, partecipanti e conversione in iscrizioni.
storico_formativo_discente: libretto sicurezza e certificazioni pregresse/esterne.

Il percorso corso deve essere una vista derivata da questi dati, non una tabella parallela che replica corsisti, firme o documenti.

Stato percorso corso¶

Per ogni corso calcolare una timeline a step:

creato
corso esiste;
tipo corso definito;
aziendale/multiaziendale definito;
azienda obbligatoria se aziendale;
docente assegnato;
aula/date/orari presenti.
corsisti
almeno un iscritto in dipendente_corso;
ogni corsista ha nome, cognome, codice fiscale;
azienda collegata quando il corso e aziendale o quando serve sul registro multi-azienda.
registro
registro PDF generato;
firme raccolte su dipendente_corso_firma;
per ogni assenza firma deve esistere una motivazione o una gestione esplicita;
registro firmato caricato oppure evidenza esterna equivalente.
verifica
gradimento e domande finali completate se previste dal corso;
eventuali prove o questionari collegati al corso/discente.
attestati
attestato interno generato oppure attestato esterno caricato;
attestati associati ai discenti idonei;
scadenze salvate nel libretto sicurezza.
chiusura
controllo chiusura corso validato;
utente, data e note di chiusura registrati;
stato corso non piu operativo.
archivio
pacchetto ZIP o fascicolo corso generato;
indice documenti salvato;
checksum e timestamp disponibili;
pacchetto rintracciabile dal documentale.

Tabella consigliata: stato percorso¶

Se serve persistere lo stato calcolato, usare una tabella leggera:

formazione_corso_percorso_state

id
tenant_key
corso_id
step_code
state: missing, warning, ready, done, blocked
missing_count
summary
payload_json
computed_at
updated_by_id

Vincoli consigliati:

unique su tenant_key, corso_id, step_code;
FK verso corso.id;
nessuna copia di corsisti, firme o documenti;
payload_json solo per snapshot diagnostico leggero: ID documenti, contatori, motivazioni mancanti.

Tabella consigliata: eventi percorso¶

Per ricostruire chi ha fatto cosa:

formazione_corso_percorso_event

id
tenant_key
corso_id
event_type
step_code
actor_user_id
message
payload_json
created_at

Eventi minimi:

course_created
schedule_completed
participants_added
register_generated
tablet_signature_saved
signed_register_uploaded
course_validation_requested
course_validated
certificate_generated
external_certificate_uploaded
course_closed
archive_package_generated

Questa tabella serve per audit e ricostruzione storica. Non deve sostituire i log tecnici WooCommerce o documentale.

Tabella consigliata: pacchetto archivio¶

Per il corso chiuso:

formazione_corso_archive_package

id
tenant_key
corso_id
status: pending, generating, ready, failed, revoked
documento_id o document_version_id del pacchetto ZIP/PDF indice;
storage_key
checksum_sha256
file_size
manifest_json
generated_by_id
generated_at
error_message

manifest_json deve contenere solo riferimenti:

corso;
aziende;
date corso;
docenti;
iscrizioni;
registro generato;
registro firmato;
firme;
attestati;
gradimenti/questionari;
allegati esterni;
log principali.

Non salvare nel manifest dati duplicati se sono gia disponibili nelle tabelle sorgenti. Salvare label e checksum solo dove utile alla ricostruzione documentale.

Ricostruzione corso¶

La ricostruzione deve partire da corso_id e tenant_key.

Sequenza:

Caricare corso, tenant, clienti, docente, date/aula.
Caricare iscrizioni e discenti.
Caricare firme per ogni dipendente_corso e data_corso.
Caricare documenti collegati al corso: registro, registro firmato, attestati, allegati.
Caricare eventuale origine WooCommerce e preventivo.
Caricare libretto sicurezza per scadenze attestati.
Calcolare step percorso e anomalie.
Se esiste pacchetto archivio ready, mostrare manifest e file scaricabile.

Obbligatorieta per chiusura¶

Minimo per chiudere:

corso completo di tipo, aziendale/multiaziendale, docente, date, orari e aula;
almeno un corsista;
nome, cognome, codice fiscale per ogni corsista;
registro generato;
firme raccolte oppure assenze giustificate;
registro firmato o documento esterno equivalente;
attestato generato/caricato per ogni idoneo;
scadenza attestato se prevista;
controllo chiusura validato da utente autorizzato.

Comportamento UI¶

La pagina corsi dovrebbe mostrare:

percorso a step con colori verde, giallo, rosso;
frase sintetica: "mancano 3 firme e 2 attestati";
un solo pulsante "Prossima azione";
link alla scheda archivio quando il corso e chiuso;
pacchetto archivio generabile solo da corso chiuso.

Permessi¶

Usare gli stessi confini del modulo formazione:

filtro tenant_key obbligatorio;
modulo visibile solo se module_enabled_current_tenant("formazione");
WooCommerce visibile solo se abilitato per tenant;
nessun bypass via URL su corsi di altro tenant;
archivio corso leggibile solo da profili autorizzati alla formazione del tenant.

Test minimi prima di implementare¶

corso aziendale senza azienda: step creato non completo;
corso senza orari: step creato non completo;
corso senza corsisti: step corsisti rosso;
firme parziali: step registro giallo con conteggio;
attestati mancanti: step attestati giallo/rosso;
corso chiuso: pacchetto generabile;
corso non chiuso: pacchetto non generabile;
utente altro tenant: nessun accesso;
modulo formazione disattivato: menu e route operative non accessibili.

Nota implementativa¶

La prima implementazione puo essere solo calcolata in view/service, senza nuove tabelle. Le tre tabelle sopra servono quando vogliamo storicizzare lo stato, accelerare la dashboard e rendere l'archivio formalmente ricostruibile.