# Refactor page Déploiement

> 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 un refactor antérieur à l’extraction du `dev-tools` vers `ttm-dev-tools`. À utiliser seulement comme contexte d’archive.

## 1. Fichiers concernés

### À modifier

- `shared/dev-tools-ui/dev-tools-overview-page.js`
  - **Rôle actuel** : porte l’essentiel du rendu de la page `Déploiement`.
  - **Points réels concernés** :
    - `app.configurePageChrome()` : masque/affiche les zones de page selon `app.currentPage`.
    - `app.renderDeployTopbar()` : remplit le résumé haut de page `Release / Profil / Cible / État`.
    - `app.renderDeploySummary()` : construit aujourd’hui le bloc principal, la suite logique, puis les détails secondaires de `Déploiement`.
    - `app.renderActions()` : sait déjà rendre les actions avancées de `Déploiement`, même si le panneau global d’actions est masqué sur cette page.
  - **Pourquoi le modifier** : c’est ici que l’ordre des blocs, la hiérarchie visuelle et la répartition primaire/secondaire/expert se décident réellement.

- `shared/dev-tools-ui/dev-tools.css`
  - **Rôle actuel** : contient déjà les styles spécifiques à `Déploiement` (`.deploy-primary-panel`, `.deploy-result-block`, `.deploy-follow-up-panel`, `.deploy-secondary-shell`, `.deploy-secondary-panel`, `.deploy-tertiary-panel`, etc.).
  - **Pourquoi le modifier** : la refonte demandée est surtout une refonte d’ordre, de hiérarchie et de lisibilité. Le CSS doit accompagner ce nouvel ordre sans recréer une nouvelle architecture.

- `shared/dev-tools-ui/dev-tools-shared.js`
  - **Rôle actuel** : définit la config de page `deploy` (`title`, `description`, flags d’affichage) et la liste des étapes `deployGuideSteps` / `deployAdvancedActionIds`.
  - **Pourquoi le modifier** : uniquement pour des ajustements de microcopie ou de libellés si nécessaire. Ce fichier ne doit pas devenir le centre de la refonte.

### À laisser tranquilles pour ce patch

- `shared/dev-tools-ui/dev-tools-view-model.js`
  - **Rôle actuel** : alimente le bandeau global, le pipeline de promotion et le prochain pas.
  - **Décision** : **ne pas modifier**. Le socle transverse existe déjà et répond précisément au besoin « où j’en suis » / « quel est le prochain pas ». Il ne faut pas recréer une seconde logique spécifique à `Déploiement`.

- `shared/dev-tools-ui/dev-tools-layout.js`
  - **Rôle actuel** : rend `globalBannerRoot`, `promotionPipelineRoot` et `nextStepRoot`.
  - **Décision** : **ne pas modifier**. Le besoin utilisateur demande explicitement de les utiliser, pas de les refaire.

- `shared/dev-tools-ui/dev-tools-renderers.js`
  - **Rôle actuel** : orchestre les appels de rendu globaux (`renderTransverseLayout`, `renderDeploySummary`, etc.).
  - **Décision** : **ne pas modifier** sauf surprise de wiring. Le problème n’est pas ici.

- `src/modules/devTools/dev-tools.page.parts.ts`
  - **Rôle actuel** : expose les slots DOM de la page (`deploySummaryRoot`, `deployContextRoot`, `nextStepRoot`, `actionsPanel`, etc.).
  - **Décision** : **laisser tranquille dans un premier patch**. Les bons conteneurs existent déjà. On peut restructurer la page `Déploiement` sans changer le squelette HTML.
  - **Exception** : à n’ouvrir que si, après implémentation, l’ordre DOM du `nextStepRoot` pose un vrai problème UX. Ce n’est pas le premier mouvement.

- `docs/dev-tools/lot3-deploy-ui-refactor.md`
  - **Rôle actuel** : cadrage produit déjà écrit sur `Deploy`.
  - **Décision** : **laisser tranquille**. Ce document reste une référence, mais la mise en œuvre concrète doit désormais se faire dans le code réel.

### Synthèse de patch ciblé

- **Patch minimal réaliste** :
  1. `shared/dev-tools-ui/dev-tools-overview-page.js`
  2. `shared/dev-tools-ui/dev-tools.css`
  3. éventuellement `shared/dev-tools-ui/dev-tools-shared.js`

- **Patch à éviter pour ce lot** :
  - backend
  - `view-model` transverse
  - layout transverse
  - refonte du shell global
  - refonte des autres pages

## 2. Structure cible de la page

Ordre exact des blocs de haut en bas, en s’appuyant sur l’existant :

