unionflow-server-api/MIGRATION_UUID.md

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

@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:

@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:

// 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:

// 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:

-- 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