# Stratégie des migrations Flyway

## Vue d’ensemble

| Version | Fichier | Rôle |
|--------|---------|------|
| **V1** | `V1__UnionFlow_Complete_Schema.sql` | Schéma historique consolidé (anciennes V1.2 à V3.7) + données de référence et de test |
| **V2** | `V2__Entity_Schema_Alignment.sql` | Alignement du schéma avec les entités JPA (colonnes/tables manquantes, types, index). Idempotent. |

Les 25 fichiers d’origine sont conservés dans **`db/legacy-migrations/`** (référence uniquement, Flyway ne les exécute pas).

## Ordre d’exécution

1. **V1** : crée les tables, contraintes et données de base.
2. **V2** : ajoute ou modifie colonnes/tables pour correspondre aux entités JPA (ADD COLUMN IF NOT EXISTS, CREATE TABLE IF NOT EXISTS). Peut être exécuté plusieurs fois sans effet de bord.

## Nouvelle base de données

Avec une base vide, Flyway exécute **V1** puis **V2**. Aucune autre action.

## Base déjà migrée avec les anciennes versions (V1.2 à V3.7)

Si la base a déjà été migrée avec les 25 anciens scripts, il faut **une seule fois** mettre à jour l’historique Flyway pour refléter la consolidation :

1. Sauvegarder la base.
2. Se connecter en base (psql, DBeaver, etc.) et exécuter :

```sql
-- Marquer la consolidation comme appliquée (une seule fois)
DELETE FROM flyway_schema_history WHERE version IN (
  '1.2','1.3','1.4','1.5','1.6','1.7','2.0','2.1','2.2','2.3','2.4','2.5','2.6','2.7','2.8','2.9','2.10',
  '3.0','3.1','3.2','3.3','3.4','3.5','3.6','3.7'
);
INSERT INTO flyway_schema_history (installed_rank, version, description, type, script, checksum, installed_by, execution_time, success)
VALUES (
  (SELECT COALESCE(MAX(installed_rank),0) + 1 FROM flyway_schema_history f2),
  '1', 'UnionFlow Complete Schema', 'SQL', 'V1__UnionFlow_Complete_Schema.sql', NULL, current_user, 0, true
);
```

Après cela, Flyway considère que la version **1** est appliquée et n’exécutera plus les anciens scripts.

## Évolutions futures

- **Changement de schéma métier** (nouvelles tables, nouvelles colonnes métier) : ajouter une migration **V3**, **V4**, etc. (une par release ou lot cohérent).
- **Alignement entités JPA** : si de nouvelles entités ou champs sont ajoutés au code, compléter **`V2__Entity_Schema_Alignment.sql`** avec des `ADD COLUMN IF NOT EXISTS` / `CREATE TABLE IF NOT EXISTS` pour garder un seul fichier d’alignement.

## Régénérer le script consolidé

Si les fichiers dans `legacy/` sont modifiés et que vous voulez régénérer `V1__UnionFlow_Complete_Schema.sql` :

```powershell
cd unionflow-server-impl-quarkus
./scripts/merge-migrations.ps1
```

(Remettre temporairement les 25 fichiers dans `db/migration/` avant de lancer le script, puis les redéplacer dans `legacy/`.)