adastra_api/SCRIPTS_MIGRATION_GUIDE.md

Migration Scripts - Guide d'utilisation

Vue d'ensemble

Cette migration restructure votre API Express de /api/v1 /api/v2 /api/v3 (qui représentaient des domaines métier, pas des versions API) vers une architecture basée sur les domaines avec des chemins clairs et explicites.

Ancien structure (confuse)

/api/v1/* → Skydive features
/api/v2/* → CMS features 
/api/v3/* → Hero Wars features

Nouvelle structure (claire)

/api/skydive/*   ← Toutes les fonctionnalités de parachutisme
/api/cms/*       ← Gestion de contenu (articles, tags, etc.)
/api/herowars/*  ← Gestion du jeu HeroWars (clans, membres, raids)

---

Scripts de migration

1. migrate-to-domain-structure.js ✓ EXÉCUTÉ

Rôle: Crée la nouvelle structure et migre les fichiers

Statut: ✅ Completed

• Créé les répertoires /api/skydive, /api/cms, /api/herowars
• Copié tous les fichiers de routes vers les nouveaux emplacements
• Généré les nouveaux fichiers index.js pour chaque domaine
• Mis à jour src/routes/api/index.js pour utiliser les nouveaux chemins
• Créé un commit Git

Fichiers modifiés:

✓ src/routes/api/skydive/          (8 fichiers)
✓ src/routes/api/cms/              (8 fichiers)
✓ src/routes/api/herowars/         (3 fichiers)
✓ src/routes/api/index.js          (mis à jour)

Rapports générés:

• MIGRATION_REPORT.md - Détails complets de la migration
• MIGRATION_SWAGGER_TODO.md - Tâches pour Swagger

---

2. update-references-post-migration.js ✓ EXÉCUTÉ

Rôle: Met à jour les références aux chemins dans la documentation

Statut: ✅ Completed

• Mis à jour les fichiers YAML Swagger (/api/v1/ → /api/skydive/, etc.)
• Mis à jour la collection et l'environnement Postman
• Scanné les fichiers clés pour les références restantes

Rapports générés:

• POST_MIGRATION_CHECKLIST.md - Liste de vérification manuelle

---

3. finalize-migration.js

Rôle: Valide, nettoie, et teste la migration

Options disponibles:

# Valider la structure sans rien faire
node scripts/finalize-migration.js

# Valider et nettoyer les anciens répertoires
node scripts/finalize-migration.js --cleanup

# Valider et tester les endpoints (nécessite le serveur en cours d'exécution)
node scripts/finalize-migration.js --test

# Mode complet: validation, nettoyage et résumé
node scripts/finalize-migration.js --full

Statut: ✅ Ready to run

Rapport généré:

• MIGRATION_COMPLETE_SUMMARY.md - Résumé final avec instructions

---

Guide étape par étape

Étape 1: Vérifier la migration ✅

ls -la src/routes/api/
# Devrait afficher: cms/, herowars/, skydive/, v1/, v2/, v3/, index.js

Étape 2: Valider la structure

node scripts/finalize-migration.js

Résultat attendu:

✓ skydive/: ✓ (8 route files)
✓ cms/: ✓ (7 route files)
✓ herowars/: ✓ (3 route files)

Étape 3: Nettoyer les anciens répertoires (OPTIONNEL)

# Option A: Via le script
node scripts/finalize-migration.js --cleanup

# Option B: Manuellement
rm -rf src/routes/api/v1 src/routes/api/v2 src/routes/api/v3
git add -A
git commit -m "chore: remove old v1/v2/v3 route directories"

Étape 4: Mettre à jour le frontend (IMPORTANT)

Fichiers à modifier dans adastra_app/src/environments/:

environment.ts

// AVANT:
export const environment = {
  production: false,
  apiUrl: '/api/v1',
  cmsUrl: '/api/v2',
  herowarsUrl: '/api/v3',
};

// APRÈS:
export const environment = {
  production: false,
  apiUrl: '/api/skydive',
  cmsUrl: '/api/cms',
  herowarsUrl: '/api/herowars',
};

environment.development.ts et environment.local.ts

Applique les mêmes changements

Mise à jour des services Angular:

// Dans vos services (par exemple, src/app/services/*.service.ts)

// AVANT:
this.http.get(environment.apiUrl + '/jumps')
this.http.get(environment.cmsUrl + '/articles')
this.http.get(environment.herowarsUrl + '/clans')

// APRÈS:
this.http.get(environment.apiUrl + '/jumps')
this.http.get(environment.cmsUrl + '/articles')
this.http.get(environment.herowarsUrl + '/clans')
// Pas de changement si vous utilisez les variables d'environnement!
// Sinon, cherchez/remplacez les chemins en dur

Automatiser la mise à jour du frontend (macOS/Linux):

cd adastra_app
sed -i '' "s|/api/v1|/api/skydive|g" src/**/*.ts
sed -i '' "s|/api/v2|/api/cms|g" src/**/*.ts
sed -i '' "s|/api/v3|/api/herowars|g" src/**/*.ts

