Gestion des étapes - StevenYAMBOS/Smash-Here-API GitHub Wiki
Mise à jour d’une Roadmap
Cette page décrit le fonctionnement du composant UpdateRoadmapForm.vue
qui permet de modifier une roadmap en deux volets distincts :
- Informations de base (titre, description, image, flags, jeux associés)
- Structure des étapes (liste des étapes, relations parent/enfant)
Contexte global
-
Le composant se trouve dans
src/components/ui/UpdateRoadmapForm.vue
. -
La modification d’une roadmap se fait désormais en deux formulaires séparés :
-
Formulaire 1 : Informations de base
- Champs utilisés :
title
,subTitle
,description
,cover
,published
,premium
,Games
- Routes Back-End à utiliser :
getOneRoadmap
: récupérer l’objet roadmap completupdateRoadmapInfo
: mettre à jour uniquement les champs « info de base »
- Champs utilisés :
-
Formulaire 2 : Étapes
- Champ utilisé :
Steps
(tableau d’ObjectId
pointant vers des documentsstep
) - Routes Back-End à utiliser :
getRoadmapSteps
: récupérer le tableau initialSteps
de la roadmapupdateRoadmapSteps
: mettre à jour la liste d’IDsSteps
dans le documentroadmap
updateOneStep
: mettre à jour un documentstep
(champsPreviousSteps
,NextSteps
,Roadmaps
)addStepToRoadmaps
etremoveStepFromRoadmap
(peuvent être utilisés pour des appels plus fins si nécessaire)
- Champ utilisé :
-
1. Formulaire 1 : Informations de base
1.1 Objectif
Ce premier onglet permet de modifier :
- Le titre (
title
) - Le sous-titre (
subTitle
) - La description (
description
) - L’image de couverture (
cover
) - Les flags Publié (
published
) et Premium (premium
) - Les jeux associés (
Games
)
1.2 Composants et données
Propriétés reçues
props.roadmap
: objet complet de la roadmap existante, contenant notamment :
interface Roadmap {
id: string
title: string
subTitle?: string
description: string
cover: string // URL de la couverture actuelle
published: boolean
premium: boolean
Games: string[] // Tableau d’IDs de jeux déjà associés
Steps: string[]
// … autres champs éventuels …
}
2. Formulaire 2 : Structure des étapes
2.1 Objectif
Ce second onglet permet de gérer la liste d’étapes associées à la roadmap et leurs relations parent↔enfant.
-
On peut ajouter ou retirer une étape de la liste
Steps
de la roadmap. -
On peut relier des étapes (ajouter un lien
source → target
) ou supprimer un lien existant. -
Côté Back-End, on aura besoin des routes :
getRoadmapSteps
: pour charger initialement la listeSteps
(tableau d’IDs) associée à la roadmap.updateRoadmapSteps
: pour réécrire le seul champSteps
dans le documentroadmap
.updateOneStep
: pour mettre à jour individuellement unstep
(tablesPreviousSteps
,NextSteps
et champRoadmaps
).addStepToRoadmaps
/removeStepFromRoadmap
: peuvent être implémentés pour des appels plus granulaires si on veut gagner en efficacité.
2.2 Relations entre étapes
- Chaque document
step
contient, parmi ses champs :
{
"Roadmaps": ["ObjectId"], // IDs des roadmaps qui incluent cette étape
"PreviousSteps": ["ObjectId"], // IDs des étapes parentes
"NextSteps": ["ObjectId"], // IDs des étapes enfants
// ...
}
-
Dans l’UI, on affiche les étapes sur plusieurs niveaux horizontaux :
- Les étapes sans parent (aucun
PreviousSteps
) sont les racines ; elles sont sur la ligne 0. - Les enfants (
NextSteps
) du(s) parent(s) apparaissent sur la ligne 1, etc.
- Les étapes sans parent (aucun
-
Exemple concret :
-
Choix du personnage (Étape 1)
PreviousSteps: []
NextSteps: [ id2 ]
-
Choix de la manette (Étape 2)
PreviousSteps: [ id1 ]
NextSteps: [ id3, id4 ]
-
Les attaques (Étape 3)
PreviousSteps: [ id2 ]
NextSteps: [ … ]
-
La défense (Étape 4)
PreviousSteps: [ id2 ]
NextSteps: [ … ]
-
-
La synchronisation des relations s’effectue via la route
PUT /step/{stepId}
(updateOneStep
). Le back-end s’assure de mettre à jour à la foisPreviousSteps
etNextSteps
de l’étape en question, et de maintenir le champRoadmaps
à jour (pour inclure l’ID de la roadmap si nécessaire).
3. Comprendre le fonctionnement des étapes
3.1 Structure en base de données
Chaque document step
(collection step
) possède notamment :
{
"Roadmaps": ["ObjectId"], // IDs des roadmaps associées
"PreviousSteps": ["ObjectId"], // IDs des étapes parentes
"NextSteps": ["ObjectId"], // IDs des étapes enfants
"title": "string",
"subtitle": "string",
"description": "string",
// ...
}
-
Roadmaps
maintient la liste desObjectId
des roadmaps dans lesquelles cette étape apparaît. -
PreviousSteps
/NextSteps
définissent un graphe orienté (DAG) sans cycles (pour la progression linéaire ou arborescente). -
Par bonne pratique, lorsqu’on modifie un
step
viaPUT /step/{id}
, le back-end doit maintenir la cohérence inverse :- Si l’on ajoute
targetId
dansNextSteps
d’unstep source
,updateOneStep
doit automatiquement incluresourceId
dansPreviousSteps
dustep target
, et vice-versa (bidirectionnel).
- Si l’on ajoute
4. Résumé visuel du composant
UpdateRoadmapForm.vue
├─ Onglet 1 “Informations” (formInfo)
│ ├─ title (input text)
│ ├─ subTitle (input text)
│ ├─ description (textarea)
│ ├─ published (toggle switch)
│ ├─ premium (toggle switch)
│ ├─ Roadmap’s games (Multiselect pré-rempli + recherche)
│ └─ Cover image (preview ancien ou nouveau fichier + input[type=file] caché)
│ └─ Boutons : [Cancel] [Save]
│
└─ Onglet 2 “Steps” (formSteps)
├─ Étapes disponibles (Multiselect + icône “+”)
├─ Aperçu VueFlow (nodes + edges)
│ ├─ nœuds = Steps sélectionnées
│ ├─ arêtes = relations NextSteps / PreviousSteps
│ ├─ onConnect → création d’un lien (PUT /step/{id})
│ ├─ onEdgesChange → suppression d’un lien (PUT /step/{id})
│ └─ Drag & Drop → ajout visuel de nœud (appel addStep + submitStructure)
└─ Bouton : [Enregistrer la structure]
5. Exemple de schéma de l’arborescence des étapes
-
Choix du personnage (Étape 1)
PreviousSteps: []
NextSteps: [ Étape 2 ]
-
Choix de la manette (Étape 2)
PreviousSteps: [ Étape 1 ]
NextSteps: [ Étape 3, Étape 4 ]
-
Les attaques (Étape 3)
PreviousSteps: [ Étape 2 ]
NextSteps: [ … ]
-
La défense (Étape 4)
PreviousSteps: [ Étape 2 ]
NextSteps: [ … ]
Visuellement, VueFlow les organise ainsi (auto-layout) :
(ÉTAPE 1) → (ÉTAPE 2) → (ÉTAPE 3)
↘ (ÉTAPE 4)
- Les nœuds « ÉTAPE 1 » sans parent sont en haut (level 0).
- Les enfants immédiats (« ÉTAPE 2 ») sont en level 1.
- Les petits-enfants (« ÉTAPE 3 » et « ÉTAPE 4 ») sont sur level 2, etc.
6. Bonnes pratiques
- Séparer la mise à jour “infos” et “structure” évite des payloads trop lourds et permet de gérer de façon découplée la logique métier (titres, flags, jeux, images d’un côté / graphe d’étapes de l’autre).
- Toujours recycler l’URL existante
props.roadmap.cover
pour que l’utilisateur voie en temps réel l’ancienne couverture et sache qu’il peut la remplacer. - Vérifier systématiquement la taille et le type du fichier image avant de faire
URL.createObjectURL()
pour éviter des fichiers trop volumineux ou un format non supporté. - Maintenir la cohérence des relations
PreviousSteps ←→ NextSteps
en appelant toujoursupdateOneStep
dès qu’un lien est ajouté ou supprimé, pour que la base reflète l’état du graphe. - Toujours mettre à jour le champ
Roadmaps
d’unstep
lors de son ajout dansselectedSteps
(s’il n’y figure pas). - Tester en local avec
getOneRoadmap
+getStep/{id}
pour vérifier que tous lesPreviousSteps
etNextSteps
remontent correctement.
En résumé, UpdateRoadmapForm.vue
se découpe en deux sous-composants logiques (onglets) :
- Infos de base → Chargement initial via
getOneRoadmap
, mise à jour viaupdateRoadmapInfo
. - Structure des étapes → Chargement initial des IDs via
getRoadmapSteps
(ougetOneRoadmap
), construction du graphe via VueFlow, mise à jour finale de la liste d’IDs viaupdateRoadmapSteps
, et synchronisation point-à-point des liens viaupdateOneStep
,addStepToRoadmaps
,removeStepFromRoadmap
selon les besoins.