1. **Bandeau global transverse** (`globalBannerRoot`)
   - lecture opératoire minimale globale
   - ne pas dupliquer dans la page métier

2. **Toolbar de page existante**
   - titre `Deploy`
   - description courte
   - sélecteur de release
   - sélecteur de profil
   - résumé haut de page (`renderDeployTopbar`)

3. **Pipeline transverse** (`promotionPipelineRoot`)
   - progression de séquence
   - blocages de parcours
   - étape courante

4. **Bloc métier principal : Flux principal** (`deploySummaryRoot`)
   - **4.1 Contexte immédiat de déploiement**
     - release résolu réellement visé
     - cible effective
     - current distant
     - état d’envoi (`prêt`, `bloqué`, `en cours`)
   - **4.2 Action principale**
     - carte principale `deploy-sync-prepare`
   - **4.3 Action complémentaire immédiate**
     - carte plus petite `deploy-prepare-release`
     - visible seulement si l’action existe
   - **4.4 Résultat récent**
     - dernier résultat utile du flux principal (`deploy-sync-prepare` / `deploy-prepare-release`)
   - **4.5 Détail technique replié du bloc principal**
     - `status CLI` replié
     - jamais au même niveau visuel que l’action principale

5. **Bloc Suite logique** (`deployContextRoot`)
   - renvoi court vers `Database`
   - renvoi court vers `Runtime`
   - bloc court, lisible, non technique

6. **Bloc Détails secondaires** (`deployContextRoot`, dans le `<details>` existant)
   - **6.1 Action séparée** : `deploy-sync`
   - **6.2 Release ciblé**
   - **6.3 Profils de déploiement**
   - **6.4 Contexte runtime API**

7. **Bloc Prochain pas transverse** (`nextStepRoot`)
   - ne pas le dupliquer à l’intérieur du contenu métier
   - il complète la page, il ne faut pas le concurrencer

### Ce qui change concrètement par rapport à aujourd’hui

- Le bloc `Flux principal` doit commencer par un **contexte immédiat compact** avant les boutons.
- Le `status CLI` ne doit plus alourdir la lecture principale : il reste visible, mais replié.
- `Release ciblé`, `Profils de déploiement` et `Contexte runtime API` restent disponibles, mais sortent clairement du premier niveau.
- La page ne doit plus essayer de raconter elle-même le pipeline complet ni le prochain pas : c’est déjà le rôle du socle transverse.

## 3. Ce qui doit être primaire / secondaire / expert

### Action principale

**Primaire absolu**

- `deploy-sync-prepare`
- carte dominante visuellement
- formulation centrée sur :
  - quelle release
  - vers quelle cible
  - puis finalisation minimale si nécessaire

### Guide de séquence

**Primaire, mais transverse**

- le guide de séquence doit vivre dans le **pipeline transverse existant**
- la page `Déploiement` peut conserver un **badge d’état local** dans le header du bloc principal
- en revanche, elle ne doit plus répéter :
  - les 5 étapes détaillées
  - les blocages de parcours déjà portés par le pipeline
  - une narration parallèle de type “étape 4 sur 5” si elle n’apporte rien de plus

### Résultat récent

**Primaire**

- le résultat récent doit être rattaché directement au bloc principal
- il doit remonter :
  - succès
  - échec
  - blocage
- il ne doit pas être noyé dans les détails runtime ou les détails profils

### Contexte de support

**Secondaire utile**

À garder accessibles, mais hors du cœur d’action :

- `deploy-sync` (action séparée)
- `Release ciblé`
- `Profils de déploiement`
- `Suite logique` vers `Database` / `Runtime`

### Détails techniques

**Expert / replié**

- `status CLI` brut
- `rawStatusJson`
- preview release détaillée
- projets détaillés du release
- manifeste / chemins complets
- détails runtime complets
- chaîne de bootstrap API
- remédiation détaillée runtime
- liste complète des profils disponibles

### Arbitrage clair

- **Secondaire** = utile à court terme pour finir le déploiement
- **Expert** = utile seulement pour diagnostiquer ou maintenir
- dès qu’un bloc explique des chemins, du JSON, des diagnostics riches, des détails projet par projet ou de la maintenance runtime, il doit descendre d’un niveau

## 4. CTA

### Bouton principal

- **Action** : `deploy-sync-prepare`
- **Placement** : premier bouton visible du bloc `Flux principal`
- **Wording conseillé** : `Envoyer la release`
- **Microcopie autour du bouton** : la phrase descriptive doit porter le détail cible, pas le label du bouton
  - exemple : `Release 2026.04.06-1 vers prod-app-01, avec finalisation distante minimale si nécessaire.`

### Boutons secondaires

