# Refonte UX/UI Devtools

> Archive historique conservée côté `TTM_API`.
>
> Source de vérité active : `C:\Users\VT\PhpstormProjects\ttm-dev-tools\docs\DEV_TOOLS_DEPLOYMENT_AUDIT.md` et `C:\Users\VT\PhpstormProjects\ttm-dev-tools\docs\README_DEV_TOOLS_UI.md`.
>
> Ce document reflète une analyse UX/UI antérieure à l’extraction du `dev-tools` vers `ttm-dev-tools`. À utiliser seulement comme contexte d’archive.

_Date : 2026-04-06_

## Cadre du document

Ce document ne repart pas de zéro. Il transforme l’audit UX/UI précédent en plan de simplification exploitable pour la décision produit, la conception UI et l’implémentation.

Il s’appuie sur un **test réel de l’interface** mené sur la console Devtools accessible localement, avec navigation effective dans les pages, déclenchement d’actions non destructives, observation des confirmations, diagnostics, états de blocage et retours temps réel.

### Constats réellement vérifiés pendant le test
- navigation réelle dans `Build`, `Déploiement`, `Releases`, `Base de données`, `Profils`, `Runtime` ;
- build `Shared` réellement exécuté avec succès ;
- diagnostic de release réellement exécuté sur `Releases`, avec résultat bloquant côté distant ;
- test de connexion DB réellement exécuté ;
- backup DB réellement exécuté avec succès ;
- ouverture de la modale de confirmation `Activate` puis annulation volontaire ;
- ouverture de la modale de confirmation `Migrer le release` puis annulation volontaire ;
- ouverture de la modale de création de profil puis annulation volontaire ;
- lancement réel du front local depuis `Runtime`, puis arrêt réel ;
- vérification réelle de l’API distante depuis `Runtime` ;
- observation réelle d’un état de reconnexion socket / fallback HTTP ;
- observation réelle d’une coupure backend locale puis d’un redémarrage nécessaire du poste de contrôle.

### Position du document
Le but n’est pas de redécrire toute la technique interne. Le but est de proposer une **lecture cible du Devtools** alignée avec le pipeline de promotion de release suivant :

1. build des sources ;
2. création d’une release locale figée ;
3. test local de cette release ;
4. push distant sans activation ;
5. test distant ;
6. préparation d’une base compatible ;
7. migration schéma / données si nécessaire ;
8. exposition sur preview / vhost / domaine dédié ;
9. test réel ;
10. bascule en actif ;
11. rollback simple si nécessaire.

---

## 1. Diagnostic synthétique

| # | Problème majeur | Catégorie | Gravité | Pourquoi c’est un problème concret |
|---|---|---|---|---|
| 1 | Le Devtools ne raconte pas encore clairement un parcours unique de promotion de release de bout en bout. | problème de modèle produit | critique | L’utilisateur comprend les pages séparément, mais pas assez le récit global `build → push → valider → migrer → exposer → activer`. |
| 2 | Le contexte opératoire global est incomplet ou dispersé selon les pages. | problème UX | critique | On ne sait pas toujours en un coup d’œil quelle release, quelle cible, quelle base et quel runtime sont réellement en jeu. |
| 3 | Certains feedbacks contredisent l’état réel observé. | bug / incohérence technique | critique | Exemple réel : après un build `Shared` réussi, la page `Build` affichait encore un message équivalent à « aucun build sans release » alors qu’une release était bien sélectionnée et utilisée. |
| 4 | La page `Base de données` concentre trop de sous-flux sensibles au même niveau visuel. | problème de hiérarchie visuelle | critique | Diagnostic, backup, clonage, restauration, migration et maintenance sont présentés dans une même lecture dense, donc cognitivement risquée. |
| 5 | La page `Profils` reste trop technique pour servir de brique produit simple de type `Env`. | problème de modèle produit | forte | L’utilisateur voit un configurateur technique complet avant de comprendre le rôle métier de l’environnement courant. |
| 6 | Le vocabulaire mélange parfois état produit, jargon technique et détails d’implémentation. | problème de wording | forte | `profil actif`, `runtime effectif`, `config versionnée`, `couche`, `current distant`, `diagnostic layout`, `preview release` demandent un effort de traduction mental. |
| 7 | Les actions expertes restent trop proches des actions de parcours normal. | problème UX | forte | Sur plusieurs pages, maintenance, diagnostic avancé ou setup structurel apparaissent presque au même rang que l’action principale. |
| 8 | Le système de fraîcheur et de synchronisation des données n’est pas assez explicite. | problème UX | forte | Après certaines actions ou quand le socket tombe, l’utilisateur voit des états qui évoluent mais ne sait pas toujours si la donnée est fraîche, partielle, issue du temps réel ou d’un fallback HTTP. |
| 9 | La frontière entre `Runtime` comme page de contrôle et `Runtime` comme cockpit de debug avancé n’est pas assez hiérarchisée. | problème de hiérarchie visuelle | moyenne | Le terminal, les logs et les actions normales cohabitent, ce qui dilue la lecture principale. |
| 10 | Les garde-fous sont présents mais pas encore assez contextualisés juste avant décision. | problème UX | moyenne | Les confirmations existent, ce qui est bien, mais elles rappellent encore insuffisamment le triplet critique `release / cible / base` avant validation d’actions sensibles. |

