# Migration UUID - Documentation UnionFlow

## Vue d'ensemble

Ce document décrit la migration complète des identifiants de `Long` (BIGINT) vers `UUID` dans le projet UnionFlow, effectuée le 16 janvier 2025.

## Contexte

### Avant la migration
- Les entités utilisaient `PanacheEntity` avec des IDs de type `Long` (BIGSERIAL en PostgreSQL)
- Les repositories utilisaient `PanacheRepository<Entity, Long>`
- Les DTOs utilisaient `UUID` pour les identifiants, nécessitant une conversion constante

### Après la migration
- Toutes les entités utilisent `BaseEntity` avec des IDs de type `UUID`
- Tous les repositories utilisent `BaseRepository<Entity>` avec `EntityManager`
- Les DTOs et entités utilisent directement `UUID`, éliminant le besoin de conversion

## Changements architecturaux

### 1. BaseEntity (remplace PanacheEntity)

**Fichier:** `unionflow-server-impl-quarkus/src/main/java/dev/lions/unionflow/server/entity/BaseEntity.java`

```java
@MappedSuperclass
public abstract class BaseEntity {
    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    @Column(name = "id", updatable = false, nullable = false)
    private UUID id;
    
    // Champs d'audit communs...
}
```

**Avantages:**
- Génération automatique d'UUID par la base de données
- Pas de séquences à gérer
- Identifiants uniques globaux (pas seulement dans une table)
- Compatible avec les architectures distribuées

### 2. BaseRepository (remplace PanacheRepository)

**Fichier:** `unionflow-server-impl-quarkus/src/main/java/dev/lions/unionflow/server/repository/BaseRepository.java`

**Changements:**
- Utilise `EntityManager` au lieu des méthodes Panache
- Toutes les méthodes utilisent `UUID` au lieu de `Long`
- Fournit les opérations CRUD de base avec UUID

**Exemple:**
```java
@ApplicationScoped
public class MembreRepository extends BaseRepository<Membre> {
    public MembreRepository() {
        super(Membre.class);
    }
    
    public Optional<Membre> findByEmail(String email) {
        TypedQuery<Membre> query = entityManager.createQuery(
            "SELECT m FROM Membre m WHERE m.email = :email", Membre.class);
        query.setParameter("email", email);
        return query.getResultStream().findFirst();
    }
}
```

### 3. Migrations de base de données

**Fichier:** `unionflow-server-impl-quarkus/src/main/resources/db/migration/V1.3__Convert_Ids_To_UUID.sql`

**Étapes de migration:**
1. Suppression des contraintes de clés étrangères existantes
2. Suppression des séquences (BIGSERIAL)
3. Suppression des tables existantes
4. Recréation des tables avec UUID comme clé primaire
5. Recréation des clés étrangères avec UUID
6. Recréation des index et contraintes

**Tables migrées:**
- `organisations`
- `membres`
- `cotisations`
- `evenements`
- `inscriptions_evenement`
- `demandes_aide`

## Entités migrées

| Entité | Ancien ID | Nouveau ID | Repository |
|--------|-----------|------------|------------|
| Organisation | Long | UUID | OrganisationRepository |
| Membre | Long | UUID | MembreRepository |
| Cotisation | Long | UUID | CotisationRepository |
| Evenement | Long | UUID | EvenementRepository |
| DemandeAide | Long | UUID | DemandeAideRepository |
| InscriptionEvenement | Long | UUID | (à créer si nécessaire) |

## Services mis à jour

### Services corrigés pour utiliser UUID:
- `MembreService` - Toutes les méthodes utilisent UUID
- `CotisationService` - Toutes les méthodes utilisent UUID
- `OrganisationService` - Toutes les méthodes utilisent UUID
- `DemandeAideService` - Converti de String vers UUID
- `EvenementService` - Utilise UUID

### Exemple de changement:
```java
// Avant
public MembreDTO trouverParId(Long id) { ... }

// Après
public MembreDTO trouverParId(UUID id) { ... }
```

## DTOs mis à jour

Tous les DTOs utilisent maintenant `UUID` directement:
- `MembreDTO.associationId` : Long → UUID
- `CotisationDTO.membreId` : Long → UUID
- Tous les autres champs ID : Long → UUID

## Classes dépréciées

### IdConverter
**Fichier:** `unionflow-server-impl-quarkus/src/main/java/dev/lions/unionflow/server/util/IdConverter.java`

Cette classe est maintenant **@Deprecated** car elle n'est plus nécessaire. Elle est conservée uniquement pour compatibilité avec d'éventuels anciens scripts de migration.

**Action recommandée:** Supprimer cette classe dans une version future (après vérification qu'elle n'est plus utilisée).

## Tests

### Tests à mettre à jour
Les tests qui utilisent encore `Long` ou des méthodes Panache doivent être mis à jour:

**Fichiers concernés:**
- `MembreServiceAdvancedSearchTest.java` - Utilise `persist()` et `isPersistent()`
- Tous les tests d'intégration qui créent des entités avec des IDs Long

**Exemple de correction:**
```java
// Avant
membre.persist();
if (membre.isPersistent()) { ... }

// Après
membreRepository.persist(membre);
if (membre.getId() != null) { ... }
```

## Migration de données (si nécessaire)

Si vous avez des données existantes à migrer, vous devrez:

1. **Créer une migration de données personnalisée** qui:
   - Génère des UUIDs pour chaque enregistrement existant
   - Met à jour toutes les clés étrangères
   - Préserve les relations entre entités

2. **Exemple de script de migration:**
```sql
-- Ajouter colonne temporaire
ALTER TABLE membres ADD COLUMN id_new UUID;

-- Générer UUIDs
UPDATE membres SET id_new = gen_random_uuid();

-- Mettre à jour les clés étrangères
UPDATE cotisations SET membre_id_new = (
    SELECT id_new FROM membres WHERE membres.id = cotisations.membre_id
);

-- Remplacer les colonnes (étapes complexes avec contraintes)
-- ...
```

## Avantages de la migration UUID

1. **Unicité globale:** Les UUIDs sont uniques même entre différentes bases de données
2. **Sécurité:** Plus difficile de deviner les IDs (pas de séquences prévisibles)
3. **Architecture distribuée:** Compatible avec les systèmes distribués et microservices
4. **Pas de séquences:** Pas besoin de gérer les séquences de base de données
5. **Cohérence:** Les DTOs et entités utilisent le même type d'ID

## Inconvénients

1. **Taille:** UUID (16 bytes) vs Long (8 bytes)
2. **Performance:** Les index sur UUID peuvent être légèrement plus lents que sur Long
3. **Lisibilité:** Les UUIDs sont moins lisibles que les IDs numériques

## Recommandations

1. **Index:** Assurez-vous que tous les index nécessaires sont créés sur les colonnes UUID
2. **Performance:** Surveillez les performances des requêtes avec UUID
3. **Tests:** Mettez à jour tous les tests pour utiliser UUID
4. **Documentation:** Mettez à jour la documentation API pour refléter l'utilisation d'UUID

## Prochaines étapes

1. ✅ Migration des entités vers BaseEntity
2. ✅ Migration des repositories vers BaseRepository
3. ✅ Création de la migration Flyway
4. ⏳ Mise à jour des tests unitaires
5. ⏳ Mise à jour de la documentation API
6. ⏳ Vérification des performances
7. ⏳ Suppression de IdConverter (après vérification)

## Support

Pour toute question concernant cette migration, contactez l'équipe UnionFlow.

**Date de migration:** 16 janvier 2025  
**Version:** 2.0  
**Auteur:** UnionFlow Team

