From d7c011238c32884c79fcd068f7455cc6de02bc36 Mon Sep 17 00:00:00 2001 From: root Date: Sat, 22 Aug 2026 21:17:03 +0000 Subject: [PATCH] docs(audit): finaliser audit UX et version locale --- docs/ui-audit/BUGS.md | 33 ++++ docs/ui-audit/PAGES_MATRIX.md | 10 + docs/ui-audit/PROGRESS.md | 35 ++++ docs/ui-audit/REPORT.md | 63 +++++++ docs/ui-audit/UX_PROPOSALS.md | 339 ++++++++++++++++++++++++++++++++++ 5 files changed, 480 insertions(+) create mode 100644 docs/ui-audit/UX_PROPOSALS.md diff --git a/docs/ui-audit/BUGS.md b/docs/ui-audit/BUGS.md index 59c1e4a..3abb8ef 100644 --- a/docs/ui-audit/BUGS.md +++ b/docs/ui-audit/BUGS.md @@ -487,3 +487,36 @@ formulaire produit, empêchant de rendre un produit disponible sur les fiches papier. Le champ est maintenant éditable avec un libellé explicite ; la modification du produit ID 1 a été enregistrée et le produit apparaît dans le profil de demande. Statut : **VALIDÉ LOCALEMENT SUR COPIE VM**. + +## Phase finale — éléments encore ouverts + +### UI-011 — centre documentaire global absent + +- **Reproduction locale** : `GET /documents/` répond HTTP 404. +- **Constat** : les documents sont exposés dans les fiches équipement, + intervention et produits d'entretien ; aucune route d'index documentaire + globale n'est clairement prévue. +- **Impact** : un utilisateur peut suivre une URL ou chercher « Documents » + et recevoir une erreur au lieu d'une orientation. +- **Statut** : **OUVERT — P2 / décision fonctionnelle nécessaire**. +- **Recommandation** : choisir entre un centre documentaire global (recherche, + permissions et catégories à définir) ou supprimer/redirecter le lien global + vers les pages documentaires existantes. Proposition détaillée dans + `UX_PROPOSALS.md`. Aucun module nouveau n'a été ajouté pendant l'audit. + +### Observations UX non corrigées + +- Menus denses et regroupements hétérogènes, proposition UX-P1. +- États vides ne guidant pas toujours vers la prochaine action, UX-P1. +- Unités et conséquences d'actions à expliciter dans plusieurs formulaires, + UX-P1/UX-P2. +- Campagne visuelle responsive/accessibilité exhaustive encore partielle. + +### Test d'isolation RBAC — corrigé + +Le test `test_admin_is_explicit_and_loses_removed_permission` retirait une +permission du rôle système `admin` sans la restaurer, ce qui provoquait un +faux échec ultérieur du smoke stock selon l'ordre d'exécution. Le test restaure +maintenant le lien dans un bloc `finally` (`933f0a5`). La suite ciblée passe +22/22 et la suite complète ne conserve plus que l'échec historique GMAO +lookback hors périmètre et son erreur de teardown. diff --git a/docs/ui-audit/PAGES_MATRIX.md b/docs/ui-audit/PAGES_MATRIX.md index c9b7221..c84ee88 100644 --- a/docs/ui-audit/PAGES_MATRIX.md +++ b/docs/ui-audit/PAGES_MATRIX.md @@ -101,3 +101,13 @@ Matrice initiale issue du smoke test authentifié avec `chatgpt`. Les pages d'intégration et de configuration interdites ne sont pas testées activement. + +## Contrôle final local + +| Page | URL | Résultat local | Commentaire | +|---|---|---:|---| +| Centre documentaire global | `/documents/` | 404 | UI-011 ouvert ; documents disponibles dans leurs modules | +| FDS / fiches techniques | `/cleaning/documents` | 200 | Page stock documentaire | +| Détail équipement groupé | `/equipments/3` | 200 | Filtre `nl2br` enregistré ; quantité 30 affichée | +| Hiérarchie équipement groupé | `/equipments/3/hierarchy` | 200 | Bâtiment → zone → salle → quantité | +| Health | `/health/` | 200 | Version à recontrôler après rebuild `0.1.0-dev.3` | diff --git a/docs/ui-audit/PROGRESS.md b/docs/ui-audit/PROGRESS.md index 5766588..c3ce078 100644 --- a/docs/ui-audit/PROGRESS.md +++ b/docs/ui-audit/PROGRESS.md @@ -7,6 +7,41 @@ Dernière mise à jour : 22 août 2026 — reprise après interruption. État : **en cours**. Revalidation VM P1 effectuée ; l'audit fonctionnel doit continuer sur les scénarios encore testables. +## Phase finale locale — 22 août 2026 + +L'application locale est disponible sur `http://127.0.0.1:5080/`, avec +MariaDB restaurée depuis la copie VM. Les contrôles locaux UI-017, UI-031 et +UI-012 sont validés et les scénarios équipements (déplacement, quantité, +réparation, remise en service, rebut et équipement fixe) sont exécutés sur +des données `TEST_UI_*`. Les intégrations interdites et l'utilisateur `alban` +n'ont pas été touchés. + +La version de référence a été incrémentée de **0.1.0-dev.2** à +**0.1.0-dev.3** dans le commit `50d3fd0`. `VERSION` reste la source de vérité; +les valeurs Docker de secours sont alignées sur cette version. Une +reconstruction locale est à effectuer pour que le conteneur actuellement +exécuté expose cette nouvelle version. + +La cartographie UX finale et les propositions (menu, onboarding, états vides, +formulaires, confirmations, TOP 10 et quick wins) sont dans +`docs/ui-audit/UX_PROPOSALS.md`. Aucun changement de refonte UX n'a été +implémenté. + +Couverture estimée : **environ 85 %**. Les principaux workflows patrimoine, +interventions, stock, prévention et RBAC ont été testés localement ; restent +partiels la recherche documentaire globale, certaines variantes de planning, +les tests visuels complets responsive/accessibilité et une installation neuve. + +### Suite automatisée finale + +- Tests ciblés version/P1/cycle de vie : **20 passed**. +- RBAC + régressions P1 : **22 passed**. +- `pytest` complet après isolation du test RBAC : **122 passed, 1 failed, + 1 error** sur 123 tests. Le seul échec restant est le test historique de + configuration/lookback GMAO hors périmètre ; son teardown échoue parce que + cette configuration de test utilise un `user_id` nul. Le test stock qui + dépendait de l'ordre RBAC est désormais isolé et passe. + ## Phases | Phase | État | Notes | diff --git a/docs/ui-audit/REPORT.md b/docs/ui-audit/REPORT.md index 85f6ad3..e4c7274 100644 --- a/docs/ui-audit/REPORT.md +++ b/docs/ui-audit/REPORT.md @@ -235,3 +235,66 @@ watchdogs et intégrations restent hors périmètre et non sollicités. Le blocage UI-023 est également levé localement : `request_enabled` est exposé dans le formulaire produit, le produit de test a été activé et il est désormais proposé dans la création d'une fiche papier. + +## Phase finale — synthèse fonctionnelle, UX et version + +### Versionnement + +La source applicative est `VERSION`, lue par `app_new/version.py`. Le +Dockerfile et les valeurs de secours Compose sont maintenant alignés sur +`0.1.0-dev.3` (commit `50d3fd0`), au lieu de `0.1.0-dev.2`. La version est +exposée par la configuration Flask et `/health/`; après reconstruction de +l'image, vérifier également le pied de page et les endpoints de statut. Le +test unitaire de lecture de version passe. La version affichée par le +conteneur actuellement lancé doit être recontrôlée après rebuild. + +### Menus et navigation + +Les menus principaux sont accessibles séquentiellement : Accueil, Alertes, +Interventions, Équipements, stock/entretien et Administration. Les contrôles +RBAC locaux confirment l'absence du lien Journaux sans +`watchdog_dnd.view`, tout en conservant le refus backend 403. Les menus +restent toutefois très denses et regroupent des fonctions quotidiennes, +administratives et d'intégration ; la proposition de regroupement par tâches +se trouve dans `UX_PROPOSALS.md` et n'est pas implémentée. + +`/documents/` répond toujours 404 (UI-011). Les documents sont actuellement +gérés dans les fiches intervention, équipement et produits d'entretien ; la +décision entre centre documentaire global et suppression du lien global reste +à valider. + +### Expérience débutant + +Les scénarios locaux bâtiment → zone → salle → équipement, déplacement, +réparation, rebut, stock FEFO et fiche papier sont réalisables avec des +données de test, mais l'ordre des prérequis n'est pas suffisamment expliqué +pour un nouvel utilisateur. Les principales recommandations sont : checklist +de premiers pas, états vides actionnables, unités explicites, confirmations +décrivant les conséquences et libellés métier des permissions. + +### Responsive et accessibilité + +Les contrôles précédents sur plusieurs listes à 390×844 et 768×1024 n'ont pas +révélé de débordement sur les pages parcourues. Une campagne visuelle complète +avec navigateur instrumenté, focus clavier, lecteurs d'écran et mesures de +contraste reste partielle et doit être exécutée avant installation neuve. + +### Statut final de cette passe + +Audit global estimé à **85 %**. Les résultats détaillés, le TOP 10 UX, les +quick wins, l'arborescence proposée et les sujets nécessitant validation sont +dans `docs/ui-audit/UX_PROPOSALS.md`. Les éléments encore ouverts sont +principalement UI-011, les contrôles UX/accessibilité exhaustifs, certaines +variantes de planning et la validation sur installation neuve. + +### Tests automatisés finaux + +- Version, P1 et cycle de vie : **20 passed**. +- RBAC et régressions P1 : **22 passed** après restauration systématique de la + permission `stock.view` du rôle système de test. +- Suite complète : **122 passed, 1 failed, 1 error** sur 123. L'unique échec + restant est `test_gmao_config_caps_lookback_at_one_year`, volontairement + hors périmètre (contexte/configuration GMAO interdite) ; son teardown échoue + également sur la contrainte `gmao_context.user_id NOT NULL`. Aucun nouveau + échec fonctionnel n'a été introduit. La correction d'isolation est dans + `933f0a5`. diff --git a/docs/ui-audit/UX_PROPOSALS.md b/docs/ui-audit/UX_PROPOSALS.md new file mode 100644 index 0000000..059cb9e --- /dev/null +++ b/docs/ui-audit/UX_PROPOSALS.md @@ -0,0 +1,339 @@ +# Propositions UX — phase finale + +Document de propositions, sans refonte implémentée. Les observations +proviennent de la navigation locale sur copie de la base VM et des contrôles +statiques des menus et formulaires. Les intégrations interdites (watchdogs, +Pronote, ENT, Outlook et configuration IA) n'ont pas été déclenchées. + +## Proposition UX-P1 — parcours « premiers pas » + +### Problème observé + +La dépendance Site/Bâtiment → Zone → Salle → Équipement est réelle, mais le +menu n'explique pas cet ordre. Une liste vide indique souvent seulement qu'il +n'y a aucun résultat. + +### Exemple concret + +Pour créer 30 chaises, un débutant doit deviner qu'il faut d'abord ouvrir le +menu « Équipements », puis créer le bâtiment, la zone, la salle et enfin +l'équipement groupé. + +### Utilisateur concerné + +Gestionnaire de collège débutant. + +### Solution proposée + +Ajouter une checklist légère et dismissible : « 1. Créer un bâtiment → 2. +Créer une zone → 3. Créer une salle → 4. Ajouter un équipement ». Dans chaque +état vide, afficher le prérequis manquant et un bouton d'action direct. + +### Bénéfice + +Réduit les erreurs de navigation et le besoin de formation initiale. + +### Risque + +Faible si la checklist est informative et n'impose aucun parcours. + +### Effort estimé + +Moyen (états vides, permissions et liens contextuels). + +### Priorité + +UX-P1 + +## Proposition UX-P1 — menu métier resserré + +### Problème observé + +Le menu « Équipements » mélange patrimoine, entreprises, contrats, stock, +prévisions et cycle de vie. Le menu « Interventions » mélange interventions, +planning, exports, compteurs et tâches administratives. Le même vocabulaire +n'est pas toujours utilisé dans les titres et les URLs. + +### Exemple concret + +Pour trouver une FDS, l'utilisateur doit ouvrir « Équipements », puis +« Matériel & Entretien », puis « FDS / fiches techniques ». + +### Utilisateur concerné + +Gestionnaire patrimoine, agent d'entretien et responsable maintenance. + +### Solution proposée + +Regrouper les entrées par tâches métier (voir l'arborescence proposée plus +bas), conserver les URLs existantes et masquer les entrées selon la +permission effective. + +### Bénéfice + +Les actions quotidiennes sont repérables sans connaître l'architecture Flask. + +### Risque + +Risque de régression de navigation et de permissions si réalisé en une seule +refonte. + +### Effort estimé + +Élevé. + +### Priorité + +UX-P1 — validation produit nécessaire avant implémentation. + +## Proposition UX-P2 — états vides actionnables + +### Problème observé + +Les messages « Aucun résultat » ne distinguent pas une recherche infructueuse +d'une base non configurée. + +### Exemple concret + +Une salle sans zone ou un stock sans emplacement ne donne pas toujours le +prochain geste à effectuer. + +### Utilisateur concerné + +Tout nouvel administrateur fonctionnel. + +### Solution proposée + +Afficher « Aucun élément pour le moment », le prérequis éventuel, un exemple +de donnée attendue et un bouton « Créer … » lorsque la permission le permet. + +### Bénéfice + +Moins d'abandons et moins de tickets de support. + +### Risque + +Un bouton affiché sans permission doit rester masqué. + +### Effort estimé + +Faible à moyen. + +### Priorité + +UX-P2 + +## Proposition UX-P2 — formulaires guidés et unités + +### Problème observé + +Plusieurs formulaires utilisent des champs génériques (quantité, durée, +stock-minimum) dont l'unité ou l'effet n'est pas toujours visible au premier +coup d'œil. + +### Exemple concret + +Une quantité de stock doit préciser s'il s'agit de litres, kilogrammes, +flacons ou unités ; une intervention doit expliquer les relations +optionnelles salle/équipement. + +### Utilisateur concerné + +Agents d'entretien et responsables de stock. + +### Solution proposée + +Ajouter unités dans le label et une aide courte sous le champ. Conserver les +valeurs après erreur et indiquer le premier champ invalide. + +### Bénéfice + +Réduit les erreurs de stock et les saisies incomplètes. + +### Risque + +Les unités doivent provenir du modèle métier, pas être inventées dans le +template. + +### Effort estimé + +Moyen. + +### Priorité + +UX-P2 + +## Proposition UX-P1 — confirmations dangereuses explicites + +### Problème observé + +Certaines actions utilisent une confirmation courte (« Êtes-vous sûr ? ») +qui n'explicite pas les conséquences. + +### Exemple concret + +Un rebut doit distinguer la sortie définitive du patrimoine d'une mise en +réparation temporaire ; une sortie de stock doit afficher la quantité et le +lot concerné. + +### Utilisateur concerné + +Responsable maintenance et stock. + +### Solution proposée + +Afficher l'objet, la quantité, la destination et l'effet sur l'inventaire, +avec un bouton d'annulation clairement secondaire. + +### Bénéfice + +Évite les pertes de stock et les suppressions involontaires. + +### Risque + +Une confirmation trop fréquente ralentit les opérations répétitives. + +### Effort estimé + +Faible à moyen. + +### Priorité + +UX-P1 + +## Proposition UX-P2 — page Documents cohérente + +### Problème observé + +`/documents/` répond 404 (UI-011), alors que les documents sont répartis dans +les fiches équipement, intervention et produits d'entretien. + +### Exemple concret + +Un utilisateur qui cherche une FDS peut essayer une page globale Documents et +obtenir une erreur. + +### Utilisateur concerné + +Agent cherchant une FDS ou une pièce jointe. + +### Solution proposée + +Décider explicitement entre (a) une page globale de recherche documentaire ou +(b) supprimer tout lien global et renvoyer vers les trois contextes métier. +Ne pas créer une nouvelle hiérarchie avant décision fonctionnelle. + +### Bénéfice + +Élimine un lien mort et rend les documents retrouvables. + +### Risque + +Une page globale implique recherche, permissions et règles de conservation. + +### Effort estimé + +Moyen à élevé selon l'option retenue. + +### Priorité + +UX-P2 + +## Arborescence de menu proposée (non implémentée) + +```text +Accueil + Tableau de bord + Alertes + +Patrimoine + Sites / bâtiments + Zones + Salles + Équipements + Cycle de vie + Équipements sortis + +Maintenance + Interventions + Planning + Tâches préventives + Compteurs + Entreprises et contrats + Exports + +Produits et stocks + Produits génériques + Références et conditionnements + État du stock + Réceptions + Sorties agents + Transferts et inventaires + FDS et fiches techniques + Fiches papier + Prévisions + +Prévention + DUERP et risques + Actions + Formations + Habilitations + +Administration + Utilisateurs + Rôles et permissions + Journaux + Statut système +``` + +Les intégrations et paramètres sensibles doivent rester dans un espace +« Configuration technique » réservé aux administrateurs autorisés, sans être +présentés comme des tâches quotidiennes. + +## Aide contextuelle proposée + +- Équipement groupé : expliquer « quantité totale » et « individualisation ». +- Équipement fixe/mobile : préciser si un déplacement est autorisé. +- Personnel/utilisateur : distinguer la personne affectée d'un compte de + connexion. +- Lot/DLU/FEFO : expliquer que le lot expirant le plus tôt est consommé en + premier. +- Fiche papier : expliquer `request_enabled` avec un libellé métier (« Peut + être demandé par un agent »), jamais le nom technique. +- Permissions : afficher une phrase d'effet (« consulter », « créer et + modifier », « administrer »). + +## TOP 10 DES AMÉLIORATIONS UX + +| Rang | Amélioration | Impact | Effort | Risque | Priorité | +|---:|---|---|---|---|---| +| 1 | Checklist des premiers pas | Très fort | Moyen | Faible | UX-P1 | +| 2 | États vides avec action suivante | Fort | Faible | Faible | UX-P1 | +| 3 | Corriger ou décider `/documents/` | Fort | Moyen | Moyen | UX-P2 | +| 4 | Menu par tâches métier | Très fort | Élevé | Élevé | UX-P1 | +| 5 | Unités et aides des formulaires stock | Fort | Moyen | Faible | UX-P2 | +| 6 | Confirmations de rebut/transfert explicites | Fort | Faible | Faible | UX-P1 | +| 7 | Libellés métier des permissions | Fort | Moyen | Moyen | UX-P2 | +| 8 | Indiquer les relations optionnelles d'une intervention | Moyen | Faible | Faible | UX-P2 | +| 9 | Recherche documentaire contextuelle | Moyen | Moyen | Moyen | UX-P2 | +| 10 | Résumé « à faire aujourd'hui » au dashboard | Très fort | Élevé | Moyen | UX-P1 | + +## QUICK WINS + +1. Remplacer les noms techniques de champs visibles par des libellés métier. +2. Ajouter l'unité directement dans les labels de quantité. +3. Ajouter un bouton de création dans les principaux états vides. +4. Décrire les conséquences dans les confirmations de rebut et sortie. +5. Afficher une explication utilisateur sur les refus 403. +6. Ajouter un test de liens internes empêchant le retour accidentel de `/documents/`. + +## Éléments soumis à validation avant implémentation + +- Arborescence de menu et déplacement des entrées. +- Checklist/onboarding et persistance de son état. +- Décision d'une page documentaire globale. +- Vocabulaire officiel « salle/local », « agent/personnel » et + « entreprise/fournisseur ». +- Priorisation du dashboard et définition des indicateurs urgents. +- Granularité future des permissions métier. +