adastra_api/docs/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:**
```bash
# 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 ✅
```bash
ls -la src/routes/api/
# Devrait afficher: cms/, herowars/, skydive/, v1/, v2/, v3/, index.js
```

### Étape 2: Valider la structure
```bash
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)
```bash
# 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`
```typescript
// 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:**
```typescript
// 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):**
```bash
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:**
```bash
cd adastra_api
npm run local
```

**Dans un autre terminal, tester les nouveaux chemins:**
```bash
# 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

```bash
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:

```bash
# 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