veza/docs/UUID_DB_MIGRATION_PLAN.md

📐 UUID_DB_MIGRATION_PLAN.md

Date: 04/12/2025 Statut: PLAN VALIDÉ (En attente d'exécution) Objectif: Unification totale des IDs (UUID) et séparation des responsabilités (Schemas).

---

1. Schéma Cible & Stratégie de Séparation

Pour résoudre définitivement les conflits de nommage et de propriété, nous allons adopter une architecture Multi-Schéma PostgreSQL.

1.1 Architecture des Schémas

1. Schema public (Master: Backend Go)

   • Contient les données "Cœur" : users, auth, tracks, playlists.
   • Le service Go veza-backend-api possède les droits DDL (Migrations) sur ce schéma.
   • Tous les IDs (PK et FK) sont des UUID.

2. Schema chat (Master: Chat Rust)

   • Contient les données spécifiques au chat : conversations, messages, members.
   • Le service Rust veza-chat-server possède les droits DDL sur ce schéma uniquement.
   • Fait référence à public.users(id) via FK.
   • Isole la table messages du chat de la table messages legacy du backend.

1.2 Matrice des Types d'Identifiants

Entité	Table	Schema	PK Type	Géré par
User	users	public	UUID	Go
Track	tracks	public	UUID	Go
Playlist	playlists	public	UUID	Go
Conversation	conversations	chat	UUID	Rust
Message	messages	chat	UUID	Rust
Message (Legacy)	messages	public	UUID	Go

---

2. Migrations : Le Plan de Bataille

Les migrations seront exécutées séquentiellement.

Phase A : Consolidation du Backend (Go)

Ces migrations doivent être créées dans veza-backend-api/migrations/

1. 070_finish_secondary_tables_uuid.sql

   • But : Finaliser le travail laissé par migrations/001_migrate_ids_to_uuid_up.sql.
   • Action : Pour toutes les tables secondaires (contests, equipment, etc.) qui ont une colonne new_id :
     • Supprimer l'ancienne PK id (INT).
     • Renommer new_id -> id.
     • Mettre id en PRIMARY KEY.

2. 071_migrate_tracks_playlists_pk_to_uuid.sql

   • But : S'assurer que tracks et playlists ont bien leur PK en UUID (pas seulement la FK user_id).
   • Action : Même pattern : ajout colonne tmp UUID, migration data, switch PK.

3. 072_create_chat_schema.sql

   • Action : CREATE SCHEMA IF NOT EXISTS chat;
   • Action : Donner les droits nécessaires au user DB du chat server.

Phase B : Refonte du Chat Server (Rust)

Ces migrations remplacent le dossier veza-chat-server/migrations/ actuel.

1. 001_init_chat_schema.sql (Remplacement total)
   • Action : Créer les tables conversations, messages, conversation_members DANS le schéma chat.
   • Reference : REFERENCES public.users(id).
   • Nettoyage : NE PAS créer de table users.

---

3. Modifications du Code (Implementation Detail)

3.1 Backend API (Go)

• Models GORM :
  • Vérifier que tous les structs (User, Track, Playlist) utilisent le type uuid.UUID pour le champ ID et ont le tag `gorm:"type:uuid;default:uuid_generate_v4()"` (ou v5 pour users legacy).
  • Supprimer définitivement les champs ID uint ou int64.
• Handlers :
  • Nettoyer tout code convertissant string -> int pour les IDs. Utiliser uuid.Parse().

3.2 Chat Server (Rust)

• Configuration SQLx :
  • Forcer le search_path : ALTER DATABASE ... SET search_path TO chat, public;.
• Structs :
  • Le struct User (utilisé pour l'auth ou l'info user) doit être un "Read Model" mappé sur public.users.
  • Supprimer toute logique d'écriture dans users depuis Rust.
• Queries :
  • Remplacer SELECT ... FROM users par SELECT ... FROM public.users.
  • Remplacer SELECT ... FROM messages par SELECT ... FROM chat.messages.

---

4. Désarmement des Migrations du Chat

Actuellement, veza-chat-server contient des migrations conflictuelles.

Plan d'action :

1. Supprimer le contenu actuel de veza-chat-server/migrations/.
2. Créer une nouvelle migration 0001_init_chat.sql qui contient uniquement la DDL du schéma chat (conversations, messages).
3. Retirer toute instruction CREATE TABLE users.
4. Ajuster sqlx-data.json (le fichier de cache query verification) en le régénérant contre la nouvelle DB cible.

---

5. Nettoyage des Scripts & Hacks

Les scripts "béquilles" doivent disparaître pour garantir que le code est sain sans patch externe.

1. Supprimer :

   • scripts/fix-remaining-uuid-errors.sh (Le code doit compiler nativement).
   • scripts/migrate-handlers-to-uuid.sh.
   • scripts/migrate-models-to-uuid.sh.
   • migrations/ (le dossier root) : Son contenu utile est déplacé dans la migration 070 du backend.

2. Créer :

   • scripts/db-reset-clean.sh :
     1. Drop DB.
     2. Create DB.
     3. Run Backend Migrations (Go).
     4. Run Chat Migrations (Rust).
     5. Seed minimal data.

---

6. Vérification de Compatibilité

• Backend -> DB : Le Backend Go migre tout en UUID. Il n'attendra plus de SERIAL.
• Chat -> DB : Le Chat utilise son propre schéma. Il lit public.users (qui est UUID) via des FKs UUID. Compatibilité 100%.
• Collision Messages : Résolue par public.messages (legacy) vs chat.messages.

⏳ Prochaine Étape

Exécuter ce plan nécessite d'abord de générer les fichiers de migration SQL décrits en Phase A et B, puis d'appliquer les changements de code.