219 lines
7.1 KiB
Markdown
219 lines
7.1 KiB
Markdown
# 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
|
|
|