# Scripts de Migration - Système de Packs d'Avatars

## 🎯 Objectif

Ces scripts permettent de configurer le système de packs d'avatars premium pour RollerLogic, en particulier la table `pack_avatars` qui est **essentielle** pour le fonctionnement du webhook Stripe.

## ⚠️ Problème Résolu

Sans la table `pack_avatars`, le webhook Stripe ne peut pas débloquer les avatars lors de l'achat d'un pack. L'utilisateur paye mais ne reçoit rien.

## 📝 Scripts Disponibles

### 1. `setup_avatar_packs_complete.py` ⭐ **RECOMMANDÉ**

**Script tout-en-un** qui effectue toute la configuration automatiquement.

```bash
python python/migrations/setup_avatar_packs_complete.py
```

**Ce qu'il fait:**

- ✅ Vérifie que le pack 'cool' existe dans `avatar_packs`
- ✅ Crée les 19 avatars 'cool_01' à 'cool_19' s'ils n'existent pas
- ✅ Crée la table `pack_avatars`
- ✅ Lie les avatars au pack
- ✅ Valide la configuration complète

**Pré-requis:**

- Le pack 'cool' doit exister dans `avatar_packs` (créé via `npm run db:init`)
- Module Python: `mysql-connector-python`

---

### 2. `create_cool_avatars.py`

Crée uniquement les 19 avatars du pack 'cool' dans la table `avatars`.

```bash
python python/migrations/create_cool_avatars.py
```

**Utiliser si:**

- Vous voulez créer les avatars séparément
- Les avatars cool sont manquants

**Ce qu'il crée:**

- 19 avatars avec codes: `cool_01`, `cool_02`, ..., `cool_19`
- Catégorie: `achat`
- Chemins: `avatars/cool/cool_XX.png`

---

### 3. `create_pack_avatars_table.py`

Crée la table `pack_avatars` et lie les avatars existants au pack 'cool'.

```bash
python python/migrations/create_pack_avatars_table.py
```

**Utiliser si:**

- Les avatars cool existent déjà
- Vous voulez seulement créer la table et les liens

**Pré-requis:**

- Les avatars avec code `cool_*` doivent exister dans `avatars`
- Le pack 'cool' doit exister dans `avatar_packs`

---

## 🚀 Utilisation Rapide

### Installation des dépendances

```bash
pip install mysql-connector-python
```

### Exécution (méthode simple)

```bash
# Tout faire en une seule commande
python python/migrations/setup_avatar_packs_complete.py
```

### Exécution (étape par étape)

```bash
# 1. Créer les avatars
python python/migrations/create_cool_avatars.py

# 2. Créer la table et les liens
python python/migrations/create_pack_avatars_table.py
```

---

## 🔍 Vérification

Après l'exécution, vérifiez que tout est en place:

```sql
-- Nombre d'avatars cool
SELECT COUNT(*) FROM avatars WHERE code LIKE 'cool_%';
-- Résultat attendu: 19

-- Table pack_avatars existe
SHOW TABLES LIKE 'pack_avatars';

-- Nombre de liens dans pack_avatars
SELECT COUNT(*) FROM pack_avatars WHERE pack_id = 'cool';
-- Résultat attendu: 19

-- Vérifier la liste complète
SELECT pa.pack_id, pa.avatar_id, pa.display_order, a.code
FROM pack_avatars pa
JOIN avatars a ON pa.avatar_id = a.id
WHERE pa.pack_id = 'cool'
ORDER BY pa.display_order;
```

---

## 📊 Structure Créée

### Table `pack_avatars`

```sql
CREATE TABLE `pack_avatars` (
  `pack_id` varchar(50) NOT NULL,
  `avatar_id` int NOT NULL,
  `display_order` int DEFAULT 0,
  PRIMARY KEY (`pack_id`, `avatar_id`),
  KEY `idx_pack_avatars_pack` (`pack_id`),
  KEY `idx_pack_avatars_avatar` (`avatar_id`),
  CONSTRAINT `pack_avatars_ibfk_1` FOREIGN KEY (`pack_id`)
    REFERENCES `avatar_packs` (`pack_id`) ON DELETE CASCADE,
  CONSTRAINT `pack_avatars_ibfk_2` FOREIGN KEY (`avatar_id`)
    REFERENCES `avatars` (`id`) ON DELETE CASCADE
);
```

### Données Insérées

- **19 avatars** dans la table `avatars`:
  - Codes: `cool_01` à `cool_19`
  - Catégorie: `achat`
  - Chemins: `avatars/cool/cool_XX.png`

- **19 liens** dans `pack_avatars`:
  - `pack_id = 'cool'`
  - `avatar_id` = ID des avatars cool
  - `display_order` = 1 à 19

---

## ⚙️ Configuration

Les scripts utilisent `db_config.py` pour se connecter à la base OVH.

Assurez-vous que votre fichier `.env` contient:

```env
DB_HOST=gb9434-001.eu.clouddb.ovh.net
DB_PORT=35670
DB_USER=votre_user
DB_PASSWORD=votre_password
DB_NAME=RollerLogic
```

---

## 🐛 Dépannage

### Erreur: "Module mysql-connector-python requis"

```bash
pip install mysql-connector-python
```

### Erreur: "Le pack 'cool' n'existe pas"

Exécutez d'abord:

```bash
cd rollerlogic-api
npm run db:init
```

Ou exécutez manuellement:

```bash
mysql -h <host> -P 35670 -u <user> -p RollerLogic < sql/migrations/add_avatar_packs.sql
```

### Erreur: "Foreign key constraint fails"

Assurez-vous que:

1. La table `avatar_packs` existe
2. Le pack 'cool' existe dans `avatar_packs`
3. Les avatars existent dans la table `avatars`

---

## ✅ Résultat Attendu

Après la migration réussie:

```
✅ MIGRATION COMPLÈTE RÉUSSIE
Pack: Pack Avatars Cool
Prix: 23.99€
Avatars configurés: 19
Avatars annoncés: 19
✅ Configuration 100% cohérente

Le webhook Stripe peut maintenant débloquer les avatars.
```

---

## 📚 Documentation Associée

- [AUDIT_BASE_OVH_2026-02-09.md](../../AUDIT_BASE_OVH_2026-02-09.md) - Audit complet de la base
- [sql/migrations/add_pack_avatars.sql](../../sql/migrations/add_pack_avatars.sql) - Migration SQL
- [rollerlogic-api/src/routes/webhook-routes.ts](../../rollerlogic-api/src/routes/webhook-routes.ts) - Code webhook

---

## 🎯 Impact

Cette migration corrige un bug critique où les achats de packs d'avatars étaient payés mais les avatars n'étaient pas débloqués pour l'utilisateur.

**Avant:** 💸 Paiement OK ➜ ❌ Aucun avatar reçu  
**Après:** 💸 Paiement OK ➜ ✅ 19 avatars débloqués