julien/adastra_api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
30104cda057f0eccf3d4fbd2347bd7c951d5d47e
adastra_api/SCRIPTS_MIGRATION_GUIDE.md
T

8.6 KiB
Raw Blame History

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

Reference in New Issue View Git Blame Copy Permalink