# 08 - Migliorie app post confronto cross-app ## Piano iniziale 1. Consolidare le evidenze gia presenti in `07_differenze_cross_app.md` e in `cross_app_capability_registry.md`. 2. Tradurre le differenze in un backlog di migliorie pratiche, con priorita, impatto, costo e rischio per ogni voce. 3. Limitare le proposte alle aree con evidenza reale nel corpus locale: - griglie e filtri - error handling e messaggistica - sessione, back browser e continuita del flusso - standard documentali e tassonomia riusabile 4. Separare chiaramente: - quick win - interventi medi - interventi strutturali 5. Chiudere con assunzioni, limiti e punti da validare col team per evitare letture oltre l’evidenza disponibile. ## Contesto e perimetro analisi migliorie `yii-framework-base` e il repository documentale del layer Yii/Sophia comune, non una business app verticale. Di conseguenza questa analisi non propone nuove funzionalita di dominio, ma migliorie sul modo in cui il layer base supporta le applicazioni verticali documentate nel corpus. Le fonti gia consolidate usate come base sono: - `07_differenze_cross_app.md` - `cross_app_capability_registry.md` - `structure_and_functions.md` - `sophia_customizations.md` Il perimetro delle migliorie e quindi centrato sulle aree dove il repository base mostra una maturita tecnica piu alta o un ruolo di canonizzazione: - rendering e comportamento delle griglie - filtri avanzati e interazione con `jquery.yiigridview.js` - error handling e pagine di fallback - sessione e continuita di navigazione - linee guida documentali e registry cross-app ## Mappa attriti principali dell'app corrente ### 1. Documentazione tecnica molto forte, ma poco orientata al riuso operativo Il repository spiega bene i componenti core di Yii e le customizzazioni Sophia, pero la trasformazione di queste evidenze in regole operative per le app verticali resta ancora dispersa tra piu documenti. Impatto: - chi analizza un verticale deve ricostruire la stessa regola da piu fonti - aumenta il tempo di onboarding per nuovi agenti o sviluppatori ### 2. Le customizzazioni griglia sono ricche, ma non ancora riassunte in una checklist applicativa `sophia_customizations.md` mostra fix e miglioramenti reali su `CGridView`, `CGridColumn` e `jquery.yiigridview.js`, ma non esiste ancora una sintesi operativa che dica quando usare quale pattern. Impatto: - rischio di applicare in modo incoerente filtri avanzati, footer estesi e comportamenti AJAX - maggiore probabilita di regressioni visive o funzionali nei verticali ### 3. La gestione errori e sessione e solida, ma poco esplicitata come standard di esperienza utente Le note su `CErrorHandler`, `exception.php` e `CHttpSession` mostrano una base robusta, ma non traducono ancora questi punti in una convenzione di UX tecnica: - come presentare gli errori - come evitare back browser confusi - come differenziare dettaglio debug e messaggio utente Impatto: - feedback meno omogenei tra schermate e progetti - più attrito nella gestione di casi limite e problemi di sessione ### 4. Il registry cross-app e utile ma ancora descrittivo Il registry mostra bene cosa e allineato, cosa e da confermare e cosa e piu maturo. Manca pero una lettura orientata all'azione: quali miglioramenti canonizzare prima per massimizzare il riuso. Impatto: - le priorita rimangono implicite - le decisioni di riallineamento richiedono ancora interpretazione manuale ## Backlog migliorie proposte | Priorita | Miglioria | Area | Impatto | Costo stimato | Rischio | |---|---|---|---|---|---| | P1 | Rendere canonica la checklist operativa delle griglie avanzate | usabilita interfaccia / affidabilita | alto | basso | basso | | P1 | Standardizzare il comportamento atteso di errori e messaggi utente | affidabilita operativa / quality of life | alto | basso-medio | basso | | P2 | Esplicitare la convenzione di sessione e continuita browser-back | affidabilita operativa | medio-alto | basso | basso | | P2 | Consolidare il registry cross-app in formato decisionale | produttivita team / riuso | medio | basso | basso | | P3 | Uniformare la tassonomia documentale e la lettura `da confermare` | qualita dati / prevenzione errori | medio | medio | basso | | P3 | Introdurre una roadmap incrementale di riallineamento tra verticali | governance tecnica | medio | medio | medio | ## Schede miglioria ### 1. Checklist canonica per griglie avanzate Problema: - le customizzazioni della griglia sono documentate in modo tecnico ma non come guida operativa unica - gli sviluppatori devono inferire i comportamenti corretti da piu documenti Proposta: - sintetizzare in una checklist unica le regole per uso di `CGridView`, `CGridColumn`, filtri avanzati, filtri inline e footer estesi - indicare i casi d'uso canonici e i casi in cui evitare combinazioni complesse Impatto: - meno regressioni sui filtri - maggiore uniformita delle interfacce tabellari tra app verticali - onboarding piu rapido per chi implementa o modifica le griglie Costo: - basso, perche si tratta soprattutto di normalizzazione documentale Rischio: - basso, non richiede modifiche invasive al codice Priorita: - P1 ### 2. Standard errore e messaggio utente Problema: - il repository spiega bene il meccanismo tecnico degli errori, ma non lo traduce in un formato UX stabile Proposta: - definire uno standard minimo per messaggi di errore e fallback: - messaggio breve per l'utente - dettaglio tecnico solo in debug - comportamento coerente per errori applicativi e sessione scaduta Impatto: - esperienze piu coerenti - minore ambiguita nei casi di errore - diagnostica piu leggibile per il team Costo: - basso-medio, soprattutto documentale con possibili adeguamenti puntuali Rischio: - basso, salvo dipendenze su view custom locali dei verticali Priorita: - P1 ### 3. Convenzione sessione e browser-back Problema: - la protezione contro i problemi di back browser e gia presente nel layer base, ma non viene sempre richiamata come vincolo di esperienza Proposta: - esplicitare la convenzione di sessione come requisito standard per form multi-step, filtri AJAX e schermate con dati sensibili - collegare la regola ai pattern documentati in `CHttpSession` Impatto: - meno falsi rientri su schermate stantie o sessioni incoerenti - flusso piu prevedibile per gli utenti Costo: - basso Rischio: - basso Priorita: - P2 ### 4. Registry cross-app decisionale Problema: - il registry attuale classifica le capability, ma non indica ancora chiaramente quale azione fare quando la classificazione e `da confermare` Proposta: - aggiungere al registry una colonna o una nota operativa che distingua: - conferma da codice - conferma da ticket - conferma da documentazione - riallineamento non necessario Impatto: - decisioni piu rapide - meno ambiguita tra evidenza diretta e inferenza - migliore trasferibilita tra analisi Costo: - basso Rischio: - basso Priorita: - P2 ### 5. Tassonomia documentale e stati di evidenza Problema: - le etichette `standard/allineata`, `piu aggiornata` e `da confermare` sono utili ma possono restare interpretative Proposta: - stabilire una micro-tassonomia uniforme per le analisi future: - verificato - verificato parzialmente - inferito - da confermare - applicarla in modo consistente ai registry e alle schede di differenza Impatto: - minore ambiguita - tracciabilita tecnica migliore - confronto cross-app piu leggibile Costo: - medio, perche richiede riallineamento di documenti gia esistenti Rischio: - basso Priorita: - P3 ### 6. Roadmap incrementale di riallineamento Problema: - senza una sequenza esplicita, le migliorie possono essere lette come lista piatta e non come piano eseguibile Proposta: - definire una roadmap a tre livelli: - quick win documentali - step intermedi di normalizzazione - interventi strutturali di governance tecnica Impatto: - miglior coordinamento - migliore prioritizzazione del lavoro sui verticali Costo: - medio Rischio: - medio, per il coinvolgimento di piu documenti e processi Priorita: - P3 ## Quick win raccomandati 1. Consolidare in `08_migliorie_app.md` una checklist sintetica delle griglie avanzate da riusare come riferimento canonico. 2. Aggiungere una mini-sezione standard su errori e sessione nelle analisi future, allineata ai comportamenti documentati qui. 3. Rendere piu leggibile il registry con una colonna o nota che distingua evidenza diretta, inferenza e punto da validare. ## Interventi medi e strutturali ### Interventi medi - Uniformare le etichette di evidenza tra le analisi 02-08. - Collegare in modo piu esplicito gli standard tecnici del framework base ai verticali che li consumano. - Introdurre un formato di review piu prescrittivo per le differenze `da confermare`. ### Interventi strutturali - Costruire un registry comune delle capability Sophia come fonte canonica per tutte le app documentate. - Trattare il repository base come standard di riferimento per griglie, error handling e sessione, con regole operative riusabili. ## Checklist verifiche eseguite - Verifica delle fonti locali gia disponibili. - Lettura di `07_differenze_cross_app.md`. - Lettura di `cross_app_capability_registry.md`. - Lettura di `structure_and_functions.md`. - Lettura di `sophia_customizations.md`. - Controllo del worktree per evitare sovrascritture. - Verifica che non esistano file `analisi/02-06` nel repo corrente. - Verifica della presenza dei documenti richiesti nel perimetro `analisi/`. ## Assunzioni, limiti e punti da validare col team ### Assunzioni - Il repository `yii-framework-base` rappresenta il layer documentale base e non una business app verticale. - Le migliorie richieste vanno intese come normalizzazione del modo in cui il layer base supporta le app applicative. - Le evidenze presenti in `07_differenze_cross_app.md` e nel registry cross-app sono sufficienti per proporre backlog documentale e di governance tecnica. ### Limiti - Non sono stati usati controlli runtime sul codice delle app verticali, quindi le equivalenze funzionali rimangono in parte inferite dalla documentazione disponibile. - Mancano nel repo corrente i documenti 02-06, quindi il richiamo alle analisi precedenti e limitato a quanto consolidato localmente nel corpus presente. - La classificazione di alcune aree come `da confermare` resta prudenziale per assenza di evidenze dirette nel repository corrente. ### Punti da validare col team - Quale formato deve avere la checklist canonica delle griglie: pagina unica, sezione nel README o allegato dedicato. - Se il registry cross-app deve diventare una fonte normativa o solo di supporto analitico. - Se le etichette di evidenza vanno allineate retroattivamente anche nei documenti gia chiusi. - Quale livello di dettaglio va mantenuto per la distinzione tra messaggio utente e dettaglio tecnico negli errori. ## Scopo Descrivere obiettivo operativo e risultato atteso. ## Perimetro Definire modulo, confini funzionali e prerequisiti. ## Flusso 1. Input e contesto. 2. Esecuzione del processo. 3. Output e verifica. ## Componenti - Controller/servizi. - Model e tabelle. - Job/log/integrazioni correlate. ## Failure mode - Errori ricorrenti. - Cause tipiche. - Segnali diagnostici. ## Checklist - Pre: prerequisiti validati. - Post: outcome e coerenza dati verificati. ## Criteri di accettazione Contenuto azionabile, verificabile e coerente con il codice.