Inventory/docs/superpowers/session-2026-04-04-ux-overhaul.md

Session 04-05 avril 2026 — Refonte UX/UI complète Inventory

Contexte

L'utilisateur (gestionnaire) remonte que les utilisateurs novices se perdent dans l'app Inventory (gestion d'inventaire industriel : machines, composants, pièces, produits). Ils découvrent le domaine ET l'app en même temps, remplissent les machines depuis de la documentation papier/PDF.

Ce qui a été fait

1. Analyse UX/UI complète

• Exploration en profondeur des 65+ composants, toutes les pages, composables et patterns
• Diagnostic : navigation top-down uniquement, pas de liens inverses, pas de breadcrumbs, navbar mélange tout, pages trop longues, mode lecture ressemble à un formulaire disabled
• Identification de 23 améliorations organisées en 4 phases

2. Spec rédigée

Fichier : docs/superpowers/specs/2026-04-04-ux-overhaul-design.md

23 sections couvrant :

• Réorganisation navbar par domaine métier
• Breadcrumbs contextuels
• Liaisons inverses "Utilisé dans"
• Liens cliquables dans la hiérarchie machine
• Système d'onglets partagé (machine + composant + pièce + produit)
• Pages catalogue unifiées (catalogue + catégories en onglets)
• Recherche globale (retirée à la demande de l'utilisateur)
• Raccourcis clavier (retirés à la demande)
• Mode lecture texte brut, empty states, toasts, responsive, etc.

3. Phase 1 — Quick wins (9 améliorations, 0 backend)

Plan : docs/superpowers/plans/2026-04-04-ux-quick-wins.md

Changement	Fichiers modifiés
Liens cliquables dans hiérarchie machine	ComponentItem, PieceItem, MachineProductsCard
Site → machines (badge cliquable)	SiteCard, index.vue
Retour contextuel (NuxtLink au lieu de router.back)	DetailHeader
Confirmations sur toutes les suppressions	CommentSection, machine/[id].vue
Header sticky composants expanded	ComponentItem
DataTable fixedLayout opt-in + minWidth	DataTable.vue, dataTable.ts
Mode lecture texte brut (26 div-inputs → <p>)	MachineInfoCard, 3 pages détail
Compteurs titres sections machine	MachineComponentsCard, MachinePiecesCard, MachineDocumentsCard
Cohérence fiches (liens catégorie + EntityVersionList)	3 pages détail entité

Review Phase 1 : a détecté 4 issues corrigées :

• component.entityId → component.composantId (property n'existait pas)
• piece.entityId → piece.pieceId
• table-fixed global → opt-in via prop fixedLayout
• NuxtLinks sans ?from=machine&machineId=xxx → ajouté

4. Phase 2 — Refactoring structurel (7 améliorations)

Plan : docs/superpowers/plans/2026-04-04-ux-phase2-structural.md

Changement	Fichiers créés/modifiés
EntityTabs composant partagé	components/common/EntityTabs.vue (nouveau)
Onglets page machine + header compact	machine/[id].vue, MachineDetailHeader.vue
Onglets composant/pièce/produit	3 pages détail
Pages catalogue unifiées /catalogues/*	3 nouvelles pages + ManagementView modifié
Navbar réorganisée (Catalogues + Administration)	AppNavbar.vue
Breadcrumbs contextuels	components/layout/AppBreadcrumb.vue (nouveau), app.vue
Redirections legacy URLs	middleware/legacy-redirects.global.ts (nouveau)
Guard modifications non sauvegardées	composables/useUnsavedGuard.ts (nouveau)

5. Phase 3 — Harmonisation visuelle (3 améliorations)

Changement	Fichiers
EmptyState composant partagé	components/common/EmptyState.vue (nouveau), 3 pages
Toasts erreur persistent + barre progression	useToast.ts, ToastContainer.vue
Responsive mobile (breadcrumbs tronqués, tabs scroll)	AppBreadcrumb, EntityTabs, vérification grids

6. Phase 4 — Backend + reverse links (6 améliorations)

Changement	Fichiers
Endpoint /api/{entity}/{id}/used-in	src/Controller/UsedInController.php (nouveau)
UsedInSection frontend	composables/useUsedIn.ts + components/common/UsedInSection.vue (nouveaux), 3 pages détail
Endpoint /api/constructeurs/stats	src/Controller/ConstructeurStatsController.php (nouveau)
Page fournisseurs enrichie (compteurs cliquables)	constructeurs.vue
Endpoint /api/model_types/{id}/related-items	src/Controller/ModelTypeRelatedItemsController.php (nouveau)
Modal catégorie enrichie (machine count + liens)	RelatedItemsModal.vue

Bugs découverts et corrigés en cours de route

Bug	Cause	Fix
<script setup> sans lang="ts"	Agents ont ajouté as string dans des fichiers JS	Ajouté lang="ts" sur ComponentItem, PieceItem, machine/[id]
Cannot access 'selectedType' before initialization	Bug pré-existant dans usePieceEdit.ts — resolvedStructure utilisait selectedType avant sa déclaration	Déplacé resolvedStructure avant useCustomFieldInputs
CommonEmptyState non résolu	pathPrefix: false dans nuxt.config → les composants dans common/ s'importent sans préfixe	Renommé CommonEmptyState → EmptyState, CommonUsedInSection → UsedInSection
/api/constructeurs/stats retourne 404	Route API Platform /api/constructeurs/{id} matchait "stats" comme un {id}	Ajouté priority: 1 sur la route bulk stats
Compteurs fournisseurs tous à 0	Tables *_constructeur_links vides — liens jamais migrés depuis les tables legacy M2M	Restauré depuis backup + créé migration Doctrine
Pages /catalogues/* manquantes sur le disque	Fichiers committés par agents mais perdus dans le working tree (confusion frontend/ vs app/)	Restauré depuis git history

Problème de données découvert

Les liens constructeur ↔ entités n'avaient jamais été migrés des anciennes tables ManyToMany (_composantconstructeurs, _piececonstructeurs) vers les nouvelles tables de liens (*_constructeur_links). Ce problème est pré-existant au refactoring UX.

Données restaurées en local

• 3 liens composant-constructeur
• 23 liens pièce-constructeur (dont 6 Limatech remappé avec le nouvel ID)

Données irrémédiablement perdues (entités supprimées)

• Convoyeur à Bande → était lié à Brillaud + Bühler
• Sangle E12 → était liée à NETCO
• Arbre du tambour tête E6 → était lié à Dexis

Migrations créées pour la prod

1. migrations/Version20260405_MigrateConstructeurLinks.php — copie depuis les tables legacy M2M (si elles existent)
2. migrations/Version20260405_RestoreConstructeurLinksFromBackup.php — fallback : insère directement les données du backup (3), nettoie les orphelins

Pour restaurer en prod : php bin/console doctrine:migrations:migrate

Fichiers de référence

Fichier	Contenu
docs/superpowers/specs/2026-04-04-ux-overhaul-design.md	Spec complète des 23 améliorations
docs/superpowers/plans/2026-04-04-ux-quick-wins.md	Plan Phase 1 (11 tasks)
docs/superpowers/plans/2026-04-04-ux-phase2-structural.md	Plan Phase 2 (11 tasks)
docs/superpowers/session-2026-04-04-ux-overhaul.md	Ce résumé

Branche

feat/ux-quick-wins — ~30 commits depuis develop

Nouveaux composants/composables créés

• app/components/common/EntityTabs.vue
• app/components/common/EmptyState.vue
• app/components/common/UsedInSection.vue
• app/components/layout/AppBreadcrumb.vue
• app/composables/useUsedIn.ts
• app/composables/useUnsavedGuard.ts
• app/middleware/legacy-redirects.global.ts
• app/pages/catalogues/composants.vue
• app/pages/catalogues/pieces.vue
• app/pages/catalogues/produits.vue

Nouveaux controllers backend

• src/Controller/UsedInController.php
• src/Controller/ConstructeurStatsController.php
• src/Controller/ModelTypeRelatedItemsController.php

Points d'attention pour la suite

1. Tester visuellement toutes les pages sur localhost:3001 avant merge
2. Lancer les migrations en prod pour restaurer les liens constructeur
3. Les anciennes URLs (/component-catalog, /pieces-catalog, etc.) redirigent automatiquement
4. Le menu Administration n'est visible que pour les gestionnaires/admins (canEdit)
5. L'onglet Catégories dans les pages catalogue n'est visible que pour canEdit
6. Le useUnsavedGuard n'est pas encore intégré dans les pages (composable créé, pas branché)