Download the PHP package ilbronza/courses without Composer

IlBronza Courses

Pacchetto Laravel per gestire corsi, sessioni, presenze e responsabilità formative degli operatori.

Questa guida è rivolta a chi deve mantenere o estendere il calcolo della validità delle responsabilità. È la parte che, partendo dai corsi completati di un operatore, aggiorna per ogni responsabilità:

• valid: se la responsabilità è valida;
• valid_to: fino a quando è valida;
• parsed_at: quando è stata ricalcolata;
• errors: il motivo dell’eventuale non validità.

I nomi delle classi storiche contengono il refuso Validith. È intenzionale: non rinominarli senza un refactoring completo dei riferimenti.

Cosa copre il package

Il package non è solo il motore di validità. Fornisce il dominio e le migrazioni per queste aree:

Le migrazioni del package creano le tabelle con prefisso courses__. Le regole di business sulla validità, invece, sono specifiche del progetto Ecostudio e vivono nell’applicazione ospitante.

Dove vive il codice

Il package contiene l’infrastruttura generica; l’applicazione ospitante (Ecostudio) contiene le regole aziendali e la mappa delle responsabilità.

Modello mentale

Una OperatorResponsibility non è il completamento di un singolo corso: è lo stato aggregato di una tipologia, per esempio FL, PS o ANT.

Dati usati dagli helper

Nell’integrazione Ecostudio, OperatorResponsibilityValidityHelperBase recupera i record CourseWorker tramite l’ID del worker legacy dell’operatore:

Ogni helper dichiara gli alias dei corsi che gli interessano in static::$includedResponsibilities; il base helper filtra i CourseWorker su quell’elenco. I campi importanti sono:

Risultato di una validazione

Tutti gli helper concreti terminano in uno dei due metodi del motore generico:

setValidWithDate() salva valid = true, valid_to = $date, parsed_at = now() e pulisce gli errori.

setNotValid() salva valid = false, azzera valid_to, imposta parsed_at = now() e concatena l’array $problems nel campo errors usando | come separatore.

Come eseguire i calcoli

Una responsabilità singola

Ogni helper estende OperatorResponsibilityValidityHelperGeneral, quindi può essere invocato direttamente con il record da calcolare:

Tutte le responsabilità di un operatore

Questo è il punto di ingresso da usare quando cambiano i corsi di un lavoratore e si vuole ricalcolare il suo solo operatore:

L’helper percorre $operator->operatorResponsibilities, trova la classe configurata per ogni responsibility_id e chiama ::parse() su quella classe. Una responsabilità senza helper configurato viene ignorata: non viene modificata né genera un errore.

Tutte le responsabilità di una tipologia

Ogni helper concreto dichiara static string $responsibility, per esempio FL. Il metodo ereditato può ricalcolare tutti gli operatori che hanno quella tipologia:

Il flusso è:

1. prende static::$responsibility dalla classe chiamante;
2. recupera la classe configurata in courses.models.responsibility.helpers.validity;
3. cerca OperatorResponsibility::byResponsibility('FL');
4. richiama ::parse() per ogni record trovato.

Lo scope usato è:

Elaborazione batch delle sole responsabilità da calcolare

Il package espone anche:

Questo metodo elabora solo le responsabilità con parsed_at nullo (toParse()), ordinandole prima per quelle mai elaborate e poi per data di parsing. A differenza dell’orchestratore per operatore, si aspetta che ogni responsabilità trovata abbia un helper configurato: una chiave mancante porta a un errore PHP al momento della chiamata statica.

Regole attualmente implementate

Le classi effettivamente mappate sono definite nel config/courses.php dell’applicazione ospitante. Lo stato sotto descrive il comportamento del codice attuale, non una prescrizione normativa.

FL — formazione lavoratori

La regola FL è volutamente esplicita e usa solo le date di completion, mai expiration_date.

Prerequisiti indispensabili

Per poter essere valida, la responsabilità FL richiede entrambi:

1. almeno un FL_G completato;
2. almeno un FL_S oppure FL_S_EL completato.