### Lecture synthétique
Les problèmes les plus coûteux ne sont pas l’absence de fonctionnalités. Ils sont principalement liés à la **lisibilité du modèle produit**, à la **densité informationnelle**, à la **cohérence des feedbacks** et à la **sécurisation cognitive des opérations sensibles**.

---

## 2. Pipeline cible raconté proprement

| Étape | Intention utilisateur | Page actuelle concernée | Action actuelle | Résultat attendu | Problèmes actuels | Amélioration recommandée |
|---|---|---|---|---|---|---|
| 1. Build des sources | Fabriquer les artefacts de la release cible | `Build` | `Release complet`, `Shared`, `API locale`, `Front`, éventuellement `Build API distant` | Artefacts cohérents générés pour une release explicite | Le contexte release n’est pas toujours relu de manière fiable ; certaines cartes répètent ou contredisent le contexte global | Faire de `Build` une page strictement centrée sur `quelle release je fabrique`, avec état fiable et feedback unifié |
| 2. Création d’une release locale figée | Produire un snapshot stable et identifiable | `Build` | Sélection / saisie de release puis lancement du build | Release locale figée, manifestée et relisible | La notion de “release prête” existe mais reste dispersée entre champ, contexte et résultats techniques | Introduire un bloc de sortie clair : `Release prête localement` avec identifiant, date, projets inclus et prochain pas |
| 3. Test local de cette release | Vérifier que la release locale est exécutable avant push | `Runtime` | Démarrage local API / front, lecture health / logs / terminal | Validation locale avant promotion | Le lien produit entre `Build` et `Runtime` est implicite ; le test local ressemble à un cockpit technique plus qu’à une étape du pipeline | Ajouter un renvoi explicite depuis `Build` vers `Runtime` : `Tester localement cette release` |
| 4. Push distant sans activation | Envoyer la release vers la cible choisie sans la rendre active | `Déploiement` | `dry-run`, `sync`, `sync + finaliser`, `prepare-release` selon le cas | Release présente côté distant, non encore activée | Le flux existe mais les détails secondaires et techniques concurrencent la lecture principale | Réduire `Déploiement` à `release visée → cible → action principale → résultat` |
| 5. Test distant | Vérifier l’état de la release distante avant bascule | `Déploiement`, `Runtime`, parfois `Releases` | `smoke`, vérifications runtime, diagnostics de layout | Confirmation que la release distante répond correctement | Le parcours n’est pas raconté comme une suite logique unique ; le diagnostic peut apparaître comme une autre logique | Formaliser un prochain pas explicite : `Tester la release distante` puis `Valider le runtime distant` |
| 6. Préparation d’une base compatible | S’assurer que la DB cible est prête avant migration / exposition | `Base de données` | diagnostics, test connexion, backup, lecture de cible | Base cible identifiée, accessible, sauvegardée si nécessaire | La page mélange trop d’objets à la fois et la cible DB n’est pas toujours le premier élément mental | Faire un sous-flux principal `Contexte DB cible → sécurité → action recommandée` |
| 7. Migration schéma / données si nécessaire | Appliquer uniquement ce qui est requis pour rendre la release compatible avec la DB cible | `Base de données` | `Migrer le release`, clonage / restauration selon cas | Schéma et données compatibles | Le lien entre release visé, DB cible et source éventuelle est trop lourd cognitivement | Isoler un bloc `Migration du release vers la DB cible` avec garde-fous renforcés |
| 8. Exposition sur preview / vhost / domaine dédié | Rendre la release accessible dans de bonnes conditions de validation | `Runtime`, `Releases`, `Profils` | installation / diagnostic preview, config front/apache selon cas | URL de test claire et isolée | Le sujet preview/vhost est éclaté entre plusieurs pages et présenté de manière trop technique | Créer une lecture cohérente : contexte global + renvoi explicite vers la page qui porte l’exposition |
| 9. Test réel | Vérifier en conditions proches du réel avant bascule | `Runtime`, `Déploiement`, `Releases` | health, smoke, lecture runtime, preview | Feu vert lisible avant activation | L’outil donne des informations utiles mais pas un “go/no-go” synthétique assez fort | Introduire un état consolidé `Prêt pour activation / Bloqué / À vérifier` |
| 10. Bascule en actif | Activer le release validé | `Releases` | `Activate`, `Activate + smoke` | Le release devient le courant distant | La confirmation protège, mais le rappel de contexte n’est pas encore assez fort juste avant l’action | Renforcer la confirmation avec release source, release cible, environnement et état des diagnostics |
| 11. Rollback simple si nécessaire | Revenir rapidement à un release antérieur en cas d’échec | `Releases` | `Rollback` | Retour à un release précédent clair et sûr | Le concept existe mais la lisibilité du rollback simple versus rollback “qui ne touche pas la DB” doit être plus explicite | Afficher un message produit clair : `Rollback code uniquement` + rappel explicite que la DB n’est pas rollbackée automatiquement |

---

## 3. Cartographie cible du Devtools

Le Devtools doit raconter un **processus global unique** composé de pages spécialisées, sans demander à l’utilisateur de reconstruire lui-même la logique produit à partir de briques techniques.

