<div align="center">

# 🎲 Boidelo

**L'application de jeux de soirée — questions, défis et cartes entre amis**

![Android](https://img.shields.io/badge/Android-7.0%2B-3DDC84?logo=android)
![Java](https://img.shields.io/badge/Java-8-orange?logo=java)
![Gradle](https://img.shields.io/badge/Gradle-8.12.0-02303A?logo=gradle)
![SDK](https://img.shields.io/badge/compileSdk-35-34A853?logo=android)
![License](https://img.shields.io/badge/License-Private-grey)

</div>

---

## 📖 Description

**Boidelo** est une application Android de jeux de soirée regroupant plusieurs mini-jeux autour d'un hub central. Entrez les noms des joueurs, choisissez un jeu, et laissez l'ambiance opérer !

L'application propose trois jeux distincts ainsi qu'un consulteur de règles de jeux d'ambiance populaires.

---

## 🎮 Jeux disponibles

### 1. Boidelo Classic

Le jeu original de questions et défis. Inspiré de jeux comme *King's Cup* ou *Never Have I Ever*.

- **150+ questions** préchargées depuis un fichier JSON, avec 10 catégories distinctes
- Questions dynamiques avec remplacement de variables (`<J1>`, `<J2>`, `<J3>`, `<variante>`)
- **Défis multi-manches** avec compte à rebours et message de fin
- Gestion intelligente : pas d'accumulation de défis simultanés
- Système de **gorgées** (boire / distribuer) avec accord grammatical automatique
- Catégorisation automatique des questions avec couleur de fond dynamique :
  - Ciblage, Classement, Jugement, Duel, Interactif, Défi, Variante, Caliente, Vote, Classique
- Paramètres personnalisables : nombre de questions, gorgées supplémentaires, durée des défis
- **Intégration OpenAI** (optionnelle) pour générer des questions via ChatGPT

### 2. 89++

Un jeu de cartes avec timer et défis spéciaux.

- Objectif : ne pas être celui qui atteint ou dépasse **89**
- Règles spéciales : Valet (−10), Dame (changement de sens), Roi (choix de valeur)
- Gorgées distribuées à chaque dizaine atteinte (70 = double !)
- **9 types de défis** aléatoires :
  - Changement de sens, Immunité, Gorgée surprise, Joker (passer son tour), Échange de mains, Double prochaine valeur, Compte mystère, Tour générale, Victime au choix
- Timer configurable pour les défis
- Suivi des gorgées par joueur

### 3. Papelito (Undercover)

Un jeu de déduction sociale. Trouvez l'Undercover avant qu'il ne soit trop tard !

- **20 paires de mots** préchargées (Pizza/Burger, Chat/Chien, Vin/Bière, etc.)
- Attribution aléatoire des rôles : **Civil**, **Undercover**, **Mr. White**
- Mécanique de **discussion → vote → élimination**
- Conditions de victoire :
  - Civils gagnent si tous les Undercovers sont éliminés
  - Undercovers gagnent s'ils sont en nombre ≥ aux Civils
- Gestion des égalités de votes (personne n'est éliminé)
- Machine à états avec validation des transitions légales

### 4. Règles de jeux

Consultez les règles des jeux d'ambiance populaires directement dans l'application.

---

## 🏗 Architecture

### Vue d'ensemble

Boidelo suit un pattern **Repository + Séparation des responsabilités**. Chaque jeu est isolé dans son propre package avec sa propre logique métier.

```
app/src/main/java/com/example/boidelov3/
├── hub/                           # Hub central
│   ├── GameSelectionActivity.java # Activité LAUNCHER (point d'entrée)
│   ├── adapter/
│   │   └── GameAdapter.java       # RecyclerView adapter
│   └── model/
│       └── GameInfo.java          # Modèle (nom, description, icône, type)
│
├── games/                         # Jeux isolés par package
│   ├── boideloclassic/            # Boidelo Classic
│   │   ├── BoideloClassicSetupActivity.java
│   │   ├── BoideloClassicParamsActivity.java
│   │   ├── BoideloClassicGameActivity.java
│   │   └── manager/
│   │       ├── BoideloPlayerManager.java
│   │       └── BoideloPlayerRowManager.java
│   ├── game89/                    # 89++
│   │   ├── Game89SetupActivity.java
│   │   ├── Game89GameActivity.java
│   │   ├── Game89Player.java      # Modèle joueur
│   │   └── Game89ChallengeManager.java  # Gestionnaire de défis
│   └── papelito/                  # Papelito (Undercover)
│       ├── PapelitoSetupActivity.java
│       ├── PapelitoGameActivity.java
│       ├── PapelitoResultActivity.java
│       ├── PapelitoResultAdapter.java
│       ├── PapelitoGame.java      # Logique complète du jeu
│       └── PapelitoPlayer.java    # Modèle joueur (Serializable)
│
├── data/                          # Couche d'accès aux données
│   ├── QuestionRepository.java    # Chargement JSON + SharedPreferences
│   ├── Result.java                # Wrapper type-safe succès/erreur
│   ├── PlayerStats.java           # Stats joueur (Parcelable)
│   └── QuestionCategory.java      # Catégorisation + couleurs
│
├── game/                          # Logique métier commune
│   └── GameEngine.java            # Moteur de jeu (pur Java)
│
├── utils/                         # Utilitaires
│   ├── ErrorHandler.java
│   ├── SecureConfig.java
│   ├── SoundManager.java
│   └── SoundGenerator.java
│
├── MainActivity.java              # Legacy (à supprimer)
├── Jeux.java                      # Legacy (à supprimer)
├── JeuxParametres.java            # Legacy (à supprimer)
├── EndGameActivity.java           # Legacy (à supprimer)
├── OpenAIService.java             # Service OpenAI
├── ChatGPTTask.java               # Task async OpenAI
├── DatabaseConnection.java        # Connexion PostgreSQL
├── Question.java                  # Modèle de question
├── Questions.java                 # Conteneur de questions (Gson)
├── PreferencesKeys.java           # Constantes SharedPreferences
└── BoideloAnimationUtils.java     # Animations UI
```

### Flux d'une partie

Chaque jeu suit le même schéma d'activité :

```
Hub (GameSelectionActivity)
  └─► Setup (saisie des joueurs)
        └─► Parameters (configuration, optionnel)
              └─► Game (partie en cours)
                    └─► End Game (statistiques & résultats)
```

### Pattern Result<T, E>

Le projet utilise un wrapper type-safe pour la gestion des erreurs, évitant les exceptions non contrôlées :

```java
Result<Questions, QuestionLoadException> result = repository.loadQuestions();
if (result.isSuccess()) {
    Questions questions = result.getData();
} else {
    Exception error = result.getError();
}
```

---

## 🛠 Stack technique

| Élément | Version / Détail |
|---|---|
| **Langage** | Java 8 |
| **Min SDK** | 24 (Android 7.0) |
| **Target / Compile SDK** | 35 (Android 15) |
| **Build system** | Gradle 8.12.0 + AGP 8.12.0 |
| **UI** | Material Design 3, AppCompat 1.7.0 |
| **Layout** | ConstraintLayout 2.2.0 |
| **Réseau** | OkHttp 4.12.0 |
| **JSON** | Gson 2.11.0 |
| **Base de données** | pgjdbc-ng 0.8.3 (PostgreSQL, actuellement inutilisé) |
| **Tests unitaires** | JUnit 4.13.2, Mockito 5.7.0, Robolectric 4.11.1 |
| **Tests UI** | AndroidX Test JUnit 1.2.1, Espresso 3.6.1 |

---

## 🧪 Tests

Le projet dispose de **11 classes de test** couvrant l'ensemble des jeux et des composants de données :

| Classe de test | Fichier |
|---|---|
| `GameEngineTest` | `game/GameEngineTest.java` (15 tests) |
| `ResultTest` | `data/ResultTest.java` (8 tests) |
| `PlayerStatsTest` | `data/PlayerStatsTest.java` |
| `QuestionCategoryTest` | `data/QuestionCategoryTest.java` |
| `QuestionTest` | `QuestionTest.java` |
| `QuestionsClassTest` | `QuestionsClassTest.java` |
| `BoideloPlayerManagerTest` | `games/boideloclassic/manager/BoideloPlayerManagerTest.java` |
| `Game89PlayerTest` | `games/game89/Game89PlayerTest.java` |
| `Game89ChallengeManagerTest` | `games/game89/Game89ChallengeManagerTest.java` |
| `PapelitoPlayerTest` | `games/papelito/PapelitoPlayerTest.java` |
| `PapelitoGameTest` | `games/papelito/PapelitoGameTest.java` |

---

## 🔨 Compilation et installation

### Prérequis

- **Android Studio** (recommandé) ou **JDK 17-21** + SDK Android
- Android SDK avec compileSdk 35

### Build depuis la ligne de commande

```bash
# Cloner le projet
git clone <url-du-repo>
cd boidelo

# Build
./gradlew build

# APK debug
./gradlew assembleDebug

# Installer sur un appareil connecté
adb install -r app/build/outputs/apk/debug/app-debug.apk
```

### Exécuter les tests

```bash
# Tous les tests unitaires
./gradlew test

# Tests instrumentés (appareil/émulateur requis)
./gradlew connectedAndroidTest

# Test spécifique
./gradlew test --tests com.example.boidelov3.game.GameEngineTest
```

> ⚠️ **Note :** Un bug connu avec Gradle 8.13 peut causer l'échec des tests unitaires en CLI. Utilisez Android Studio ou un JDK 17-21 pour contourner le problème.

### Clean

```bash
./gradlew clean
```

---

## 🎨 Interface

- **Material Design 3** avec composants modernes (MaterialCardView, TextInputLayout, etc.)
- **Mode sombre** avec thèmes dédiés (`values-night/`)
- **Animations fluides** : fade in/out, slide, color transition, button press/release
- **Feedback haptique** et effets sonores via `SoundManager` / `SoundGenerator`
- **Palette principale** : Violet (`#9395D3`) / Lavande (`#B3B7EE`) sur fond blanc cassé (`#FBF9FF`)
- Couleurs dynamiques par catégorie de question (10 couleurs distinctes)
- Toutes les activités en mode **portrait**

---

## 📁 Structure des ressources

```
app/src/main/res/
├── anim/          # 10 animations (slide, fade, button, color)
├── drawable/      # Icônes de jeux, boutons, fonds
├── layout/        # 19 layouts XML
│   ├── activity_game_selection.xml       # Hub principal
│   ├── activity_boidelo_classic_setup.xml
│   ├── activity_boidelo_classic_params.xml
│   ├── activity_boidelo_classic_game.xml
│   ├── activity_game89_setup.xml
│   ├── activity_game89_game.xml
│   ├── activity_papelito_setup.xml
│   ├── activity_papelito_game.xml
│   ├── activity_papelito_result.xml
│   ├── dialog_papelito_vote.xml
│   └── dialog_papelito_word_reveal.xml
├── values/        # Strings, couleurs, thèmes, styles
├── values-night/  # Variantes mode sombre
├── mipmap-*/      # Icônes launcher (mdpi → xxxhdpi)
└── xml/           # Backup rules, data extraction rules
```

---

## 📊 Données

Les questions de Boidelo Classic sont stockées dans `app/src/main/assets/question.json`. Chaque question contient :

- `id` — identifiant unique
- `question` — texte avec placeholders (`<J1>`, `<variante>`, `<manches>`)
- `gorger` — nombre de gorgées
- `distribution` / `recois` — flags pour boire ou distribuer
- `variante` — liste de variantes alternatives
- `manches` — nombre de manches pour les défis
- `arret` — message de fin de défi

---

## 🔐 Configuration

### Clé API OpenAI (optionnel)

Les clés sensibles sont stockées dans `local.properties` (non versionné) :

```properties
OPENAI_API_KEY=sk-votre-cle-ici
```

La classe `SecureConfig` fournit un accès sécurisé à ces valeurs.

### Base de données PostgreSQL

La connexion PostgreSQL est préparée mais le backend n'est pas encore en production. Les identifiants BuildConfig sont intentionnellement vides — l'usage d'une API backend est recommandé.

---

## 🚀 Ajouter un nouveau jeu

1. Créer un package sous `com.example.boidelov3.games.<nom_du_jeu>`
2. Implémenter les activités **Setup**, **Game** et **Result** (suivre le flux standard)
3. Ajouter une valeur à l'enum `GameInfo.GameType`
4. Enregistrer le jeu dans `GameSelectionActivity.setupGamesList()`
5. Ajouter le cas dans le `switch` de `GameSelectionActivity.onItemClick()`
6. Déclarer les activités dans `AndroidManifest.xml` avec `screenOrientation="portrait"`
7. Ajouter l'icône drawable `ic_<nom_du_jeu>.xml`
8. Écrire les tests unitaires correspondants

---

## 📝 Conventions

- **Langue métier** : français (`gorgees`, `manches`, `caliente`)
- **Code technique** : anglais (`allPlayers`, `activeManches`)
- **Interface utilisateur** : français
- **Clés SharedPreferences** : centralisées dans `PreferencesKeys.java`
- **Nommage layouts** : `activity_<jeu>_<écran>.xml`, `dialog_<jeu>_<usage>.xml`
- **Nommage strings** : préfixe par jeu (`papelito_`, `boidelo_`, `game89_`)

---

## 📋 Statut des fonctionnalités

| Fonctionnalité | Statut |
|---|---|
| Hub de sélection de jeux | ✅ Opérationnel |
| Boidelo Classic (150+ questions) | ✅ Opérationnel |
| 89++ (cartes + défis) | ✅ Opérationnel |
| Papelito / Undercover | ✅ Opérationnel |
| Règles de jeux | 🚧 En cours |
| Intégration OpenAI (questions IA) | 🚧 En développement |
| Connexion PostgreSQL | 🔧 Prête (backend requis) |
| Mode sombre | ✅ Opérationnel |
| Tests unitaires (11 classes) | ✅ Opérationnel |

---

## 📚 Documentation supplémentaire

- [`ANALYSE_CODE.md`](ANALYSE_CODE.md) — Analyse détaillée du code (ancienne architecture)
- [`README_ARCHITECTURE.md`](README_ARCHITECTURE.md) — Documentation de l'architecture Repository
- [`CLAUDE.md`](CLAUDE.md) — Guide de développement pour l'IA

---

## 📄 Licence

Projet privé — tous droits réservés.

---

*Boidelo — buvez responsable* 🍻