# Système d'avatars Beta Testeur

## Vue d'ensemble

Ce système attribue automatiquement des avatars exclusifs aux joueurs qui s'inscrivent pendant la **période beta** (1 mois après le lancement du jeu).

## Modifications apportées

### 1. Période beta réduite de 3 mois à 1 mois

**Fichier modifié:** `rollerlogic-api/src/server/badges.ts`

- Avant : `const threeMonthsMs = 90 * 24 * 60 * 60 * 1000;` (3 mois)
- Maintenant : `const oneMonthMs = 30 * 24 * 60 * 60 * 1000;` (1 mois)

Le badge "early-tester" est maintenant attribué aux utilisateurs qui s'inscrivent dans le **1er mois** suivant le lancement.

### 2. Nouveau module : Attribution automatique des avatars beta

**Nouveau fichier:** `rollerlogic-api/src/server/beta-tester.ts`

Ce module contient 3 fonctions principales :

- `isInBetaPeriod()` : Vérifie si un utilisateur s'est inscrit pendant la période beta
- `grantBetaTesterAvatars()` : Attribue tous les avatars beta_testeur à un utilisateur
- `handleBetaTesterRegistration()` : Combine les deux fonctions précédentes

### 3. Intégration dans le processus d'inscription

**Fichier modifié:** `rollerlogic-api/src/routes/auth-routes.ts`

Lors de l'inscription d'un nouvel utilisateur :

```typescript
await ensureUserData(db, user.id);

// Attribution automatique des avatars beta_testeur si inscription pendant période beta
await handleBetaTesterRegistration(db, user.id, new Date());

await revokeRefreshTokensForUser(db, user.id);
```

### 4. Script SQL pour créer les avatars beta_testeur

**Nouveau fichier:** `add_beta_tester_avatars.sql`

mysql -u votre_user -p votre_database < add_beta_tester_avatars.sqlCe script ajoute **3 avatars exclusifs** "beta_testeur" dans la table `avatars` :

- `beta-testeur-01` → `beta_testeur/beta_test_1.png`
- `beta-testeur-02` → `beta_testeur/beta_test_2.png`
- `beta-testeur-03` → `beta_testeur/beta_test_3.png`
- Catégorie : `recompense`
- Prix : `0` (gratuits, attribués automatiquement)
- Condition de déblocage : `{"type": "beta_tester"}`

## Installation et déploiement

### Étape 1 : Exécuter le script de migration Python

**Méthode recommandée** - Exécution du script Python :

```bash
# Activer l'environnement virtuel
.\.venv\Scripts\Activate.ps1  # PowerShell Windows
# ou
source .venv/bin/activate      # Linux/Mac

# Exécuter le script de migration
python add_beta_tester_avatars.py
```

Le script :

- ✅ Vérifie si les avatars existent déjà
- ✅ Ajoute uniquement les avatars manquants
- ✅ Affiche un rapport détaillé
- ✅ Gère les erreurs automatiquement

**Alternative** - Script SQL manuel :

```bash
mysql -u votre_user -p votre_database < add_beta_tester_avatars.sql
```

**✅ Les fichiers d'images existent déjà :**

- `rollerlogic-api/private/beta_testeur/beta_test_1.png`
- `rollerlogic-api/private/beta_testeur/beta_test_2.png`
- `rollerlogic-api/private/beta_testeur/beta_test_3.png`

### Étape 2 : Rebuild et redéployer l'API

```bash
cd rollerlogic-api
npm run build
# Puis redémarrez votre serveur (PM2, Docker, etc.)
```

### Étape 3 : Vérifier la date de lancement

La période beta commence à partir de la `launch_date` configurée dans la table `app_config`.

Vérifiez la valeur actuelle :

```sql
SELECT config_value FROM app_config WHERE config_key = 'launch_date';
```

Si elle n'est pas définie ou vaut "unset", définissez-la :

```sql
UPDATE app_config
SET config_value = '2026-02-09T00:00:00Z'
WHERE config_key = 'launch_date';
```

