docs: ajout du README.md après analyse complète du projet
This commit is contained in:
root
@@ -0,0 +1,372 @@
|
||||
<div align="center">
|
||||
|
||||
# 🎲 Boidelo
|
||||
|
||||
**L'application de jeux de soirée — questions, défis et cartes entre amis**
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</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* 🍻
|
||||
Reference in New Issue
Block a user