# Devtools — spécification UI frontend > 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`. > > Cette spécification reflète un cadrage UI antérieur à l’extraction du `dev-tools` vers `ttm-dev-tools`. À utiliser seulement comme contexte d’archive. _Date : 2026-04-06_ ## 1. Structure globale de chaque page Règle commune à toutes les pages : 1. `Bandeau global` 2. `Pipeline de promotion` 3. `En-tête de page` 4. `Bloc principal métier` 5. `Bloc résultat courant` 6. `Bloc Prochain pas recommandé` 7. `Blocs secondaires` 8. `Blocs experts repliés` --- ### 1.1 Page `Build` | Ordre | Nom exact du bloc | Rôle | Priorité visuelle | |---|---|---|---| | 1 | `Bandeau global` | afficher le contexte opératoire commun | primaire | | 2 | `Pipeline de promotion` | afficher l’avancement transverse | primaire | | 3 | `Build` | afficher le titre et le sous-titre | primaire | | 4 | `Contexte du build` | afficher `Release`, `Profil`, `Projets`, `État build` | primaire | | 5 | `Builds locaux` | afficher les cartes d’actions `Build complet`, `Build shared`, `Build API`, `Build front` | primaire | | 6 | `Dernier résultat de build` | afficher le dernier résultat exploitable du build courant | primaire | | 7 | `Build distant API` | afficher l’action distante spécifique si disponible | secondaire | | 8 | `Détails du build` | afficher snapshots, chemins et détails techniques | expert | | 9 | `Prochain pas recommandé` | afficher l’action suivante | primaire | #### En-tête de page `Build` - Titre exact : `Build` - Sous-titre exact : `Fabrique les artefacts pour la release sélectionnée.` --- ### 1.2 Page `Déploiement` | Ordre | Nom exact du bloc | Rôle | Priorité visuelle | |---|---|---|---| | 1 | `Bandeau global` | afficher le contexte opératoire commun | primaire | | 2 | `Pipeline de promotion` | afficher l’avancement transverse | primaire | | 3 | `Déploiement` | afficher le titre et le sous-titre | primaire | | 4 | `Contexte de déploiement` | afficher `Release`, `Cible`, `Profil`, `État distant` | primaire | | 5 | `Envoyer la release` | afficher le flux principal d’envoi | primaire | | 6 | `Dernier résultat de déploiement` | afficher le résultat du dernier envoi ou de la dernière finalisation | primaire | | 7 | `Suite logique` | afficher les renvois courts vers `Runtime` et `Base de données` | secondaire | | 8 | `Actions avancées de déploiement` | afficher `Sync seul`, `Finaliser seul`, détails techniques | expert | | 9 | `Prochain pas recommandé` | afficher l’action suivante | primaire | #### En-tête de page `Déploiement` - Titre exact : `Déploiement` - Sous-titre exact : `Pousse une release déjà prête vers la cible configurée.` --- ### 1.3 Page `Runtime` | Ordre | Nom exact du bloc | Rôle | Priorité visuelle | |---|---|---|---| | 1 | `Bandeau global` | afficher le contexte opératoire commun | primaire | | 2 | `Pipeline de promotion` | afficher l’avancement transverse | primaire | | 3 | `Runtime` | afficher le titre et le sous-titre | primaire | | 4 | `Contexte runtime` | afficher `Cible runtime`, `Socle local`, `Couche distante`, `État` | primaire | | 5 | `Pilotage runtime` | afficher les cartes services locales et distantes avec actions normales | primaire | | 6 | `État détaillé runtime` | afficher health, endpoints, PID, dernière vérification, raison lisible | secondaire | | 7 | `Investigation avancée` | afficher logs, console, terminal | secondaire | | 8 | `Maintenance runtime avancée` | afficher setup, vhost, proxy, correction structurelle | expert | | 9 | `Prochain pas recommandé` | afficher l’action suivante | primaire | #### En-tête de page `Runtime` - Titre exact : `Runtime` - Sous-titre exact : `Contrôle et validation opérationnelle de la cible courante.` --- ### 1.4 Page `Base de données` | Ordre | Nom exact du bloc | Rôle | Priorité visuelle | |---|---|---|---| | 1 | `Bandeau global` | afficher le contexte opératoire commun | primaire | | 2 | `Pipeline de promotion` | afficher l’avancement transverse | primaire | | 3 | `Base de données` | afficher le titre et le sous-titre | primaire | | 4 | `Contexte DB cible` | afficher `DB cible`, `Release visée`, `Active distante`, `Release de migration` | primaire | | 5 | `Diagnostic DB` | afficher la lisibilité et la qualification de la DB cible | primaire | | 6 | `Sécurité / Backup` | afficher le statut de sauvegarde et l’action de backup | primaire | | 7 | `Migration du release` | afficher la migration normale du release vers la DB cible | primaire | | 8 | `Dernier résultat DB` | afficher le dernier résultat exploitable | primaire | | 9 | `Préparer une base non-prod` | afficher le sous-flux simplifié de clonage | secondaire | | 10 | `Mode expert DB` | afficher restauration, artefacts, setup, maintenance | expert | | 11 | `Prochain pas recommandé` | afficher l’action suivante | primaire | #### En-tête de page `Base de données` - Titre exact : `Base de données` - Sous-titre exact : `Prépare et sécurise la base cible pour la release en cours.` --- ### 1.5 Page `Releases` | Ordre | Nom exact du bloc | Rôle | Priorité visuelle | |---|---|---|---| | 1 | `Bandeau global` | afficher le contexte opératoire commun | primaire | | 2 | `Pipeline de promotion` | afficher l’avancement transverse | primaire | | 3 | `Releases` | afficher le titre et le sous-titre | primaire | | 4 | `Release ciblée` | afficher la comparaison `Release visée / Active distante` | primaire | | 5 | `Bascule du release` | afficher `Activer ce release` et `Revenir au release précédent` | primaire | | 6 | `Vérification d’activation` | afficher le verdict d’activabilité et le diagnostic compact | primaire | | 7 | `Dernier résultat de bascule` | afficher le résultat de la dernière activation ou du dernier rollback | primaire | | 8 | `Maintenance release` | afficher `Activer + smoke`, `Nettoyer les anciens releases`, preview release | secondaire | | 9 | `Détails techniques release` | afficher manifestes, chemins, détails CLI | expert | | 10 | `Prochain pas recommandé` | afficher l’action suivante | primaire | #### En-tête de page `Releases` - Titre exact : `Releases` - Sous-titre exact : `Activation et rollback du release ciblé.` --- ### 1.6 Page `Env` | Ordre | Nom exact du bloc | Rôle | Priorité visuelle | |---|---|---|---| | 1 | `Bandeau global` | afficher le contexte opératoire commun | primaire | | 2 | `Pipeline de promotion` | afficher l’avancement transverse | secondaire | | 3 | `Env` | afficher le titre et le sous-titre | primaire | | 4 | `Environnement courant` | afficher `Cible`, `Profil actif`, `Couche`, `URLs publiques` | primaire | | 5 | `Actions d’environnement` | afficher `Ouvrir`, `Créer`, `Dupliquer`, `Enregistrer`, `Activer cet environnement` | primaire | | 6 | `Configuration guidée` | afficher les champs essentiels d’édition | primaire | | 7 | `Configuration avancée` | afficher sections techniques repliables | secondaire | | 8 | `Mode expert JSON` | afficher l’édition JSON brute | expert | | 9 | `Prochain pas recommandé` | afficher le retour vers le pipeline | primaire | #### En-tête de page `Env` - Titre exact : `Env` - Sous-titre exact : `Cible et configuration de la promotion en cours.` --- ## 2. Bandeau global (UI concrète) ### 2.1 Contenu exact affiché Le bandeau global affiche toujours deux lignes. #### Ligne 1 — contexte critique 1. `Release visée : {releaseName}` 2. `Active distante : {remoteCurrentRelease}` 3. `Cible : {environmentLabel}` 4. `Blocage : {blockingReason}` uniquement si blocage présent #### Ligne 2 — contexte de support 1. `Profil : {activeProfile}` 2. `DB cible : {databaseLabel}` 3. `État : {freshnessLabel}` 4. `Temps réel : {realtimeLabel}` ### 2.2 Ordre visuel Ordre visuel fixe de gauche à droite : #### Ligne 1 `Release visée` → `Active distante` → `Cible` → `Blocage` #### Ligne 2 `Profil` → `DB cible` → `État` → `Temps réel` ### 2.3 Format texte exact Exemples exacts autorisés : - `Release visée : 20260404-014000` - `Active distante : 20260403-231500` - `Cible : Préprod` - `Profil : default` - `DB cible : ttm_api / stackmod-dev-mariadb` - `État : vérifié il y a 18 s` - `État : données à rafraîchir` - `Temps réel : connecté` - `Temps réel : reconnexion…` - `Temps réel : fallback HTTP` - `Blocage : release absente côté distant` - `Blocage : DB cible non confirmée` ### 2.4 États possibles | État | Couleur | Règle | |---|---|---| | normal | neutre + accents verts légers | aucun blocage, état frais ou acceptable | | warning | ambre | donnée obsolète, reconnexion, vérification requise | | critique | rouge | incohérence, blocage d’action sensible, cible invalide | ### 2.5 Comportement si incohérence En cas d’incohérence : - le champ concerné passe en rouge ; - le champ `Blocage` devient visible ; - les actions sensibles de la page passent en état désactivé ; - le pipeline marque les étapes dépendantes en `Bloqué`. #### Incohérences gérées - release visée absente côté distant ; - DB cible non confirmée ; - profil incohérent avec runtime ; - cible inconnue ; - état contradictoire entre page et système. ### 2.6 Comportement si reconnexion Quand la connexion temps réel est dégradée : - le champ affiche `Temps réel : reconnexion…` ; - si fallback HTTP actif, il affiche `Temps réel : fallback HTTP` ; - le dernier état utile reste visible partout ; - le champ `État` bascule en `État : données à rafraîchir` si la fraîcheur n’est plus garantie ; - les actions non destructives restent actives ; - les actions sensibles restent actives uniquement si le contexte critique reste frais. --- ## 3. Pipeline UI (affichage précis) ### 3.1 Représentation visuelle Le pipeline est un rail horizontal sticky sous le bandeau global. Ordre exact des étapes : 1. `Build` 2. `Test local` 3. `Push distant` 4. `Validation distante` 5. `Base` 6. `Preview` 7. `Activation` Format de chaque étape : - ligne 1 : nom de l’étape ; - ligne 2 : badge de statut ; - ligne 3 : preuve courte ou blocage court. ### 3.2 États possibles par étape États uniques autorisés : - `Non commencé` - `En cours` - `Prêt` - `Bloqué` - `Obsolète` - `Non requis` ### 3.3 Microcopy exacte | Statut | Texte exact | Couleur | Affichage | |---|---|---|---| | Non commencé | `Non commencé` | neutre | badge gris | | En cours | `En cours` | bleu | badge bleu | | Prêt | `Prêt` | vert | badge vert | | Bloqué | `Bloqué` | rouge | badge rouge | | Obsolète | `Obsolète` | ambre | badge ambre | | Non requis | `Non requis` | neutre atténué | badge gris atténué | ### 3.4 Preuve courte / blocage court La ligne 3 affiche une seule phrase courte. Exemples exacts : - `Build effectué` - `Front local vérifié` - `Release envoyée` - `Runtime distant vérifié` - `Backup disponible` - `Preview non installée` - `DB cible non confirmée` - `Release absente côté distant` - `Étape invalidée par changement de cible` ### 3.5 Exemple concret d’affichage réel ```text [Build] Prêt Build effectué [Test local] Prêt Front local vérifié [Push distant] Prêt Release envoyée [Validation distante] Prêt Runtime distant vérifié [Base] Prêt Backup disponible [Preview] Non requis Aucune preview requise [Activation] Prêt Release activable ``` ### 3.6 Règle sticky Le pipeline est sticky sur desktop. Sur petit écran, il devient un rail horizontal scrollable. Il reste toujours visible sur les pages `Build`, `Déploiement`, `Runtime`, `Base de données`, `Releases`, `Env`. --- ## 4. Bloc “Prochain pas recommandé” ### 4.1 Format exact Le bloc a toujours la même structure. #### Titre fixe `Prochain pas recommandé` #### Ligne principale `Action recommandée : {nextActionLabel}` #### Ligne secondaire `Pourquoi : {nextActionReason}` #### CTA principal `Aller à {targetPageOrAction}` ### 4.2 Règles d’affichage - le bloc est toujours visible en bas de la page ; - il n’affiche qu’une seule recommandation ; - la recommandation est calculée à partir du pipeline courant ; - s’il existe un blocage, la recommandation pointe vers sa résolution ; - si aucun blocage n’existe, la recommandation pointe vers l’étape suivante du pipeline. ### 4.3 Cas non bloqué Format : - `Action recommandée : tester cette release localement` - `Pourquoi : le build est prêt et aucune validation locale n’a encore été enregistrée.` - CTA : `Aller à Runtime` ### 4.4 Cas bloqué Format : - `Action recommandée : confirmer la DB cible` - `Pourquoi : la migration est bloquée tant que la base cible n’est pas qualifiée.` - CTA : `Aller à Base de données` ### 4.5 Exemples concrets #### Exemple Build prêt - `Action recommandée : tester cette release localement` - `Pourquoi : le build est prêt pour la release 20260404-014000.` - CTA : `Aller à Runtime` #### Exemple Push fait, DB bloquée - `Action recommandée : qualifier la base cible` - `Pourquoi : l’activation est bloquée par un état DB incomplet.` - CTA : `Aller à Base de données` --- ## 5. Page Base de données (ULTRA PRÉCISE) ### 5.1 Version simple — ordre exact des blocs 1. `Bandeau global` 2. `Pipeline de promotion` 3. `Base de données` 4. `Contexte DB cible` 5. `Diagnostic DB` 6. `Sécurité / Backup` 7. `Migration du release` 8. `Dernier résultat DB` 9. `Préparer une base non-prod` 10. `Prochain pas recommandé` 11. `Mode expert DB` ### 5.2 Version expert — contenu exact Le bloc `Mode expert DB` contient exactement ces sous-blocs, dans cet ordre : 1. `Clonage avancé` 2. `Restauration DB` 3. `Artefacts d’export` 4. `Setup DB` 5. `Maintenance DB` Ce bloc est replié par défaut. ### 5.3 Labels exacts de la page simple #### Bloc `Contexte DB cible` - `Release visée : {releaseName}` - `Active distante : {remoteCurrentRelease}` - `Release de migration : {migrationRelease}` - `DB cible : {databaseTarget}` #### Bloc `Diagnostic DB` - titre : `Diagnostic DB` - résumé : `La base cible est prête à être utilisée.` ou `La base cible doit être qualifiée avant action.` - champs : - `Connexion : OK` / `Connexion : échec` - `Prisma : OK` / `Prisma : bloqué` - `Dernière vérification : il y a 18 s` #### Bloc `Sécurité / Backup` - titre : `Sécurité / Backup` - résumé : `Un backup récent est disponible.` ou `Aucun backup récent disponible.` - champs : - `Dernier backup : 2026-04-06 17:44:59` - `Cible du backup : ttm_api` - bouton principal du bloc : `Créer un backup` #### Bloc `Migration du release` - titre : `Migration du release` - résumé : `La migration applique le release sélectionné sur la DB cible.` - champs : - `Release migré : {migrationRelease}` - `DB cible : {databaseTarget}` - `État migration : Prêt` / `Bloqué` - bouton principal du bloc : `Migrer le release` #### Bloc `Dernier résultat DB` - titre : `Dernier résultat DB` - contenu : badge d’état + résumé + détails repliables. #### Bloc `Préparer une base non-prod` - titre : `Préparer une base non-prod` - champs : - `DB source : {databaseSource}` - `Artefact source : {artifactSource}` - `DB cible : {databaseTarget}` - bouton principal du bloc : `Préparer la base non-prod` ### 5.4 Séparation visuelle claire Règles obligatoires : - `Diagnostic DB`, `Sécurité / Backup` et `Migration du release` sont trois cartes distinctes ; - `Préparer une base non-prod` est séparé visuellement par un fond secondaire ; - `Mode expert DB` est dans un accordéon fermé par défaut ; - chaque bloc porte son propre badge d’état ; - aucun champ `source` ou `cible` n’est affiché sans préfixe explicite. ### 5.5 Exemples d’affichage réel #### Exemple simple — DB prête ```text Base de données Prépare et sécurise la base cible pour la release en cours. Contexte DB cible Release visée : 20260404-014000 Active distante : 20260403-231500 Release de migration : 20260404-014000 DB cible : ttm_api / stackmod-dev-mariadb Diagnostic DB Prêt Connexion : OK Prisma : OK Dernière vérification : il y a 18 s Sécurité / Backup Prêt Dernier backup : 2026-04-06 17:44:59 Cible du backup : ttm_api [Créer un backup] Migration du release Prêt Release migré : 20260404-014000 DB cible : ttm_api / stackmod-dev-mariadb [Migrer le release] ``` #### Exemple simple — DB bloquée ```text Base de données Prépare et sécurise la base cible pour la release en cours. Contexte DB cible Release visée : 20260404-014000 Active distante : 20260403-231500 Release de migration : 20260404-014000 DB cible : non confirmée Diagnostic DB Bloqué Connexion : OK Prisma : bloqué Dernière vérification : il y a 12 s Remédiation : relancer prepare-release sans skip-install. Sécurité / Backup Warning Aucun backup récent disponible. [Créer un backup] Migration du release Bloqué Release migré : 20260404-014000 DB cible : non confirmée [Migrer le release] (désactivé) ``` --- ## 6. Boutons et actions ### 6.1 Page `Build` - bouton principal unique : `Build complet` - boutons secondaires : `Build shared`, `Build API`, `Build front`, `Utiliser dernier local`, `Utiliser current distant` - boutons experts : `Build API distant`, `Rafraîchir` - désactivation : - `Build complet` désactivé si release vide, contexte contradictoire ou action en cours - `Build API distant` désactivé si prérequis distant absent ### 6.2 Page `Déploiement` - bouton principal unique : `Envoyer la release` - boutons secondaires : `Vérifier avant envoi`, `Envoyer + finaliser` - boutons experts : `Sync seul`, `Finaliser seul`, `Voir le détail technique` - désactivation : - bouton principal désactivé si release locale non prête, cible non confirmée, dry-run bloquant ou action en cours ### 6.3 Page `Runtime` - bouton principal unique : `Vérifier` - boutons secondaires : `Démarrer`, `Arrêter`, `Redémarrer` - boutons experts : `Ouvrir le terminal`, `Voir les logs`, `Diagnostics avancés` - désactivation : - boutons runtime désactivés si cible ambiguë, profil incohérent ou action déjà en cours sur le service ### 6.4 Page `Base de données` - bouton principal unique : `Migrer le release` - boutons secondaires : `Tester la connexion`, `Créer un backup`, `Préparer la base non-prod` - boutons experts : `Restaurer une base cible`, `Mode expert` - désactivation : - `Migrer le release` désactivé si DB cible non confirmée, diagnostic critique, release de migration inconnue ou action en cours - `Restaurer une base cible` désactivé si artefact source absent ### 6.5 Page `Releases` - bouton principal unique : `Activer ce release` - boutons secondaires : `Revenir au release précédent`, `Vérifier la présence du release` - boutons experts : `Activer + smoke`, `Nettoyer les anciens releases` - désactivation : - `Activer ce release` désactivé si release absente côté distant, diagnostic critique ou action en cours - `Revenir au release précédent` désactivé si aucun rollback disponible ### 6.6 Page `Env` - bouton principal unique : `Enregistrer` - boutons secondaires : `Ouvrir`, `Créer`, `Dupliquer`, `Activer cet environnement` - boutons experts : `Mode expert JSON`, `Voir les couches` - désactivation : - `Enregistrer` désactivé si validation formulaire échoue ou sauvegarde déjà en cours - `Activer cet environnement` désactivé si une action sensible est en cours ailleurs --- ## 7. États UI ### 7.1 Loading - texte exact : `Chargement…` - comportement visuel : - skeleton ou contenu atténué ; - titres visibles ; - contexte global visible ; - bouton déclencheur désactivé. ### 7.2 Succès - texte exact : `Action terminée avec succès` - comportement visuel : - badge vert ; - résumé court ; - détails repliables ; - mise à jour du pipeline si l’action valide une étape. ### 7.3 Erreur - texte exact : `Action échouée` - comportement visuel : - badge rouge ; - message d’erreur court ; - remédiation courte ; - pipeline inchangé ou bloqué selon le cas. ### 7.4 Bloqué - texte exact : `Bloqué` - comportement visuel : - badge rouge ; - bouton principal désactivé ; - cause affichée juste sous le badge ; - `Prochain pas recommandé` orienté résolution. ### 7.5 Obsolète - texte exact : `Obsolète` - comportement visuel : - badge ambre ; - ancienne preuve affichée en atténué ; - microcopy : `Étape invalidée par changement de contexte`. ### 7.6 En cours - texte exact : `En cours` - comportement visuel : - badge bleu ; - bouton déclencheur désactivé ; - dernier état utile conservé ; - sortie temps réel attachée au bloc courant. --- ## 8. Exemples concrets ### 8.1 Scénario complet — release prête à activer ```text Bandeau global Release visée : 20260404-014000 Active distante : 20260403-231500 Cible : Préprod Profil : default DB cible : ttm_api / stackmod-dev-mariadb État : vérifié il y a 12 s Temps réel : connecté Pipeline de promotion Build Prêt Build effectué Test local Prêt Front local vérifié Push distant Prêt Release envoyée Validation distante Prêt Runtime distant vérifié Base Prêt Backup disponible Preview Non requis Aucune preview requise Activation Prêt Release activable Releases Activation et rollback du release ciblé. Release ciblée Release visée : 20260404-014000 Active distante : 20260403-231500 Écart : nouvelle release prête Bascule du release [Activer ce release] [Revenir au release précédent] Vérification d’activation Prêt Aucun blocage détecté. Prochain pas recommandé Action recommandée : activer ce release Pourquoi : toutes les étapes requises du pipeline sont prêtes. [Aller à l’action principale] ``` ### 8.2 Scénario complet — release bloquée par la DB ```text Bandeau global Release visée : 20260404-014000 Active distante : 20260403-231500 Cible : Préprod Blocage : DB cible non confirmée Profil : default DB cible : non confirmée État : données à rafraîchir Temps réel : fallback HTTP Pipeline de promotion Build Prêt Build effectué Test local Prêt Front local vérifié Push distant Prêt Release envoyée Validation distante Prêt Runtime distant vérifié Base Bloqué DB cible non confirmée Preview Non commencé À faire Activation Bloqué Base non prête Base de données Prépare et sécurise la base cible pour la release en cours. Contexte DB cible Release visée : 20260404-014000 Active distante : 20260403-231500 Release de migration : 20260404-014000 DB cible : non confirmée Diagnostic DB Bloqué Connexion : OK Prisma : bloqué Dernière vérification : il y a 15 s Remédiation : relancer prepare-release sans skip-install. Sécurité / Backup Warning Aucun backup récent disponible. [Créer un backup] Migration du release Bloqué Release migré : 20260404-014000 DB cible : non confirmée [Migrer le release] (désactivé) Prochain pas recommandé Action recommandée : confirmer la DB cible Pourquoi : l’activation est bloquée tant que la base n’est pas qualifiée. [Aller à Base de données] ``` --- ## 9. Contraintes d’implémentation - aucun bloc principal ne change d’ordre selon l’état ; - un seul bouton principal visible par page ; - tous les blocs experts sont repliés par défaut ; - les microcopies listées ici sont les chaînes de référence ; - aucune action sensible n’est laissée active en état `Bloqué` ; - le bandeau global et le pipeline sont présents sur toutes les pages du parcours ; - toute page termine par `Prochain pas recommandé`.