## Fonctionnement

1. **Un utilisateur s'inscrit** via `/api/auth/register`
2. Le système vérifie automatiquement si `date_inscription <= launch_date + 30 jours`
3. Si OUI :
   - Tous les avatars avec le code `beta-testeur%` sont débloqués
   - Ils apparaissent dans l'inventaire du joueur
   - Le joueur peut les sélectionner immédiatement
4. Si NON :
   - Inscription normale sans avatars bonus

## Logs et débogage

Lors de l'attribution des avatars, le système log dans la console :

```
Avatars beta_testeur attribués à l'utilisateur 123 (3 avatars)
```

En cas d'erreur :

```
Erreur lors de l'attribution des avatars beta_testeur à l'utilisateur 123: [details]
```

## Vérification manuelle

### Vérifier si un utilisateur a les avatars beta

```sql
SELECT u.id, u.email, u.created_at, a.code, ua.unlocked_at
FROM users u
JOIN user_avatars ua ON ua.user_id = u.id
JOIN avatars a ON a.id = ua.avatar_id
WHERE a.code LIKE 'beta-testeur%'
ORDER BY u.id, a.code;
```

### Attribuer manuellement les avatars à un utilisateur spécifique

```sql
-- Remplacez 123 par l'ID de l'utilisateur
INSERT IGNORE INTO user_avatars (user_id, avatar_id, source, metadata, unlocked_at)
SELECT 123, id, 'manual_grant', '{"reason": "attribution_manuelle"}', NOW()
FROM avatars
WHERE code LIKE 'beta-testeur%';
```

## Notes importantes

- **Non rétroactif** : Seuls les nouveaux utilisateurs qui s'inscrivent APRÈS le déploiement bénéficient automatiquement de cette fonctionnalité
- **Une seule fois** : Les avatars sont attribués une seule fois à l'inscription (pas de vérification ultérieure)
- **Gratuits** : Ces avatars sont gratuits et ne nécessitent aucun achat
- **Exclusifs** : Après la période beta, ces avatars ne sont plus attribuables automatiquement

## Tests mis à jour

Le test du badge "early-tester" a été mis à jour dans :

```typescript
// rollerlogic-api/src/server/__tests__/badges.test.ts
it("badge early-tester pendant le 1er mois après launch_date", () => {
  // ...
});
```

Exécutez les tests :

```bash
cd rollerlogic-api
npm test
```

## Personnalisation

### Modifier la durée de la période beta

Dans `rollerlogic-api/src/server/beta-tester.ts`, ligne ~24 :

```typescript
const oneMonthMs = 30 * 24 * 60 * 60 * 1000; // 30 jours

// Pour 2 semaines :
// const twoWeeksMs = 14 * 24 * 60 * 60 * 1000;

// Pour 2 mois :
// const twoMonthsMs = 60 * 24 * 60 * 60 * 1000;
```

N'oubliez pas de mettre à jour également `badges.ts` avec la même valeur !

### Ajouter plus d'avatars beta

Ajoutez d'abord les fichiers images dans `rollerlogic-api/private/beta_testeur/`, puis ajoutez les entrées dans `add_beta_tester_avatars.sql` :

```sql
('beta-testeur-04', 'recompense', 'beta_testeur/beta_test_4.png', 0, '{"type": "beta_tester"}', 103),
('beta-testeur-05', 'recompense', 'beta_testeur/beta_test_5.png', 0, '{"type": "beta_tester"}', 104),
```

## Support

En cas de problème, vérifiez :

1. ✅ Les avatars existent dans la table `avatars`
2. ✅ Les fichiers images existent dans `/private/beta_testeur/`
3. ✅ La `launch_date` est correctement définie
4. ✅ L'API a été rebuild et redémarrée
5. ✅ Les logs du serveur pour les erreurs

---

**Date de création :** 9 février 2026  
**Auteur :** GitHub Copilot