Fase 3 - Pilota catalogo modulo Formazione

Data audit: 2026-06-30

Documenti collegati:

• docs/processo/inventario_fase1_catalogo_moduli_tenant.md
• docs/processo/fase1b_catalogo_moduli_business.md
• docs/processo/fase2_specifica_tecnica_catalogo_moduli.md

Decisione

Il modulo Formazione e' un buon candidato come primo pilota del catalogo moduli, ma non deve essere migrato in modalita big-bang.

La prima iterazione consigliata e':

1. catalogare safe_formazione;
2. collegarlo al legacy module code formazione;
3. definire menu dichiarativo in shadow mode;
4. collegare feature flag e profilo dedicato;
5. mantenere TenantModuleEntitlement come enforcement runtime;
6. non spostare subito WooCommerce, portale esterno e job su nuovo enforcement.

Perche Formazione e' adatto

Criterio	Esito	Nota
Modulo runtime gia esistente	OK	module_code = formazione
Gate menu esistente	OK	menu_formazione_enabled_current_tenant()
Gate route esistente	Parziale	_formazione_access_allowed() usa is_module_enabled("formazione")
Feature dedicate	OK	feature.formazione.external_portal, feature.formazione.sso_v1, feature.formazione.certificate_sync_v2
Profilo dedicato	OK	operatore_formazione con module_code = formazione
Tenant pilota gia individuabili	OK	tenant_besant, tenant_retra, tenant_fornautic
Dipendenze RAS/commerciale	Basse/medie	WooCommerce quote puo toccare commerciale, ma core formazione e' autonomo
Menu confinabile	OK	Root Formazione, sottosezioni Pianificazione, Didattica, Monitoraggio
Rischio business	Medio	Molte viste, sync esterno e attestati

Perimetro del modulo

Codici

Tipo	Codice
Codice catalogo	safe_formazione
Codice legacy runtime	formazione
Tipo modulo	sellable
Owner	Formazione
Dipendenza obbligatoria	core_anagrafiche
Dipendenze opzionali	WooCommerce, portale esterno, SSO, sync attestati

Feature

Feature code	Tipo	Stato consigliato iniziale
feature.formazione.external_portal	Add-on / portale esterno	disabilitata di default
feature.formazione.sso_v1	Add-on / SSO	disabilitata di default
feature.formazione.certificate_sync_v2	Add-on / sync attestati	disabilitata di default
feature.formazione.woocommerce_sync	Da introdurre come mapping logico	derivata da policy tenant esistente
feature.formazione.language_check	Da introdurre come mapping logico	derivata da policy tenant esistente

Nota: le ultime due oggi non risultano come TenantFeatureFlag standard. Sono gestite in tenant_policy.py con mappe tenant hardcoded.

Profili

Profilo	Uso
operatore_formazione	Operatore dedicato modulo formazione
admin_tenant	Gestione tenant completa
operatore_admin	Operatore amministrativo con accesso esteso
readonly	Consultazione

Tenant gia allineati

Da tenant_policy.py:

Tenant	WooCommerce	Language check
tenant_besant	si	no
tenant_retra	no	si
tenant_fornautic	no	no

Da config.py, questi tenant hanno formazione abilitato nei default override:

• tenant_besant
• tenant_retra
• tenant_fornautic

Menu target

Il menu attuale e' registrato in app/__init__.py. Nel pilota non va rimosso: va riprodotto in module_menu_item e confrontato in shadow mode.

