veza/docs/UUID_DB_CARTOGRAPHY.md

🗺️ UUID_DB_CARTOGRAPHY.md

Date: 04/12/2025 Statut: 🔴 ALERTE CRITIQUE (Schisme de Données) Contexte: Analyse post-mortem de la migration INT vers UUID et du conflit de propriété des données entre Backend (Go) et Chat (Rust).

---

1. État des Lieux : La Guerre des Schémas

Il existe trois sources de vérité concurrentes pour la définition de la base de données, créant un état incohérent.

Entité	Source de Vérité	Type ID Utilisateur	Méthode de Génération	Colonnes Clés
Backend API (Go)	veza-backend-api/migrations/	UUID (Migré)	uuid_generate_v5 (Déterministe depuis INT)	username, email, password_hash
Chat Server (Rust)	veza-chat-server/migrations/	UUID (Natif)	gen_random_uuid() (v4 Aléatoire)	display_name, last_seen, avatar_url
Root Scripts	migrations/	UUID (Mixte)	uuid_generate_v4 (v4 Aléatoire)	N/A (Tables secondaires)

🚨 Le Conflit "Users"

La table users est définie différemment par les deux services majeurs.

• Backend (Go) migre les anciens IDs : 123 -> UUID-v5-du-123.
• Chat (Rust) crée de nouveaux users : UUID-v4-Random.

Conséquence : Si le Backend et le Chat partagent la même DB (ce qui est le cas en prod), le Chat Server va échouer car il attend des colonnes (display_name) qui n'existent pas dans la version Backend (first_name/last_name), ou vice-versa.

---

2. Cartographie des Tables & IDs

Tables Principales (Gérées par veza-backend-api)

Ces tables ont subi la migration 047 (Destructive).

Table	Type ID PK	Type FK User	État Migration	Observation
users	UUID	N/A	✅ Terminée	PK renommée de id_uuid à id.
tracks	SERIAL	UUID	✅ Terminée	FK user_id est UUID. PK reste SERIAL ? (À vérifier)
playlists	SERIAL	UUID	✅ Terminée	FK user_id est UUID.
messages (Legacy)	SERIAL	UUID	✅ Terminée	Table messages du backend (pas celle du Chat Server).

Tables "Chat" (Gérées par veza-chat-server)

Ces tables sont définies dans 001_create_clean_database.sql (Rust).

Table	Type ID PK	Type FK User	État	Conflit ?
conversations	UUID	UUID	Natif	OK
messages (New)	UUID	UUID	Natif	⚠️ Conflit de nom avec messages du Backend
conversation_members	Composite	UUID	Natif	OK

Tables Secondaires (Gérées par migrations/ root)

Tables touchées par 001_migrate_ids_to_uuid_up.sql.

Table	Type ID PK	État	Observation
contests	UUID (new_id)	⚠️ Partiel	Colonne new_id ajoutée mais PK pas encore switchée ?
equipment	UUID (new_id)	⚠️ Partiel	Idem.
user_profiles	UUID (new_id)	⚠️ Partiel	Doublon potentiel avec users ?

---

3. Analyse des Migrations Exécutées

Migration Critique : veza-backend-api/.../047_migrate_users_id_to_uuid.sql

C'est la migration de référence. Elle est destructrice (DROP COLUMN id).

• Points Forts : Utilise uuid_generate_v5(namespace, old_id). Cela garantit que l'ID 42 devient toujours le même UUID. C'est excellent pour la consistance.
• Points Faibles : Elle suppose qu'elle est la seule à toucher à la DB.

Migration "Root" : migrations/001_migrate_ids_to_uuid_up.sql

Semble être une tentative de rattrapage pour les tables oubliées par la migration 047.

• Problème : Elle ajoute new_id mais ne semble pas (dans l'extrait lu) faire le DROP et RENAME final. Elle laisse la DB dans un état intermédiaire (id INT + new_id UUID).

Scripts Shell de "Fix"

• scripts/fix-remaining-uuid-errors.sh : Un script "Find & Replace" brutal (sed) sur le code Go.
  • Preuve que le code Go n'a pas été refactoré proprement mais "patché" pour accepter les UUIDs (remplacement de 0 par uuid.Nil).

---

4. Source of Truth (Proposition de Résolution)

Pour résoudre le schisme, nous devons établir une hiérarchie stricte.

👑 Maître du Schéma Global : veza-backend-api

Le Backend Go contient l'historique et la complexité métier (Auth, Roles, Profils). Il DOIT posséder la table users.

🚫 Interdit au Chat Server

Le veza-chat-server NE DOIT PAS :

1. Créer la table users.
2. Gérer ses propres migrations pour users.
3. Avoir une table messages qui porte le même nom que celle du Backend (si elles sont dans le même schema).

✅ Actions Requises (pour la phase de correction)

1. Aligner le schéma User : Le Chat Server (Rust) doit adapter son modèle struct User pour correspondre aux colonnes réelles du Backend (first_name vs display_name).
2. Renommage Tables : La table messages du Chat Server doit être renommée chat_messages pour éviter la collision avec les messages legacy du Backend.
3. Nettoyage Root : Finir ou reverter la migration migrations/001_migrate_ids_to_uuid_up.sql (état new_id hybride dangereux).

---

5. Conclusion

Le chaos des IDs est en réalité un Chaos de Gouvernance. Deux équipes (ou deux esprits) ont travaillé en parallèle : l'une migrant l'existant (Go), l'autre construisant le futur (Rust), sans se synchroniser sur la couche de données partagée.