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.