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.