Menu key proposta	Label	Parent	Route/href attuale	Feature richiesta	Note
formazione.root	Formazione	root	categoria	nessuna	Root logico
formazione.dashboard	Cruscotto Formazione	Pianificazione	FormazioneDashboardView	nessuna	View FAB
formazione.guida	Guida Formazione	Pianificazione	/formazione-dashboard/guida	nessuna	Link
formazione.calendar	Calendario Formazione	Pianificazione	FormazioneCalendarView	nessuna	View
formazione.portal	Portale Discenti	Pianificazione	/training-portal/launch	feature.formazione.external_portal	Oggi menu cond usa solo modulo, non feature
formazione.date	Date e Orari	Pianificazione	DataCorsoView	nessuna	View
formazione.edizioni	Edizioni Corso	Pianificazione	EdizioneCorsoView	nessuna	View
formazione.corsi	Corsi	Didattica	/formazione-corsi/	nessuna	Link
formazione.registro	Registro Presenze	Didattica	/corsoview/list/?context=registro_presenze	nessuna	Link legacy
formazione.aule	Aule	Didattica	AulaView	nessuna	View
formazione.docenti	Docenti	Didattica	DocenteView	nessuna	View
formazione.iscrizioni	Iscrizioni e Discenti	Didattica	/formazione-iscrizioni/	nessuna	Link
formazione.corsisti_workspace	Carica Corsisti	Didattica	/formazione-corsisti-workspace/	nessuna	Link
formazione.import_corsisti	Import Corsisti	Didattica	/formazione-import-corsisti/	nessuna	Link
formazione.legacy_mapping	Mappatura Corsi Legacy	Didattica	/formazione-legacy-course-mapping/	feature.formazione.woocommerce_sync o admin only	Da classificare
formazione.materiali	Materiali Formazione	Didattica	MaterialeFormazioneView	nessuna	View
formazione.categorie	Categorie Formazione	Didattica	/formazione-categorie/tree	nessuna	Link/tree
formazione.monitoraggio	Monitoraggio Formazione	Monitoraggio	FormazioneMonitoraggioView	nessuna	View
formazione.woocommerce_enrollments	Iscrizioni WooCommerce	Monitoraggio	/formazione-woocommerce-enrollments/	feature.formazione.woocommerce_sync	Oggi deriva da policy tenant
formazione.sconti	Sconti Formazione	Monitoraggio	/formazione-sconti/	feature.formazione.woocommerce_sync	Collegato a quote/sconti
formazione.woocommerce_catalog	Catalogo WooCommerce	Monitoraggio	/formazione-woocommerce-sync/	feature.formazione.woocommerce_sync	Oggi deriva da policy tenant
formazione.woocommerce_manuale	Manuale WooCommerce	Monitoraggio	/formazione-dashboard/manuale-woocommerce	feature.formazione.woocommerce_sync	Link
formazione.reportistica	Reportistica Formazione	Monitoraggio	/formazione-reportistica/	nessuna	Link
formazione.scadenze	Scadenze Attestati	Monitoraggio	/formazione-scadenze-attestati/	nessuna	Link
formazione.gap_mansioni	Gap Formativo per Mansione	Monitoraggio	/formazione-gap-mansioni/	nessuna	Link
formazione.storico_verifiche	Storico da Verificare	Monitoraggio	FormazioneStoricoVerificheView	feature.formazione.language_check	Da formalizzare
formazione.survey	Questionari Gradimento	Monitoraggio	CorsoSurveyView	nessuna	View
formazione.qualita	Qualita Formazione	Monitoraggio	FormazioneQualitaView	nessuna	View
formazione.notify_audit	Audit Invii Formazione	Monitoraggio	FormazioneNotifyAuditView	nessuna	View
formazione.clienti	Clienti	Anagrafiche	/clienti/	nessuna	Dipendenza core anagrafiche
formazione.dipendenti	Dipendenti	Anagrafiche	/formazione-discenti/	nessuna	Link
formazione.enti	Enti Formatori	Anagrafiche	FormazioneEnteFormatoreView	nessuna	View

Modelli dati Formazione da considerare

Modello	Area
Aula	Pianificazione
Docente	Pianificazione/didattica
Corso	Catalogo corsi
EdizioneCorso	Edizioni
DataCorso	Date e calendario
DipendenteCorso	Partecipazioni/iscrizioni
DipendenteCorsoFirma	Registro/firme
MaterialeFormazione	Materiali
CorsoSurvey	Questionari
FormazioneNotifyAudit	Audit invii
FormazioneCalendarPreference	Preferenze calendario
FormazioneExternalCategoryMap	Integrazione WooCommerce
FormazioneExternalCourseMap	Integrazione WooCommerce
FormazioneExternalEnrollmentMap	Integrazione WooCommerce
FormazioneExternalSyncLog	Audit sync esterno
FormazioneDiscountRule	Sconti/prezzi formazione
FormazioneQuoteSeatReservation	Preventivi/posti
FormazioneQuoteParticipant	Partecipanti preventivo
FormazioneEnteFormatore	Enti/provider

Limiti target per Formazione

Limit key	Significato	Piano base	Piano pro	Piano enterprise
courses.active	Corsi attivi	limitato	piu alto	custom
editions.monthly	Edizioni create/mese	limitato	piu alto	custom
students.active	Discenti attivi	limitato	piu alto	custom
certificates.monthly	Attestati generati/mese	limitato	piu alto	custom
surveys.monthly	Questionari/mese	limitato	piu alto	custom
woocommerce.products	Prodotti sincronizzati	non incluso	incluso	custom
woocommerce.orders.monthly	Ordini/import/mese	non incluso	incluso	custom
external_portal.users	Utenti portale esterno	add-on	incluso opzionale	custom

Nota: nella prima implementazione questi limiti possono essere solo descrittivi/reporting, non enforcement bloccante.

Piani suggeriti

Piano	Include	Esclude
trial	cruscotto, corsi, date, iscrizioni, attestati base	WooCommerce, SSO, portale esterno
base	pianificazione, didattica, monitoraggio base, scadenze attestati	WooCommerce, SSO
pro	base + reportistica completa, sconti, import avanzati, survey	SSO enterprise
enterprise	pro + SSO, portale esterno, sync certificati, limiti custom	nulla di standard
addon_woocommerce	sync catalogo, iscrizioni WooCommerce, quote/sconti	richiede base o superiore
addon_external_portal	handoff training engine	richiede feature external portal
addon_language_check	controlli linguaggio/storico verifiche	richiede configurazione tenant