Se anche uno solo dei prerequisiti manca, viene salvato valid = false con uno di questi errori:

• FL_G mancante o non completato;
• FL_S o FL_S_EL mancante o non completato.

Calcolo della data

Quando i prerequisiti ci sono, l’helper trova la data di completamento più recente tra:

• il più recente fra FL_S e FL_S_EL;
• PREP_A;
• FL_A.

Poi calcola:

Se valid_to è nel futuro, FL è valida; altrimenti viene salvata come non valida con errore FL scaduto.

Esempio:

La data più recente è PREP_A (2024-01-20), quindi la validità FL termina il 2029-01-20.

PRI

L’helper considera PRI e PRIECO. Se trova almeno un corso con completion, imposta una data fissa di validità al 2040-03-22; non calcola una durata a partire dal completamento. Se non trova completamenti, salva la responsabilità come non valida.

Questa è una regola transitoria codificata nell’helper, da rivalutare prima di renderla una regola definitiva.

Famiglia base + aggiornamento

ANT, ANT2, ANT3, PREP, PS e DL estendono OperatorResponsibilityValidityHelperBasePlusAgg e usano la stessa struttura.

Ogni classe dichiara:

La configurazione corrente è:

Il comportamento del base/agg attuale è:

1. per il corso base, cerca il record con la maggiore expiration_date che abbia completion, completion_ps_t1 e completion_ps_t2;
2. se le tre date non ci sono ma flag_boh è attivo, usa expiration_date, oppure calcola la scadenza dal completamento tramite addValidityToDate();
3. per l’aggiornamento, usa la maggiore expiration_date disponibile;
4. con base e aggiornamento presenti, la data finale è la maggiore tra le due;
5. con il solo base, la responsabilità è valida solo se la sua data è futura; il codice registra inoltre l’aggiornamento come mancante;
6. senza una data base valida, la responsabilità non è valida.

Avvertenza sul base/agg

Il controllo delle colonne completion_ps_t1 e completion_ps_t2 è nel base helper comune, quindi oggi viene applicato anche a ANT, ANT2, ANT3, PREP e DL, non soltanto a PS. Questa è l’implementazione presente: prima di modificarla, decidere esplicitamente se è una regola voluta o un residuo della logica PS.

Aggiungere una nuova responsabilità

1. Creare un helper in app/Helpers/Courses/Validity/ dell’applicazione ospitante.
2. Estendere OperatorResponsibilityValidityHelperBase oppure OperatorResponsibilityValidityHelperBasePlusAgg se la regola è realmente quella base + aggiornamento.
3. Impostare la chiave, gli alias dei corsi letti e la logica di handle().
4. Registrare la chiave in config/courses.php dell’applicazione ospitante sotto models.responsibility.helpers.validity.
5. Preparare casi con corso assente, corso incompleto, corso scaduto e corso valido.

Esempio minimale:

Checklist di manutenzione

Prima di considerare completata una modifica alle validità:

• verificare che responsibility_id coincida con la chiave in config/courses.php;
• verificare che gli alias in $includedResponsibilities coincidano con quelli realmente salvati nei CourseWorker;
• definire se la data di partenza è completion oppure expiration_date;
• verificare i prerequisiti obbligatori separatamente dalle date che prolungano la validità;
• verificare sia una scadenza futura sia una scaduta;
• verificare il contenuto di errors per un caso non valido;
• eseguire almeno il controllo sintattico:

Limiti noti

• OperatorResponsibilityValidityHelperGeneral::getCourseSessions() nel package contiene un dd() intenzionale: gli helper dell’app devono passare da OperatorResponsibilityValidityHelperBase, che lo sostituisce con il recupero corretto dei CourseWorker legacy.
• Gli helper placeholder elencati nella tabella non producono alcun esito; lasciarli mappati può far sembrare che una responsabilità sia stata elaborata quando non è successo nulla.
• Il package non contiene ancora una suite automatizzata di test per queste regole. Ogni nuova logica va prima verificata con una matrice di casi reali o fixture dedicate.