### 3.1 Récit cible du produit
Le récit cible devrait être :

1. **Je choisis la release et la cible sur lesquelles je travaille** ;
2. **Je construis ou je relis la release locale** ;
3. **Je la pousse à distance sans l’activer** ;
4. **Je vérifie qu’elle fonctionne** ;
5. **Je prépare la base si nécessaire** ;
6. **Je migre explicitement si nécessaire** ;
7. **Je vérifie l’exposition et le runtime** ;
8. **J’active** ;
9. **Je rollback uniquement le code si nécessaire**.

### 3.2 Ce qui doit être visible partout
Doit être visible sur toutes les pages, dans un bandeau global commun :
- release sélectionnée ;
- release actuellement active côté distant ;
- profil actif ;
- cible / environnement ;
- base cible ;
- état global des diagnostics critiques ;
- fraîcheur des données ;
- état du temps réel / socket.

### 3.3 Ce qui doit rester local à une page
Doit rester local à la page concernée :
- les actions de build détaillées ;
- les actions de sync / finalisation ;
- les diagnostics et opérations DB détaillées ;
- les commandes de contrôle runtime ;
- l’édition technique des profils ;
- les outils experts (terminal, logs détaillés, setup structurel).

### 3.4 Ce qui doit être considéré comme contexte global
Le contexte global doit contenir uniquement les éléments qui changent la portée de l’action :
- **sur quoi** j’agis : release ;
- **où** j’agis : environnement / cible / profil ;
- **sur quelle donnée** j’agis : base cible ;
- **dans quel état** je suis : diagnostics, fraîcheur, temps réel.

### 3.5 Ce qui doit être considéré comme action principale
Chaque page doit avoir **une lecture principale**, donc une action principale ou un sous-flux principal :
- `Build` : fabriquer la release ;
- `Déploiement` : pousser la release ;
- `Releases` : activer / rollbacker le code ;
- `Base de données` : sécuriser puis migrer la DB cible ;
- `Profils` : choisir ou éditer l’environnement technique ;
- `Runtime` : vérifier et piloter l’état opérationnel.

### 3.6 Ce qui doit être considéré comme secondaire / expert
Doit être secondaire, replié ou explicitement expert :
- détails JSON bruts ;
- chemins système complets ;
- commandes shell ;
- maintenance structurelle rare ;
- clonage / restauration non standard ;
- terminal intégré ;
- diagnostics avancés non nécessaires à la majorité des parcours.

---

## 4. Bandeau global de contexte opératoire

Le bandeau global doit devenir la pièce maîtresse de sécurité cognitive du Devtools.

### 4.1 Contenu minimal obligatoire
1. **Release sélectionnée**
2. **Release courant distant**
3. **Profil actif**
4. **Environnement / cible**
5. **Base cible**
6. **Fraîcheur des données**
7. **Temps réel / socket**
8. **Blocage critique éventuel**

### 4.2 Ordre recommandé

| Rang | Champ | Rôle | Priorité visuelle |
|---|---|---|---|
| 1 | Release sélectionnée | Contexte d’action principal | très forte |
| 2 | Courant distant | Point de comparaison immédiat | très forte |
| 3 | Environnement / cible | Portée métier de l’opération | très forte |
| 4 | Profil actif | Support technique du ciblage | forte |
| 5 | Base cible | Risque DB associé | forte |
| 6 | Blocage critique | Interdiction ou alerte structurante | forte |
| 7 | Fraîcheur des données | Confiance dans l’affichage | moyenne |
| 8 | Temps réel / socket | Qualité de synchronisation du plan de contrôle | moyenne |

### 4.3 Comportement visuel recommandé
- `Release sélectionnée` et `Courant distant` doivent être côte à côte pour rendre la comparaison instantanée.
- `Environnement / cible` doit être affiché comme un badge très lisible, distinct du simple nom de profil.
- `Profil actif` reste visible mais visuellement moins fort que l’environnement métier.
- `Base cible` doit être un jeton clair de type `DB : ttm_api / stackmod-dev-mariadb` ou équivalent compréhensible.
- `Blocage critique` doit dominer visuellement tout le bandeau lorsqu’il existe.
- `Fraîcheur des données` et `Temps réel / socket` doivent rester lisibles mais plus secondaires.

### 4.4 Champs et formulation recommandés
- **Release sélectionnée** : `Release visée : 20260404-014000`
- **Courant distant** : `Courant distant : 20260403-231500`
- **Environnement / cible** : `Cible : Préprod` ou `Cible : Production`
- **Profil actif** : `Profil technique : default`
- **Base cible** : `DB cible : ttm_api (container stackmod-dev-mariadb)`
- **Fraîcheur** : `Données vérifiées il y a 18 s` ou `Données à rafraîchir`
- **Temps réel** : `Temps réel : connecté`, `Reconnexion…`, `Fallback HTTP`
- **Blocage critique** : `Blocage : release absente côté distant` ou `Blocage : diagnostic Prisma en erreur`

### 4.5 Comportement en cas d’incohérence
En cas d’incohérence, le bandeau doit prioriser l’explication plutôt que la donnée brute.

#### Cas 1 — release sélectionnée absente côté distant
- afficher la release sélectionnée ;
- afficher `courant distant` ;
- ajouter un badge critique `release non présente côté cible` ;
- désactiver les actions d’activation.