Étape 5: Tester les endpoints

Démarrer le serveur API:

cd adastra_api
npm run local

Dans un autre terminal, tester les nouveaux chemins:

# Tester Swagger UI
curl http://localhost:3200/api-docs

# Tester les endpoints des domaines
curl http://localhost:3200/api/skydive/jumps
curl http://localhost:3200/api/cms/articles
curl http://localhost:3200/api/herowars/clans

# Avec authentification si nécessaire
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3200/api/skydive/jumps

Étape 6: Tester le frontend

cd adastra_app
npm start
# Ou avec configuration spécifique
npm run local  # ng serve --configuration local

Vérifier dans les DevTools que les appels API vont vers les nouveaux chemins.

---

Statistiques de la migration

Métrique	Valeur
Nouveaux domaines créés	3 (skydive, cms, herowars)
Fichiers de routes migrés	19
Fichiers index.js créés/mis à jour	4
Fichiers Swagger mis à jour	Oui
Fichiers Postman mis à jour	Oui
Commits Git créés	1 (structure) + opt. 1 (nettoyage)

---

Fichiers de rapport créés

Fichier	Contenu
MIGRATION_REPORT.md	Rapport détaillé de la migration
MIGRATION_SWAGGER_TODO.md	Notes pour les mises à jour Swagger
POST_MIGRATION_CHECKLIST.md	Liste de vérification manuelle
MIGRATION_COMPLETE_SUMMARY.md	Résumé final et instructions
SCRIPTS_MIGRATION_GUIDE.md	Ce fichier

---

Procédure de rollback

Si vous devez annuler la migration:

# Voir l'historique
git log --oneline -10

# Annuler les changements (ajuster le nombre de commits)
git reset --hard HEAD~2

# Ou restaurer une branche spécifique
git reset --hard origin/develop

---

Points clés à retenir

✅ La migration est non-destructive:

• Les anciens répertoires v1/v2/v3 existent toujours
• Vous pouvez les supprimer après vérification

✅ Mises à jour automatisées:

• Scripts: Oui ✓
• Swagger: Oui ✓
• Postman: Oui ✓

⚠️ Mises à jour manuelles requises:

• Frontend Angular (environnement + services)
• Tous les appels API en dur dans le code cliente
• Documentation externe
• Tests d'intégration

✅ Git-safe:

• Chaque étape crée un commit
• Rollback facile si problème

---

Troubleshooting

Les endpoints retournent 404

• ✓ Vérifier que le serveur a redémarré après la migration
• ✓ Vérifier les chemins dans Swagger UI (http://localhost:3200/api-docs)
• ✓ Vérifier que le backend a bien recompilé (avec nodemon)

Les routes ne sont pas trouvées

• ✓ Vérifier que src/routes/api/index.js a les bonnes références
• ✓ Vérifier que chaque domaine a un index.js
• ✓ Vérifier l'ordre des middlewares dans app.js

Erreurs d'authentification

• ✓ Les middlewares d'auth ne sont pas affectés
• ✓ Les tokens JWT restent valides
• ✓ Les headers restent les mêmes

Le frontend ne peut pas accéder à l'API

• ✓ Vérifier CORS dans app.js
• ✓ Vérifier les URLs dans les environnements Angular
• ✓ Vérifier les appels http dans les services

---

Prochaines étapes

1. ✅ Tester tous les endpoints du backend
2. ✅ Mettre à jour le frontend (environnement + services)
3. ✅ Tester le frontend avec le backend modifié
4. ✅ Mettre à jour la documentation
5. ✅ Nettoyer les anciens répertoires v1/v2/v3 (optionnel)
6. ✅ Déployer en staging/production

---

Ressources supplémentaires

• Documentation architecture: ARCHITECTURE_DIAGRAMS.md
• ADR (Architecture Decision Records): ADR_INDEX.md
• Configuration Swagger: src/config/swagger.js
• Routes configuration: src/routes/api/index.js

---

Support

Pour des questions ou problèmes:

1. ✓ Consulter los fichiers de rapport (POST_MIGRATION_CHECKLIST.md, etc.)
2. ✓ Vérifier les logs du serveur: npm run local (output)
3. ✓ Vérifier Swagger UI: http://localhost:3200/api-docs
4. ✓ Exécuter la validation: node scripts/finalize-migration.js

---

Migration effectuée le: 24 avril 2026 Version API: v1/v2/v3 → domain-based Status: ✅ Complete