329 lines
14 KiB
Markdown
329 lines
14 KiB
Markdown
╔═══════════════════════════════════════════════════════════════════════════════╗
|
|
║ ║
|
|
║ ✅ MIGRATION AUTOMATIQUE RÉUSSIE - Structure Basée Domaines ║
|
|
║ ║
|
|
║ De: /api/v1, /api/v2, /api/v3 (confus) ║
|
|
║ Vers: /api/skydive, /api/cms, /api/herowars (clair) ║
|
|
║ ║
|
|
╚═══════════════════════════════════════════════════════════════════════════════╝
|
|
|
|
📊 STATISTIQUES DE LA MIGRATION
|
|
═══════════════════════════════════════════════════════════════════════════════
|
|
|
|
✓ Fichiers de routes migrés: 19 fichiers
|
|
✓ Domaines créés: 3 nouveaux domaines
|
|
✓ Fichiers index.js: 4 créés/mis à jour
|
|
✓ Documentation: 5 fichiers de rapport
|
|
✓ Scripts de migration: 3 scripts npm
|
|
✓ Commits Git: 2 commits
|
|
✓ Fichiers Swagger mis à jour: 4 fichiers YAML
|
|
|
|
|
|
🎯 STRUCTURE NOUVELLE CRÉÉE
|
|
═══════════════════════════════════════════════════════════════════════════════
|
|
|
|
src/routes/api/
|
|
├── skydive/ ← Parachutisme
|
|
│ ├── aeronefs.js
|
|
│ ├── applications.js
|
|
│ ├── canopies.js
|
|
│ ├── dropzones.js
|
|
│ ├── jumps.js
|
|
│ ├── pages.js
|
|
│ ├── profiles.js
|
|
│ ├── qcm.js
|
|
│ └── index.js
|
|
│
|
|
├── cms/ ← Gestion de contenu
|
|
│ ├── articles.routes.js
|
|
│ ├── comments.routes.js
|
|
│ ├── product.routes.js
|
|
│ ├── products.routes.js
|
|
│ ├── profiles.routes.js
|
|
│ ├── tags.routes.js
|
|
│ ├── user.routes.js
|
|
│ └── index.js
|
|
│
|
|
└── herowars/ ← Jeu HeroWars
|
|
├── clans.routes.js
|
|
├── members.routes.js
|
|
├── herowars.routes.js
|
|
└── index.js
|
|
|
|
|
|
📝 FICHIERS DE DOCUMENTATION CRÉÉS
|
|
═══════════════════════════════════════════════════════════════════════════════
|
|
|
|
1. MIGRATION_REPORT.md
|
|
└─ Rapport détaillé: structure ancienne → nouvelle, fichiers migrés
|
|
|
|
2. MIGRATION_COMPLETE_SUMMARY.md
|
|
└─ Résumé exécutif avec instructions de test et frontend
|
|
|
|
3. POST_MIGRATION_CHECKLIST.md
|
|
└─ Liste de vérification manuelle pour validation
|
|
|
|
4. SCRIPTS_MIGRATION_GUIDE.md
|
|
└─ Guide complet d'utilisation des scripts (CE FICHIER)
|
|
|
|
5. MIGRATION_SWAGGER_TODO.md
|
|
└─ Notes sur les mises à jour Swagger/OpenAPI
|
|
|
|
|
|
⚙️ SCRIPTS DE MIGRATION CRÉÉS
|
|
═══════════════════════════════════════════════════════════════════════════════
|
|
|
|
1. scripts/migrate-to-domain-structure.js
|
|
│
|
|
├─ Phase 1: Crée les répertoires de domaines
|
|
├─ Phase 2: Migre tous les fichiers de routes
|
|
├─ Phase 3: Génère les fichiers index.js
|
|
├─ Phase 4: Met à jour src/routes/api/index.js
|
|
├─ Phase 5: Crée les notes Swagger
|
|
├─ Phase 6: Gère les fichiers Swagger
|
|
├─ Phase 7: Effectue les opérations Git
|
|
├─ Phase 8: Valide la migration
|
|
└─ Phase 9: Génère un rapport
|
|
|
|
[✅ EXÉCUTÉ: commit 9f73ed0]
|
|
|
|
2. scripts/update-references-post-migration.js
|
|
│
|
|
├─ Phase 1: Met à jour les fichiers YAML Swagger
|
|
├─ Phase 2: Met à jour la collection/env Postman
|
|
├─ Phase 3: Scanne les références v1/v2/v3 restantes
|
|
└─ Phase 4: Génère une liste de vérification
|
|
|
|
[✅ EXÉCUTÉ]
|
|
|
|
3. scripts/finalize-migration.js
|
|
│
|
|
├─ Phase 1: Valide la structure des domaines
|
|
├─ Phase 2: Liste les anciens répertoires
|
|
├─ Phase 3: Optionnel - Nettoie les v1/v2/v3 (--cleanup)
|
|
├─ Phase 4: Optionnel - Teste les endpoints (--test)
|
|
└─ Phase 5: Génère un résumé final
|
|
|
|
[PRÊT À EXÉCUTER - voir instructions ci-dessous]
|
|
|
|
|
|
🚀 PROCHAINES ÉTAPES IMMÉDIATES
|
|
═══════════════════════════════════════════════════════════════════════════════
|
|
|
|
ÉTAPE 1️⃣: VALIDER LA STRUCTURE
|
|
────────────────────────────────────────────────────────────────────────────────
|
|
$ node scripts/finalize-migration.js
|
|
|
|
✓ Affichera: "skydive/: ✓ (8 route files)"
|
|
✓ Affichera: "cms/: ✓ (7 route files)"
|
|
✓ Affichera: "herowars/: ✓ (3 route files)"
|
|
|
|
|
|
ÉTAPE 2️⃣: NETTOYER LES ANCIENS RÉPERTOIRES (OPTIONNEL)
|
|
────────────────────────────────────────────────────────────────────────────────
|
|
OPTION A - Via 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 directories"
|
|
|
|
|
|
ÉTAPE 3️⃣: TESTER LE SERVEUR
|
|
────────────────────────────────────────────────────────────────────────────────
|
|
Terminal 1 - Démarrer l'API:
|
|
$ npm run local
|
|
|
|
Terminal 2 - Tester les endpoints:
|
|
$ curl http://localhost:3200/api-docs # Swagger UI
|
|
$ curl http://localhost:3200/api/skydive/jumps # Skydive
|
|
$ curl http://localhost:3200/api/cms/articles # CMS
|
|
$ curl http://localhost:3200/api/herowars/clans # HeroWars
|
|
|
|
|
|
ÉTAPE 4️⃣: METTRE À JOUR LE FRONTEND (IMPORTANT!) 🔴
|
|
────────────────────────────────────────────────────────────────────────────────
|
|
|
|
A. Mettre à jour les environnements Angular:
|
|
Fichiers à modifier:
|
|
- src/environments/environment.ts
|
|
- src/environments/environment.development.ts
|
|
- src/environments/environment.local.ts
|
|
|
|
AVANT:
|
|
export const environment = {
|
|
apiUrl: '/api/v1',
|
|
cmsUrl: '/api/v2',
|
|
herowarsUrl: '/api/v3',
|
|
};
|
|
|
|
APRÈS:
|
|
export const environment = {
|
|
apiUrl: '/api/skydive',
|
|
cmsUrl: '/api/cms',
|
|
herowarsUrl: '/api/herowars',
|
|
};
|
|
|
|
B. Mettre à jour les services Angular:
|
|
Cherchez et remplacez les chemins en dur:
|
|
|
|
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
|
|
|
|
C. Tester le frontend:
|
|
$ npm start
|
|
Vérifier dans DevTools que les appels API vont vers /api/skydive/*, /api/cms/*, etc.
|
|
|
|
|
|
ÉTAPE 5️⃣: POUSSER LES CHANGEMENTS
|
|
────────────────────────────────────────────────────────────────────────────────
|
|
$ git push origin develop
|
|
ou
|
|
$ git push --all --follow-tags
|
|
|
|
|
|
📋 RÉSUMÉ DES COMMITS GIT
|
|
═══════════════════════════════════════════════════════════════════════════════
|
|
|
|
Commit 1: 9f73ed0
|
|
├─ Message: "refactor: restructure API routes from v1/v2/v3 to domain-based..."
|
|
├─ Actions:
|
|
│ ├─ Créé: src/routes/api/skydive/, cms/, herowars/
|
|
│ ├─ Copié: 19 fichiers de routes
|
|
│ └─ Mis à jour: src/routes/api/index.js
|
|
└─ État: ✅ MERGED
|
|
|
|
Commit 2: 74df96c
|
|
├─ Message: "docs: add migration documentation, finalization scripts, and update Swagger paths"
|
|
├─ Actions:
|
|
│ ├─ Créé: 4 fichiers de documentation
|
|
│ ├─ Créé: 2 scripts de finalisation
|
|
│ └─ Mis à jour: 4 fichiers Swagger YAML
|
|
└─ État: ✅ CURRENT HEAD
|
|
|
|
|
|
🔄 AVANT/APRÈS - COMPARAISON DES API
|
|
═══════════════════════════════════════════════════════════════════════════════
|
|
|
|
SAUT/PARACHUTISME:
|
|
AVANT: GET /api/v1/jumps
|
|
APRÈS: GET /api/skydive/jumps
|
|
──────────────────────
|
|
GET /api/v1/aeronefs → GET /api/skydive/aeronefs
|
|
POST /api/v1/aeronefs → POST /api/skydive/aeronefs
|
|
|
|
CONTENU:
|
|
AVANT: GET /api/v2/articles
|
|
APRÈS: GET /api/cms/articles
|
|
────────────────────────
|
|
GET /api/v2/articles/123 → GET /api/cms/articles/123
|
|
POST /api/v2/articles → POST /api/cms/articles
|
|
GET /api/v2/comments → GET /api/cms/comments
|
|
|
|
JEU:
|
|
AVANT: GET /api/v3/clans
|
|
APRÈS: GET /api/herowars/clans
|
|
────────────────────────
|
|
GET /api/v3/members → GET /api/herowars/members
|
|
POST /api/v3/members/123 → POST /api/herowars/members/123
|
|
|
|
|
|
⚠️ IMPORTANT: ROLLBACK EN CAS DE PROBLÈME
|
|
═══════════════════════════════════════════════════════════════════════════════
|
|
|
|
Si vous rencontrez des problèmes:
|
|
|
|
Option 1 - Peu de changements (rollback 2 commits):
|
|
$ git reset --hard HEAD~2
|
|
|
|
Option 2 - Si vous avez poussé, utiliser revert:
|
|
$ git revert 74df96c
|
|
$ git revert 9f73ed0
|
|
|
|
Option 3 - Restaurer depuis le remote:
|
|
$ git fetch origin
|
|
$ git reset --hard origin/develop
|
|
|
|
|
|
✅ CHECKLIST DE VALIDATION POST-MIGRATION
|
|
═══════════════════════════════════════════════════════════════════════════════
|
|
|
|
Backend (adastra_api):
|
|
☐ npm run local - serveur démarre sans erreur
|
|
☐ curl http://localhost:3200/api-docs - Swagger UI accessible
|
|
☐ Endpoints skydive fonctionnent: GET /api/skydive/jumps
|
|
☐ Endpoints CMS fonctionnent: GET /api/cms/articles
|
|
☐ Endpoints HeroWars fonctionnent: GET /api/herowars/clans
|
|
|
|
Frontend (adastra_app):
|
|
☐ npm start - app démarre sans erreur
|
|
☐ Appels API vont vers les nouveaux chemins
|
|
☐ Authentification toujours fonctionnelle
|
|
☐ Pages affichent les données correctement
|
|
☐ Aucune erreur 404 sur les endpoints
|
|
|
|
Git:
|
|
☐ Commits créés et visibles: git log --oneline -5
|
|
☐ Prêt pour: git push origin develop
|
|
|
|
Documentation:
|
|
☐ README.md mis à jour (optionnel)
|
|
☐ Équipe notifiée du changement
|
|
☐ Documentation technique mise à jour
|
|
|
|
|
|
📚 RESSOURCES SUPPLÉMENTAIRES
|
|
═══════════════════════════════════════════════════════════════════════════════
|
|
|
|
Consultez ces fichiers pour plus d'informations:
|
|
|
|
1. SCRIPTS_MIGRATION_GUIDE.md
|
|
└─ Guide détaillé de chaque script et options
|
|
|
|
2. POST_MIGRATION_CHECKLIST.md
|
|
└─ Liste complète de vérification manuelle
|
|
|
|
3. MIGRATION_COMPLETE_SUMMARY.md
|
|
└─ Résumé exécutif avec instructions
|
|
|
|
4. docs/*.md (depuis l'audit architectural)
|
|
└─ Architecture complète et ADRs
|
|
|
|
|
|
🎓 POINTS CLÉS À RETENIR
|
|
═══════════════════════════════════════════════════════════════════════════════
|
|
|
|
✓ NON-DESTRUCTIF: Les anciens répertoires restent, vous pouvez les nettoyer
|
|
progressivement après vérification
|
|
|
|
✓ AUTOMATISÉ: Scripts Python/Node qui gèrent la plupart des tâches
|
|
Swagger, Postman, routes mis à jour automatiquement
|
|
|
|
⚠️ MANUEL: Frontend DOIT être mis à jour (recherche/remplace)
|
|
Tests doivent être revérifiés
|
|
Documentation peut nécessiter mise à jour
|
|
|
|
✓ GIT-SAFE: Chaque étape crée un commit
|
|
Rollback facile si problème
|
|
Toutes les modifications sont tracées
|
|
|
|
✓ BÉNÉFICES: Chemins d'API clairs et explicites
|
|
Séparation nette des domaines métier
|
|
Meilleure architecture et maintenabilité
|
|
Préparation pour futures versions d'API
|
|
|
|
|
|
═══════════════════════════════════════════════════════════════════════════════
|
|
|
|
✨ Migration complétée avec succès! ✨
|
|
|
|
Prêt à continuer avec les 20 ADRs d'architecture?
|
|
(QUICK_START_WEEK1.md pour la Phase 1)
|
|
|
|
═══════════════════════════════════════════════════════════════════════════════
|
|
|
|
Date: 24 avril 2026
|
|
Statut: ✅ COMPLETE
|
|
Prochaine étape: Mise à jour du frontend + tests
|