#### Cas 2 — profil actif incompatible avec le runtime observé
- afficher un état `contexte contradictoire détecté` ;
- figer les actions sensibles ;
- proposer `Rafraîchir le contexte` puis `Revalider le profil`.

#### Cas 3 — DB cible inconnue ou obsolète
- afficher `DB cible non confirmée` ;
- désactiver les migrations ;
- laisser les diagnostics et tests de connexion accessibles.

#### Cas 4 — temps réel dégradé
- afficher `Reconnexion…` ou `Fallback HTTP` ;
- garder le dernier état utile visible ;
- marquer les données comme potentiellement obsolètes jusqu’à confirmation.

---

## 5. Refonte par page

### 5.1 Build

#### Rôle cible de la page
Fabriquer les artefacts d’une release explicitement choisie et rendre évident si cette release est prête pour le prochain pas.

#### Ce qui doit être mis en avant
- la release visée ;
- les projets ciblés ;
- le statut du dernier build ;
- les actions de build locales ;
- le résultat concret du dernier build.

#### Ce qui doit être secondaire
- chemins techniques ;
- détails internes de manifeste ;
- notes longues sur des règles globales déjà rappelées ailleurs ;
- build distant API si c’est un cas avancé.

#### Ce qu’il faut simplifier
- supprimer les messages concurrents dans la zone haute ;
- éviter toute répétition entre bandeau global, contexte de page et cartes d’action ;
- rendre la sortie lisible comme `release prête` plutôt que comme un log technique uniquement.

#### Ce qu’il faut renommer
- conserver `Build` comme titre ;
- préférer `Release visée`, `Projets ciblés`, `Dernier résultat`, `Release prête localement`.

#### Ce qu’il faut masquer / replier
- détails de snapshot local ;
- chemins complets d’artefacts ;
- messages de sécurité transverses déjà portés par le bandeau global.

#### Ce qu’il faut bloquer strictement
- tout build sans release explicite ;
- tout build si le contexte global est contradictoire ;
- tout build distant si le prérequis distant n’est pas prêt.

#### Ce qu’il faut mieux expliquer
- qu’un build réussi produit une release locale figée ;
- que le prochain pas normal est soit `Tester localement`, soit `Déployer sans activer`.

#### Hiérarchie visuelle recommandée
1. bandeau global ;
2. titre + sous-titre ;
3. ligne compacte `Release / Profil / Projets / État` ;
4. cartes de build locales ;
5. résultat récent ;
6. bloc secondaire `Contexte du build` ;
7. bloc replié `Build distant API`.

#### Prochain pas à afficher en sortie
- si build réussi : `Prochain pas recommandé : tester cette release localement dans Runtime ou la pousser dans Déploiement`.

### 5.2 Déploiement

#### Rôle cible de la page
Pousser une release déjà prête vers la cible choisie, sans confusion avec le build, la DB ou le runtime.

#### Ce qui doit être mis en avant
- release visée ;
- cible / environnement ;
- action principale `push` ;
- finalisation minimale si nécessaire ;
- dernier résultat utile ;
- prochain pas après succès.

#### Ce qui doit être secondaire
- détails de statut CLI ;
- détails de profil ;
- détails runtime ;
- diagnostics avancés ;
- actions séparées rares.

#### Ce qu’il faut simplifier
- recentrer la page sur un seul flux principal ;
- éviter que les détails secondaires noient la lecture `j’envoie quoi, où, avec quel résultat`.

#### Ce qu’il faut renommer
- préférer `Envoyer la release`, `Finalisation distante`, `Résultat du déploiement`, `Suite logique`.

#### Ce qu’il faut masquer / replier
- détails secondaires ;
- actions expertes isolées ;
- contexte technique avancé.

#### Ce qu’il faut bloquer strictement
- activation depuis `Déploiement` ;
- lancement d’un push si la release locale n’est pas prête ;
- action de sync si le contexte cible n’est pas confirmé.

#### Ce qu’il faut mieux expliquer
- que cette page ne rend pas la release active ;
- qu’après push, le prochain pas est `tester`, pas `activer immédiatement`.

#### Hiérarchie visuelle recommandée
1. bandeau global ;
2. titre + sous-titre ;
3. contexte minimal `Release / Cible / État` ;
4. bloc principal `Envoyer la release` ;
5. résultat ;
6. suite logique vers `Database` et `Runtime` ;
7. détails secondaires repliés.

#### Prochain pas à afficher en sortie
- `Release envoyée. Prochain pas recommandé : vérifier le runtime distant puis traiter la base si nécessaire.`

### 5.3 Releases

#### Rôle cible de la page
Gérer la vie d’un release déjà présent côté distant : validation finale, activation et rollback code.

#### Ce qui doit être mis en avant
- release visée ;
- courant distant ;
- différence entre les deux ;
- état de validité avant activation ;
- actions `Activer` et `Rollback`.

#### Ce qui doit être secondaire
- maintenance release ;
- cleanup ;
- preview release ;
- diagnostics détaillés si non nécessaires au moment de décider.

#### Ce qu’il faut simplifier
- faire de la comparaison `visée / courant` le cœur de la page ;
- afficher un verdict synthétique avant activation.