Service code preliminari

Canonico proposto	Uso
SAFE_FORM_BASE	Piano base formazione
SAFE_FORM_PRO	Piano pro formazione
SAFE_FORM_ENTERPRISE	Piano enterprise formazione
SAFE_FORM_WOOCOMMERCE	Add-on WooCommerce
SAFE_FORM_EXTERNAL_PORTAL	Add-on portale esterno
SAFE_FORM_SSO	Add-on SSO
SAFE_FORM_CERTIFICATE_SYNC	Add-on sync attestati
SAFE_FORM_LANGUAGE_CHECK	Add-on verifica linguaggio

Adapter necessari

Entitlement

Mapping:

• catalogo safe_formazione;
• legacy entitlement formazione.

Prima fase:

• leggere TenantModuleEntitlement(module_code="formazione");
• non cambiare is_module_enabled("formazione");
• la subscription futura deve sincronizzare verso l'entitlement legacy.

Feature

Mapping iniziale:

• feature.formazione.external_portal;
• feature.formazione.sso_v1;
• feature.formazione.certificate_sync_v2;
• nuovo mapping logico feature.formazione.woocommerce_sync;
• nuovo mapping logico feature.formazione.language_check.

Per WooCommerce e language check, la prima versione puo leggere le policy esistenti e produrre solo diagnostica. La conversione a feature flag tenant-specific va fatta dopo shadow mode.

Menu

La prima implementazione deve calcolare il menu catalogo e confrontarlo con:

• menu reale visibile;
• policy menu label-based;
• ruoli ROLE_PROFILE_*;
• menu_formazione_enabled_current_tenant().

Non deve ancora sostituire appbuilder.add_link/add_view.

Profili

Mapping:

• operatore_formazione -> profilo operativo principale;
• admin_tenant e operatore_admin -> profili amministrativi;
• readonly -> consultazione.

Il readonly deve essere progettato, ma nella prima fase puo essere solo rilevato e riportato.

Piano di rollout senza codice runtime

Step 0 - Conferma pilota

Decisione: usare safe_formazione come primo modulo pilota.

Condizione: nessun cambio runtime nel primo passaggio.

Step 1 - Seed catalogo in specifica

Preparare i seed futuri per:

• module_catalog;
• module_feature;
• module_profile;
• module_menu_item;
• module_dependency;
• module_plan;
• module_service_mapping.

Output atteso: file seed o migrazione da implementare nella fase successiva.

Step 2 - Shadow menu

Obiettivo:

• generare menu previsto da catalogo;
• confrontarlo con il menu attuale per tenant/profilo;
• produrre report differenze.

Tenant di test:

• tenant_besant;
• tenant_retra;
• tenant_fornautic;
• un tenant con formazione disabilitata, es. tenant_netopen.

Step 3 - Adapter entitlement

Obiettivo:

• verificare che safe_formazione e formazione diano lo stesso stato effettivo;
• nessuna scrittura implicita in lettura;
• report su mismatch tenant.

Step 4 - Adapter feature

Obiettivo:

• mappare feature esistenti;
• evidenziare policy hardcoded WooCommerce/language check;
• proporre conversione a TenantFeatureFlag.

Step 5 - Control-plane preview

Obiettivo:

• mostrare per ogni tenant: modulo, piano, feature, menu, profili, limiti;
• nessuna attivazione distruttiva;
• esportazione report.

Step 6 - Primo enforcement limitato

Solo dopo report puliti:

• route portale esterno;
• menu WooCommerce;
• menu language check.

Non iniziare da corsi/iscrizioni base, perche' sono il cuore operativo del modulo.

Idoneita finale

Valutazione: si, Formazione e' possibile come primo modulo pilota.

Motivi:

• ha un confine funzionale chiaro;
• ha gia un entitlement dedicato;
• ha feature flag dedicate;
• ha un profilo dedicato;
• ha tenant pilota gia configurati;
• ha menu numeroso ma concentrato.

Rischi:

• molte route BaseView potrebbero non avere enforcement uniforme;
• WooCommerce e quote toccano flussi commerciali;
• parte delle feature e' hardcoded in tenant_policy.py;
• il menu attuale usa molte label strutturali;
• il readonly non e' garantito ovunque.

Conclusione operativa: procedere con Formazione, ma il primo rilascio deve essere catalogo + shadow + preview. L'enforcement reale deve arrivare solo dopo avere confrontato catalogo e runtime su tenant pilota.

Checklist prima del codice

1. Approvare codice canonico safe_formazione.
2. Approvare mapping legacy safe_formazione -> formazione.
3. Approvare menu target.
4. Decidere se feature.formazione.woocommerce_sync e feature.formazione.language_check diventano feature flag ufficiali.
5. Decidere tenant pilota primario: consigliato tenant_besant perche' include WooCommerce.
6. Decidere tenant controllo negativo: consigliato tenant_netopen perche' ha formazione disabilitata.
7. Decidere che la prima implementazione non sostituisce il menu attuale.