Refactoring - Version OK
This commit is contained in:
dahoud
218
MIGRATION_UUID.md
Normal file
218
MIGRATION_UUID.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user