#### Ce qu’il faut renommer
- `Activate` → `Activer ce release` ;
- `Rollback` → `Revenir au release précédent` ;
- `Diagnostiquer le layout release` → `Vérifier la présence du release côté cible`.

#### Ce qu’il faut masquer / replier
- maintenance ;
- cleanup ;
- preview ;
- détails de layout avancés.

#### Ce qu’il faut bloquer strictement
- activer une release absente côté distant ;
- rollback si aucun release de repli clair n’est disponible ;
- activation tant qu’un diagnostic bloquant est présent.

#### Ce qu’il faut mieux expliquer
- que l’activation bascule le code courant ;
- que le rollback ne rollbacke pas automatiquement la DB ;
- que la page intervient après push et validation.

#### Hiérarchie visuelle recommandée
1. bandeau global ;
2. titre + sous-titre ;
3. bloc `Comparaison release visée / courant distant` ;
4. bloc `Prêt pour activation ?` ;
5. actions principales `Activer` / `Rollback` ;
6. résultat ;
7. maintenance secondaire repliée.

#### Prochain pas à afficher en sortie
- après activation réussie : `Prochain pas recommandé : surveiller le runtime et les smoke tests` ;
- après rollback : `Prochain pas recommandé : vérifier le runtime et documenter la raison du retour arrière`.

### 5.4 Base de données

#### Rôle cible de la page
Sécuriser et traiter explicitement la base de données cible, sans ambiguïté entre diagnostic, sauvegarde, migration et clonage.

#### Ce qui doit être mis en avant
- DB cible ;
- release visée pour la migration ;
- diagnostic DB ;
- backup préalable ;
- action principale recommandée selon le cas.

#### Ce qui doit être secondaire
- setup one-shot ;
- clonage expert ;
- restauration avancée ;
- notes techniques longues ;
- maintenance héritée.

#### Ce qu’il faut simplifier
- découper la page en sous-flux lisibles ;
- éviter qu’un utilisateur voie simultanément trop de sources, de cibles, de conteneurs, d’artefacts et de notes.

#### Ce qu’il faut renommer
- `Pilotage DB explicite` → `Décision base de données` ;
- `Clonage DB vers cible non-prod` → `Préparer une base non-prod` ;
- `Contexte technique réel d’accès DB` → `Contexte DB`.

#### Ce qu’il faut masquer / replier
- maintenance / héritage ;
- détails d’artefact d’export ;
- setup rare ;
- lecture très technique de conteneur / writer context si non nécessaire.

#### Ce qu’il faut bloquer strictement
- toute migration si la DB cible n’est pas confirmée ;
- toute restauration si l’artefact source n’existe pas ;
- toute action destructive si la cible est ambiguë ;
- toute migration si le release visé n’est pas identifié.

#### Ce qu’il faut mieux expliquer
- différence entre diagnostic, backup, migration, clonage et restauration ;
- différence entre DB source et DB cible ;
- lien entre release visé et migration exécutée.

#### Hiérarchie visuelle recommandée
1. bandeau global ;
2. titre + sous-titre ;
3. bloc `Contexte DB cible` ;
4. bloc `Diagnostic et sécurité` ;
5. bloc principal `Action recommandée` ;
6. résultat ;
7. bloc secondaire `Préparer une base non-prod` ;
8. mode expert replié.

#### Prochain pas à afficher en sortie
- `Base prête. Prochain pas recommandé : vérifier le runtime distant puis poursuivre vers activation si tout est vert.`

### 5.5 Profils

#### Rôle cible de la page
Servir de brique `Env` ou `Environnement`, c’est-à-dire expliquer et éditer l’environnement courant, pas seulement exposer un énorme formulaire technique.

#### Ce qui doit être mis en avant
- environnement courant ;
- profil technique utilisé ;
- différence entre configuration versionnée et surcharge locale ;
- actions de sélection, duplication et édition.

#### Ce qui doit être secondaire
- JSON expert ;
- tous les détails techniques avancés ;
- champs rares ;
- réglages internes trop fins.

#### Ce qu’il faut simplifier
- introduire une lecture métier avant la lecture technique ;
- commencer par `sur quel environnement je travaille` puis seulement `comment il est configuré`.

#### Ce qu’il faut renommer
- idéalement, dans le récit produit, `Profils` devient `Env` ou `Environnements` ;
- `Actif fichier` → `Profil versionné actif` ;
- `Runtime effectif` → `Profil réellement utilisé au runtime`.

#### Ce qu’il faut masquer / replier
- sections avancées ;
- mode expert JSON ;
- champs peu utilisés ;
- détails front/apache/db tant que l’utilisateur n’a pas choisi de les éditer.

#### Ce qu’il faut bloquer strictement
- suppression de surcharge sans rappel de conséquence ;
- changement de profil pendant une action sensible en cours.

#### Ce qu’il faut mieux expliquer
- différence entre environnement produit et profil technique ;
- portée d’un changement de profil ;
- différence entre versionné et local override.

#### Hiérarchie visuelle recommandée
1. bandeau global ;
2. titre + sous-titre ;
3. bloc `Environnement courant` ;
4. actions `Choisir / Dupliquer / Créer` ;
5. formulaire guidé section par section ;
6. mode expert replié.