- `deploy-prepare-release`
  - wording conseillé : `Finaliser seulement`
  - rôle : relancer uniquement la finalisation distante
  - niveau : secondaire proche du flux principal

- `deploy-sync`
  - wording conseillé : `Envoyer sans finaliser`
  - rôle : action séparée, maintenance ciblée
  - niveau : secondaire replié

- `deploy-diagnose-api-runtime`
  - wording conseillé : `Diagnostiquer le runtime API`
  - niveau : expert / maintenance

- `deploy-bootstrap-api-runtime`
  - wording conseillé : `Créer / réparer le runtime API`
  - niveau : expert / maintenance

### Conditions de désactivation

#### `deploy-sync-prepare`

Le bouton doit rester désactivé si au moins un de ces cas est vrai :

- action absente
- action indisponible (`!primaryDeployAction.available`)
- action déjà en cours (`primaryDeployRunning`)
- permissions de parcours refusées (`!primaryDeployPermissions.allowed`)

#### `deploy-prepare-release`

- caché si l’action n’existe pas ou n’est pas disponible
- désactivé si en cours (`separatePrepareRunning`)

#### `deploy-sync`

- caché si l’action n’existe pas ou n’est pas disponible
- désactivé si en cours (`separateSyncRunning`)

#### CTA expert runtime

- `deploy-diagnose-api-runtime`
  - désactivé si indisponible ou déjà lancé
- `deploy-bootstrap-api-runtime`
  - désactivé si indisponible ou déjà lancé
  - à laisser dans la maintenance avancée, pas dans le flux principal

### Wording conseillé

#### À garder

- `Envoyer la release`
- `Finaliser seulement`
- `Envoyer sans finaliser`
- `Résultat le plus récent`
- `Suite logique`
- `Détails secondaires`

#### À éviter

- libellés trop techniques dès le premier niveau
- verbes multiples dans un même CTA
- microcopie qui reparle de build, migration DB ou audit runtime dans le bouton principal

## 5. Réutilisation du socle transverse

### Ce que la page doit laisser au bandeau global

Le bandeau global doit continuer à porter :

- fraîcheur de la donnée
- contexte opératoire global
- blocage transverse éventuel
- lecture “est-ce que l’outil est globalement dans un état exploitable ?”

### Ce que la page doit laisser au pipeline

Le pipeline doit continuer à porter :

- la séquence globale de promotion
- l’étape courante
- les blocages de parcours
- la lecture transverse `Build → Test local → Push distant → Validation distante → Database`

### Ce que la page doit laisser au prochain pas

Le bloc `nextStepRoot` doit continuer à porter :

- la recommandation suivante
- le lien vers la bonne page
- la raison principale du prochain mouvement

### Ce que la page ne doit plus répéter

- un second pipeline détaillé dans `Déploiement`
- une seconde recommandation “prochain pas” dans le même vocabulaire que le bloc transverse
- une répétition complète de `Release / Profil / Cible / État` sous forme de gros bandeau métier si le topbar le fait déjà
- des rappels de type `Deploy ne build pas / ne migre pas / n’est pas Runtime` à plusieurs endroits

### Position saine

La page `Déploiement` doit seulement répondre localement à :

1. qu’est-ce que j’envoie ;
2. où est-ce que je l’envoie ;
3. puis-je cliquer maintenant ;
4. qu’est-ce qu’il vient de se passer.

Le reste doit rester transverse.

## 6. Plan de patch concret

### Composants / renderers à modifier

#### 1. `shared/dev-tools-ui/dev-tools-overview-page.js`

**C’est le cœur du patch.**

À faire :

1. **resserrer `renderDeployTopbar()`**
   - utiliser en priorité `selectedReleaseSummary.resolvedReleaseName` plutôt que seulement `requestedReleaseName` / `remoteCurrentReleaseName`
   - garder les 4 pills `Release / Profil / Cible / État`
   - ne pas enrichir davantage

2. **réorganiser `renderDeploySummary()`**
   - ouvrir le bloc principal par un sous-bloc `Contexte immédiat`
   - garder la carte `Envoyer la release` comme centre absolu
   - conserver la carte `Finalisation séparée`, mais visuellement plus discrète
   - garder `Résultat le plus récent` directement sous le flux principal
   - déplacer le `status CLI` dans un détail replié systématique

3. **alléger `secondaryHtml`**
   - ordre recommandé dans le `<details>` secondaire :
     1. `Action séparée`
     2. `Release ciblé`
     3. `Profils de déploiement`
     4. `Contexte runtime API`
   - conserver les renderers métier existants autant que possible
   - éviter d’éclater la logique en trop de nouvelles fonctions si la lisibilité reste bonne