#### Prochain pas à afficher en sortie
- `Profil mis à jour. Prochain pas recommandé : recharger le contexte global puis revenir au pipeline Build / Déploiement / Database / Runtime.`

### 5.6 Runtime

#### Rôle cible de la page
Contrôler et diagnostiquer l’état opérationnel local et distant une fois que la release et la cible sont déjà connues.

#### Ce qui doit être mis en avant
- distinction local / distant ;
- état de chaque service ;
- actions normales `vérifier`, `start`, `stop`, `restart` ;
- dernier état utile ;
- état temps réel.

#### Ce qui doit être secondaire
- terminal intégré ;
- logs détaillés ;
- maintenance avancée ;
- setup runtime structurel.

#### Ce qu’il faut simplifier
- faire de `contrôler l’état` la lecture principale ;
- éviter que le terminal devienne le centre de gravité de la page.

#### Ce qu’il faut renommer
- `Pilotage runtime normal` peut rester ;
- `Détails runtime utiles` peut devenir `État détaillé` ;
- `Console / logs / terminal` peut devenir `Investigation avancée`.

#### Ce qu’il faut masquer / replier
- terminal ;
- logs longs ;
- maintenance avancée ;
- diagnostics de correction structurelle rares.

#### Ce qu’il faut bloquer strictement
- arrêt / restart sur cible ambiguë ;
- start distant si le profil n’est pas cohérent ;
- actions concurrentes sur le même service pendant un état `En cours`.

#### Ce qu’il faut mieux expliquer
- différence entre socle local et couche distante ;
- statut réel du temps réel ;
- portée exacte des actions distantes.

#### Hiérarchie visuelle recommandée
1. bandeau global ;
2. titre + sous-titre ;
3. contexte runtime compact ;
4. cartes locales ;
5. cartes distantes ;
6. état détaillé ;
7. investigation avancée repliée.

#### Prochain pas à afficher en sortie
- `Runtime vérifié. Prochain pas recommandé : si tout est vert, revenir à Releases pour activer ou confirmer la mise en service.`

---

## 6. Page Base de données : refonte détaillée

La page `Base de données` est la page la plus sensible car elle concentre la plus forte densité de risque métier et de charge cognitive.

### 6.1 Principe directeur
La page ne doit plus être lue comme une grande page technique de capacités DB. Elle doit être lue comme une **suite de décisions contrôlées**.

### 6.2 Séparation cible des sous-flux

#### A. Diagnostic
Objectif : répondre à `la cible DB est-elle lisible, joignable et suffisamment qualifiée pour décider ?`

Doit contenir :
- DB cible ;
- mode d’accès ;
- état diagnostic ;
- dernières vérifications ;
- remédiation courte.

#### B. Backup
Objectif : répondre à `la sécurité minimale avant action sensible est-elle assurée ?`

Doit contenir :
- dernier backup connu ;
- timestamp ;
- cible concernée ;
- bouton de backup ;
- avertissement si backup absent ou ancien.

#### C. Migration
Objectif : répondre à `quel release migre quelle DB cible ?`

Doit contenir :
- release visé ;
- DB cible ;
- diagnostic Prisma / compatibilité ;
- bouton de migration ;
- blocage si contexte incomplet.

#### D. Clonage / préparation non-prod
Objectif : répondre à `comment préparer une base de test cohérente sans toucher la prod ?`

Doit contenir :
- DB source ;
- artefact source ;
- DB cible ;
- bouton de restauration / préparation ;
- règles non-prod explicites.

#### E. Restauration / expert
Objectif : réserver les opérations rares et potentiellement risquées à un niveau expert explicite.

Doit contenir :
- opérations rares ;
- setup additionnel ;
- détails d’artefacts ;
- commandes techniques ;
- maintenance héritée.

### 6.3 Ce qui doit rester dans la page principale
Doit rester au premier niveau :
1. contexte DB cible ;
2. diagnostic ;
3. backup ;
4. migration si applicable ;
5. résultat récent ;
6. prochain pas.

### 6.4 Ce qui doit passer en mode expert
Doit passer en mode expert ou en bloc replié :
- clonage détaillé multi-source ;
- restauration avancée ;
- setup one-shot ;
- détails d’artefacts et chemins ;
- maintenance historique ;
- diagnostic très technique de conteneur ou writer context.

### 6.5 Affichage sans ambiguïté des objets critiques

| Objet | Formulation recommandée | Règle UX |
|---|---|---|
| Release visé | `Release visé pour migration : 20260404-014000` | toujours visible dans le bloc migration |
| Release source | `Release source de l’artefact : non applicable / inconnu / <nom>` | ne jamais confondre avec le release visé |
| Release migré | `Migration appliquée pour : 20260404-014000` | affiché en sortie après succès |
| DB source | `DB source : v2` ou `DB source : production exportée` | uniquement dans le sous-flux clonage / restauration |
| DB cible | `DB cible : ttm_api (préprod)` | visible partout dans la page principale |

### 6.6 Règles pour éviter la confusion cognitive
- ne jamais afficher `source` et `cible` sans libellé explicite ;
- ne jamais afficher `release`, `DB` et `artefact` dans la même ligne sans préfixe ;
- ne jamais laisser visible une action destructive si la cible n’est pas formellement déterminée ;
- utiliser une couleur et une hiérarchie différentes pour `diagnostic`, `sécurité`, `action`, `résultat` ;
- faire précéder chaque action sensible d’un résumé court : `Vous allez migrer le release X sur la DB Y de la cible Z`.

### 6.7 Structure recommandée de la page DB
1. bandeau global ;
2. titre + sous-titre ;
3. bloc `Contexte DB cible` ;
4. bloc `Diagnostic` ;
5. bloc `Sécurité / Backup` ;
6. bloc `Migration du release` ;
7. bloc `Résultat récent` ;
8. bloc `Préparer une base non-prod` ;
9. bloc `Mode expert` replié.

---

## 7. États, feedbacks et fraîcheur des données

Le Devtools doit adopter un modèle transversal unique pour les états, compatible avec les règles déjà posées sur les chargements explicites.

| Cas | Texte conseillé | Sévérité | Comportement visuel recommandé |
|---|---|---|---|
| Loading initial | `Chargement…` | neutre | état au niveau page, contenu principal atténué, titres visibles |
| Refresh local | `Mise à jour…` | neutre | état au niveau bloc, dernier état utile conservé |
| Action en cours | `En cours` ou `Lancement…` | informative | état au niveau carte ou bouton, bouton déclencheur désactivé |
| Succès | `Action terminée avec succès` | positive | badge vert + résumé court + sortie détaillée repliable |
| Erreur | `Action échouée` | forte | badge rouge + message lisible + remédiation courte |
| Diagnostic bloquant | `Blocage détecté` | critique | bannière ou badge critique, action sensible désactivée |
| Diagnostic conseillé | `À vérifier` | moyenne | badge ambre, action possible mais non prioritaire |
| Données potentiellement obsolètes | `Données à rafraîchir` | moyenne | badge neutre/ambre, pas rouge tant qu’il ne s’agit pas d’une erreur |
| Reconnexion temps réel | `Reconnexion… Le dernier état connu reste affiché.` | informative | badge bleu/ambre, dernier état utile conservé |
| État contradictoire détecté | `Contexte contradictoire détecté` | critique | bannière critique, actions sensibles gelées, CTA `Rafraîchir le contexte` |

### 7.1 Règles transverses
- aucun chargement silencieux ;
- aucun spinner seul sans texte ;
- aucun changement brutal de valeur sans état intermédiaire ;
- le dernier état utile doit rester visible pendant l’attente ;
- l’utilisateur doit savoir si l’information est fraîche, partielle ou potentiellement obsolète.

### 7.2 Traduction concrète des observations réelles
Les observations réelles confirment le besoin de ce modèle :
- sur `Runtime`, après l’arrêt du front local, la page a affiché un état de reconnexion et de fallback ; c’est utile, mais cela doit être systématisé et mieux relié à la fraîcheur des autres données ;
- sur `Build`, un message de blocage incohérent est resté visible malgré un build réussi ; cela confirme qu’un état doit toujours dépendre d’une source de vérité claire ;
- sur plusieurs pages, la modale de suivi donne un très bon feedback d’exécution, mais la page de fond doit ensuite relire l’état avec la même cohérence.

---

## 8. Garde-fous et sécurité cognitive

### 8.1 Actions à désactiver strictement
Doivent être désactivées sans exception quand le contexte est incomplet ou bloqué :
- activer une release absente côté distant ;
- rollbacker sans release de repli identifié ;
- migrer une DB cible non confirmée ;
- restaurer sans artefact source existant ;
- lancer un build sans release explicite ;
- démarrer / arrêter un runtime distant quand le profil ou la cible sont contradictoires ;
- relancer la même action pendant qu’elle est déjà `En cours`.

### 8.2 Actions pouvant rester accessibles avec warning
Peuvent rester accessibles avec avertissement clair :
- diagnostics ;
- test connexion DB ;
- vérification runtime ;
- smoke tests ;
- lecture de contexte ;
- ouverture des détails experts.

### 8.3 Confirmations à renforcer
Doivent être renforcées avec rappel de contexte complet :
- `Activer ce release` ;
- `Revenir au release précédent` ;
- `Migrer le release` ;
- `Restaurer une DB cible` ;
- `Arrêter un service distant` ;
- suppression ou changement sensible de profil / surcharge.

### 8.4 Contexte à rappeler juste avant validation
Avant confirmation d’une action sensible, rappeler au minimum :
- release visé ;
- courant distant actuel ;
- environnement / cible ;
- profil actif ;
- DB cible si la DB est concernée ;
- présence d’un blocage critique ou d’un diagnostic non levé.

### 8.5 Forme recommandée des confirmations sensibles
Format conseillé :
1. **Titre** : action claire ;
2. **Résumé** : phrase complète ;
3. **Contexte** : liste `release / cible / DB / profil` ;
4. **Conséquence** : ce que l’action va réellement modifier ;
5. **Blocages éventuels** ;
6. **CTA primaire** explicite, jamais générique.

Exemple :
- Titre : `Confirmer la migration DB`
- Résumé : `Vous allez migrer le release 20260404-014000 sur la DB ttm_api de la cible Préprod.`
- Conséquence : `Cette action modifie le schéma et potentiellement les données de la base cible.`

---

## 9. Plan d’implémentation

### 9.1 Quick wins