4. **ne pas réintroduire `renderDeployGuide()`**
   - `showGuide` est déjà à `false`
   - le pipeline transverse remplit déjà ce rôle

#### 2. `shared/dev-tools-ui/dev-tools.css`

À faire :

- renforcer visuellement la différence entre :
  - bloc principal
  - bloc suite logique
  - détails secondaires
  - maintenance experte
- ajouter si besoin une classe de type `deploy-immediate-context`
- réduire le poids visuel de la carte `Finaliser seulement`
- faire en sorte que `Résultat le plus récent` soit immédiatement lisible après l’action principale
- garder les détails secondaires lisibles une fois ouverts, sans les faire remonter au niveau du bloc principal

#### 3. `shared/dev-tools-ui/dev-tools-shared.js`

À faire seulement si utile :

- ajuster la microcopie `deploy.description`
- éventuellement harmoniser les libellés exposés par la config de page
- ne pas toucher au modèle transverse ni aux règles de parcours

### Ordre de codage

1. `renderDeploySummary()`
2. `renderDeployTopbar()`
3. `dev-tools.css`
4. `dev-tools-shared.js` si une microcopie reste incohérente

### Risques de régression

- **écouteurs d’événements**
  - `renderDeploySummary()` rebinde des listeners après `innerHTML`
  - tout déplacement de bouton doit conserver les attributs `data-run-action-id`, `data-switch-profile-name`, `data-fill-release-name`

- **états de chargement**
  - la page gère déjà les états `chargement…`
  - il ne faut pas casser les branches sans `summary`

- **visibilité des diagnostics**
  - en repoussant le runtime et le CLI dans le secondaire, il ne faut pas masquer une erreur critique sans signal dans le primaire
  - le primaire doit donc conserver un badge d’état clair et un dernier résultat visible

- **duplication transverse**
  - le plus gros risque produit est de recommencer à raconter le pipeline et le prochain pas dans `renderDeploySummary()`

- **dette de lisibilité dans un gros renderer**
  - `renderDeploySummary()` est déjà volumineux
  - si la réorganisation devient confuse, extraire 2 ou 3 helpers locaux ciblés, pas une mini-architecture complète

## 7. Quick wins

### Quick win 1 — Corriger la release réellement affichée en haut de page

Dans `renderDeployTopbar()`, afficher d’abord le **release résolu** (`selectedReleaseSummary.resolvedReleaseName`) plutôt que seulement la valeur demandée ou le `current` distant.

**Gain** : la page répond mieux à `quelle release je pousse`.

### Quick win 2 — Ajouter un mini bloc `Contexte immédiat` au début du flux principal

Sans créer de nouveau système, ajouter juste au-dessus de la carte principale une rangée compacte de 3 à 4 cartes/pills :

- Release visé
- Cible
- Current distant
- Statut d’envoi

**Gain** : la page devient compréhensible avant même de regarder les détails secondaires.

### Quick win 3 — Sortir le `status CLI` du premier plan

Le `status CLI` est utile, mais il ne doit plus être lu avant le résultat récent.

**Gain** : réduction immédiate du bruit technique.

### Quick win 4 — Garder le résultat récent collé à l’action principale

Ne pas le reléguer dans les détails secondaires.

**Gain** : la page répond clairement à `si je peux l’envoyer` puis `ce qu’il vient de se passer`.

### Quick win 5 — Réduire la place de `Finaliser seulement`

La carte existe déjà et reste utile. Il faut simplement lui donner un rang visuel inférieur à `Envoyer la release`.

**Gain** : meilleur focus sans perdre la capacité métier existante.

### Quick win 6 — Garder `Database ensuite` et `Runtime ensuite` très courts

Ces cartes existent déjà dans `deployContextRoot`. Il faut les garder courtes, directionnelles, non techniques.

**Gain** : la page répond à `quel est le prochain pas après` sans usurper le rôle du bloc transverse `Prochain pas recommandé`.

---

## Décision finale

Pour faire de `Déploiement` la première vraie page métier alignée avec le parcours de promotion de release, il faut **trancher simplement** :

- **le primaire** = `release + cible + possibilité d’envoi + CTA principal + résultat récent`
- **le secondaire** = action séparée + contexte release/profil/runtime utile
- **l’expert** = CLI, runtime détaillé, preview, diagnostics riches
- **le transverse** = bandeau global + pipeline + prochain pas

Le bon patch n’est donc pas une refonte générale.
Le bon patch est une **réorganisation chirurgicale de `renderDeploySummary()`**, accompagnée d’un léger ajustement de `renderDeployTopbar()` et du CSS spécifique `Déploiement`.