| Chantier | Bénéfice | Complexité | Priorité |
|---|---|---|---|
| Unifier le bandeau global de contexte sur toutes les pages | Réduit immédiatement le risque d’erreur de cible | moyenne | très haute |
| Corriger les feedbacks contradaires de `Build` | Supprime une incohérence critique observée en réel | faible | très haute |
| Renforcer les confirmations avec `release / cible / DB / profil` | Sécurise les actions sensibles sans refonte lourde | faible | très haute |
| Replier par défaut les blocs experts sur `Runtime` et `Database` | Réduit la charge mentale immédiatement | faible | haute |
| Ajouter un bloc `Prochain pas recommandé` en sortie des actions principales | Raconte enfin le pipeline de manière opérationnelle | faible | haute |
| Normaliser les libellés d’état (`Chargement…`, `Mise à jour…`, `En cours`, `Blocage détecté`) | Améliore la cohérence transverse | faible | haute |

### 9.2 Refactor UX moyen terme

| Chantier | Bénéfice | Complexité | Priorité |
|---|---|---|---|
| Recentrer `Déploiement` sur un flux principal unique | Rend la page immédiatement compréhensible | moyenne | très haute |
| Recomposer `Base de données` en sous-flux `Diagnostic / Backup / Migration / Préparation non-prod / Expert` | Réduit fortement le risque cognitif et opérationnel | élevée | très haute |
| Repositionner `Profils` comme page `Env` ou `Environnements` dans le récit produit | Simplifie la compréhension globale du Devtools | moyenne | haute |
| Recomposer `Releases` autour de `visée vs courant` puis `activation / rollback` | Clarifie la bascule finale et le rollback code | moyenne | haute |
| Structurer `Runtime` autour des actions normales et reléguer l’investigation avancée | Clarifie le rôle de la page | moyenne | haute |

### 9.3 Évolutions structurantes

| Chantier | Bénéfice | Complexité | Priorité |
|---|---|---|---|
| Introduire un état consolidé global `Prêt / À vérifier / Bloqué` pour la promotion du release | Donne une lecture produit synthétique très forte | élevée | haute |
| Faire converger toutes les pages vers un modèle commun de fraîcheur de données et de source de vérité | Supprime les doutes sur la fiabilité des états | élevée | haute |
| Formaliser le concept produit `Pipeline de promotion` dans l’UI avec étapes et renvois explicites | Transforme le Devtools en vrai cockpit de promotion | élevée | haute |
| Distinguer explicitement `preview légère` et `validation complète` dans le récit produit | Réduit les mauvaises interprétations des validations possibles | moyenne | moyenne |
| Séparer plus clairement la lecture métier et la lecture experte sur toutes les pages | Rend l’outil plus robuste pour un usage quotidien | élevée | moyenne |

---

## 10. Conclusion opérationnelle

Le Devtools a déjà une base solide : les pages sont séparées, les diagnostics existent, les confirmations sensibles existent, les modales de suivi sont utiles et le système permet déjà de piloter une partie importante du cycle réel. Le problème principal n’est pas un manque de capacités. Le problème principal est que le **récit opératoire** n’est pas encore assez explicite, stable et hiérarchisé.

Le nouveau récit cible doit être simple :

- je choisis ma release et ma cible ;
- je fabrique ma release ;
- je la teste ;
- je la pousse ;
- je prépare la base si nécessaire ;
- je vérifie le runtime et l’exposition ;
- j’active ;
- je rollbacke le code si nécessaire.

Chaque page doit soutenir ce récit avec un rôle clair, un contexte global partagé, une action principale visible, des détails experts relégués et un prochain pas explicite. La page `Base de données` doit recevoir le plus gros effort de clarification, car c’est là que le risque cognitif et opérationnel est le plus fort.

### Top 10 des changements les plus rentables
1. unifier le bandeau global de contexte opératoire ;
2. corriger toutes les incohérences d’état visibles après action ;
3. recentrer `Déploiement` sur `release → cible → push → résultat` ;
4. restructurer `Base de données` en sous-flux lisibles ;
5. renforcer les confirmations sensibles avec rappel complet du contexte ;
6. rendre explicite le `prochain pas recommandé` sur chaque page ;
7. clarifier la comparaison `release visée / courant distant` sur `Releases` ;
8. reléguer les outils experts derrière des blocs repliés ;
9. repositionner `Profils` comme brique `Env` lisible ;
10. normaliser le modèle de fraîcheur, reconnexion et obsolescence des données.

### Ordre recommandé de mise en œuvre
1. **Sécuriser d’abord** : bandeau global, confirmations renforcées, désactivation stricte des actions sensibles incohérentes.
2. **Clarifier ensuite** : `Déploiement`, `Releases`, `Runtime`, libellés d’état, prochains pas recommandés.
3. **Refondre ensuite la page la plus risquée** : `Base de données`.
4. **Stabiliser enfin le récit produit global** : `Profils` vers `Env`, état consolidé de promotion, lecture pipeline transverse.

En résumé, la meilleure suite n’est pas d’ajouter des capacités. C’est de **rendre le Devtools plus lisible, plus fiable et plus narratif**, pour qu’un utilisateur comprenne toujours sur quoi il agit, dans quel ordre, avec quel risque et avec quel prochain pas.