modernisation api et test unitaire
This commit is contained in:
@@ -0,0 +1,509 @@
|
||||
# BoideloV3 - Documentation Architecture
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
Ce document décrit l'architecture mise en place pour l'application BoideloV3, un jeu de défi à boire pour Android.
|
||||
|
||||
L'architecture suit le pattern **Repository + Separation of Concerns**, permettant :
|
||||
- Une meilleure séparation des responsabilités
|
||||
- Un code testable unitairement
|
||||
- Une gestion d'erreurs robuste
|
||||
- Une maintenance facilitée
|
||||
|
||||
---
|
||||
|
||||
## Structure du projet
|
||||
|
||||
```
|
||||
app/src/main/java/com/example/boidelov3/
|
||||
├── data/ # Couche d'accès aux données
|
||||
│ ├── Result.java # Wrapper de résultat (succès/erreur)
|
||||
│ └── QuestionRepository.java # Repository pour les questions
|
||||
├── game/ # Logique métier du jeu
|
||||
│ └── GameEngine.java # Moteur de jeu
|
||||
├── ui/ # Activités et Fragments
|
||||
│ ├── Jeux.java # Activité principale du jeu
|
||||
│ ├── JeuxParametres.java # Écran de paramètres
|
||||
│ ├── EndGameActivity.java # Écran de fin de partie
|
||||
│ └── MainActivity.java # Écran d'accueil
|
||||
└── utils/ # Utilitaires
|
||||
├── DatabaseConnection.java # Connexion BDD PostgreSQL
|
||||
├── SoundManager.java # Gestion des sons
|
||||
└── BoideloAnimationUtils.java # Animations UI
|
||||
|
||||
app/src/test/java/com/example/boidelov3/
|
||||
├── data/
|
||||
│ └── ResultTest.java # Tests de Result
|
||||
└── game/
|
||||
└── GameEngineTest.java # Tests de GameEngine
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. Couche Data (données)
|
||||
|
||||
### 1.1 Result<T, E>
|
||||
|
||||
Wrapper type-safe pour représenter le résultat d'une opération qui peut échouer.
|
||||
|
||||
**Avantages :**
|
||||
- Remplace les exceptions par des valeurs de retour
|
||||
- Force le traitement des erreurs
|
||||
- Rend le code plus prévisible
|
||||
|
||||
**Utilisation :**
|
||||
|
||||
```java
|
||||
// Créer un résultat succès
|
||||
Result<String, Exception> success = Result.success("Données chargées");
|
||||
|
||||
// Créer un résultat erreur
|
||||
Result<String, Exception> failure = Result.failure(new Exception("Erreur de chargement"));
|
||||
|
||||
// Utiliser le résultat
|
||||
if (result.isSuccess()) {
|
||||
String data = result.getData();
|
||||
// Traiter les données
|
||||
} else {
|
||||
Exception error = result.getError();
|
||||
// Gérer l'erreur
|
||||
}
|
||||
|
||||
// Ou avec getOrElse
|
||||
String value = result.getOrElse("valeur par défaut");
|
||||
```
|
||||
|
||||
**Méthodes disponibles :**
|
||||
|
||||
| Méthode | Description |
|
||||
|---------|-------------|
|
||||
| `success(T data)` | Crée un résultat réussi |
|
||||
| `failure(E error)` | Crée un résultat d'erreur |
|
||||
| `isSuccess()` | Vrai si réussi |
|
||||
| `isFailure()` | Vrai si échoué |
|
||||
| `getData()` | Retourne les données (null si erreur) |
|
||||
| `getError()` | Retourne l'erreur (null si succès) |
|
||||
| `getOrNull()` | Retourne les données ou null |
|
||||
| `getOrElse(T default)` | Retourne les données ou une valeur par défaut |
|
||||
|
||||
---
|
||||
|
||||
### 1.2 QuestionRepository
|
||||
|
||||
Gère l'accès aux données des questions (JSON + SharedPreferences).
|
||||
|
||||
**Responsabilités :**
|
||||
- Charger les questions depuis `assets/question.json`
|
||||
- Suivre les questions déjà posées
|
||||
- Sauvegarder les statistiques de jeu
|
||||
|
||||
**Utilisation :**
|
||||
|
||||
```java
|
||||
// Créer le repository
|
||||
QuestionRepository repository = new QuestionRepository(context);
|
||||
|
||||
// Charger les questions
|
||||
Result<Questions, QuestionLoadException> result = repository.loadQuestions();
|
||||
|
||||
if (result.isSuccess()) {
|
||||
Questions questions = result.getData();
|
||||
List<Question> questionList = questions.getQuestions();
|
||||
// Utiliser les questions
|
||||
} else {
|
||||
QuestionLoadException error = result.getError();
|
||||
Log.e("TAG", "Erreur: " + error.getMessage());
|
||||
}
|
||||
|
||||
// Obtenir une question aléatoire non posée
|
||||
Result<Question, QuestionLoadException> randomResult =
|
||||
repository.getRandomUnaskedQuestion(questionList);
|
||||
|
||||
// Réinitialiser les questions posées
|
||||
repository.resetAskedQuestions();
|
||||
|
||||
// Sauvegarder les stats
|
||||
repository.saveGameStats(questionsPlayed, playersCount);
|
||||
```
|
||||
|
||||
**Méthodes principales :**
|
||||
|
||||
| Méthode | Description |
|
||||
|---------|-------------|
|
||||
| `loadQuestions()` | Charge toutes les questions depuis le JSON |
|
||||
| `getRandomUnaskedQuestion(List)` | Retourne une question non posée |
|
||||
| `markQuestionAsAsked(int)` | Marque une question comme posée |
|
||||
| `resetAskedQuestions()` | Réinitialise le suivi des questions |
|
||||
| `saveGameStats(int, int)` | Sauvegarde les statistiques |
|
||||
|
||||
---
|
||||
|
||||
## 2. Couche Game (logique métier)
|
||||
|
||||
### 2.1 GameEngine
|
||||
|
||||
Contient toute la logique du jeu, indépendante de l'UI.
|
||||
|
||||
**Responsabilités :**
|
||||
- Remplacement des variables dans les questions (`<J1>`, `<variante>`, etc.)
|
||||
- Gestion des manches actives
|
||||
- Sélection aléatoire de joueurs
|
||||
- Calcul des gorgées
|
||||
|
||||
**Utilisation :**
|
||||
|
||||
```java
|
||||
// Créer le moteur de jeu
|
||||
GameEngine engine = new GameEngine();
|
||||
|
||||
// Préparer les joueurs
|
||||
List<String> players = Arrays.asList("Alice", "Bob", "Charlie", "David");
|
||||
int addedGorgees = 2; // Paramètre de jeu
|
||||
|
||||
// Traiter une question
|
||||
Question rawQuestion = ...; // Question depuis le JSON
|
||||
ProcessedQuestion processed = engine.processQuestion(rawQuestion, players, addedGorgees);
|
||||
|
||||
// Afficher la question traitée
|
||||
textView.setText(Html.fromHtml(processed.question.getQuestion()));
|
||||
|
||||
// Vérifier si c'est une manche
|
||||
if (processed.isManche) {
|
||||
// C'est un défi à manches
|
||||
Log.d("Game", "Manche active: " + processed.question.getManchesRestantes());
|
||||
}
|
||||
|
||||
// Mettre à jour les manches (à chaque tour)
|
||||
MancheState mancheState = engine.updateManches();
|
||||
|
||||
if (mancheState.endMessage != null) {
|
||||
// Une manche s'est terminée
|
||||
Toast.makeText(context, mancheState.endMessage, Toast.LENGTH_LONG).show();
|
||||
} else if (mancheState.activeManche != null) {
|
||||
// Une manche est toujours active
|
||||
Question activeManche = mancheState.activeManche;
|
||||
int remaining = activeManche.getManchesRestantes();
|
||||
// Afficher le compteur de manches
|
||||
}
|
||||
|
||||
// Sélectionner des joueurs aléatoires
|
||||
List<String> selectedPlayers = engine.selectRandomPlayers(players, 3);
|
||||
// Retourne 3 joueurs uniques
|
||||
|
||||
// Vider toutes les manches (fin de partie)
|
||||
engine.clearManches();
|
||||
```
|
||||
|
||||
**Classes internes :**
|
||||
|
||||
| Classe | Description |
|
||||
|--------|-------------|
|
||||
| `ProcessedQuestion` | Conteneur pour une question traitée |
|
||||
| `MancheState` | État des manches après mise à jour |
|
||||
|
||||
**Méthodes principales :**
|
||||
|
||||
| Méthode | Description |
|
||||
|---------|-------------|
|
||||
| `processQuestion(Question, List, int)` | Traite une question (remplace variables) |
|
||||
| `selectRandomPlayers(List, int)` | Sélectionne n joueurs uniques |
|
||||
| `updateManches()` | Met à jour et retourne l'état des manches |
|
||||
| `hasActiveManche()` | Vrai si une manche est active |
|
||||
| `clearManches()` | Vide toutes les manches actives |
|
||||
|
||||
---
|
||||
|
||||
## 3. Utilisation recommandée dans une Activity
|
||||
|
||||
Voici comment intégrer les nouvelles classes dans `Jeux.java` :
|
||||
|
||||
```java
|
||||
public class Jeux extends AppCompatActivity {
|
||||
private QuestionRepository repository;
|
||||
private GameEngine gameEngine;
|
||||
private List<String> players;
|
||||
|
||||
@Override
|
||||
protected void onCreate(Bundle savedInstanceState) {
|
||||
super.onCreate(savedInstanceState);
|
||||
setContentView(R.layout.activity_jeux);
|
||||
|
||||
// Initialiser les composants
|
||||
repository = new QuestionRepository(this);
|
||||
gameEngine = new GameEngine();
|
||||
players = getIntent().getStringArrayListExtra("EXTRA_LIST_JOUEUR");
|
||||
|
||||
// Charger les questions
|
||||
loadAndStartGame();
|
||||
}
|
||||
|
||||
private void loadAndStartGame() {
|
||||
Result<Questions, QuestionRepository.QuestionLoadException> result =
|
||||
repository.loadQuestions();
|
||||
|
||||
if (result.isSuccess()) {
|
||||
Questions questions = result.getData();
|
||||
displayNextQuestion(questions);
|
||||
} else {
|
||||
Toast.makeText(this, "Erreur de chargement", Toast.LENGTH_SHORT).show();
|
||||
finish();
|
||||
}
|
||||
}
|
||||
|
||||
private void displayNextQuestion(Questions allQuestions) {
|
||||
// Obtenir une question aléatoire
|
||||
Result<Question, QuestionRepository.QuestionLoadException> result =
|
||||
repository.getRandomUnaskedQuestion(allQuestions.getQuestions());
|
||||
|
||||
if (result.isFailure()) {
|
||||
endGame();
|
||||
return;
|
||||
}
|
||||
|
||||
Question question = result.getData();
|
||||
|
||||
// Traiter la question avec le moteur de jeu
|
||||
int addedGorgees = getIntent().getIntExtra("EXTRA_AJOUT_GORGEE", 0);
|
||||
GameEngine.ProcessedQuestion processed =
|
||||
gameEngine.processQuestion(question, players, addedGorgees);
|
||||
|
||||
// Afficher
|
||||
questionTextView.setText(Html.fromHtml(processed.question.getQuestion()));
|
||||
|
||||
// Gérer les manches
|
||||
GameEngine.MancheState mancheState = gameEngine.updateManches();
|
||||
if (mancheState.endMessage != null) {
|
||||
Toast.makeText(this, mancheState.endMessage, Toast.LENGTH_LONG).show();
|
||||
}
|
||||
}
|
||||
|
||||
private void endGame() {
|
||||
repository.saveGameStats(totalQuestions, players.size());
|
||||
// Naviguer vers EndGameActivity
|
||||
}
|
||||
|
||||
@Override
|
||||
protected void onDestroy() {
|
||||
super.onDestroy();
|
||||
gameEngine.clearManches();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Tests unitaires
|
||||
|
||||
Les tests sont situés dans `app/src/test/java/`.
|
||||
|
||||
### 4.1 Exécuter les tests
|
||||
|
||||
**Depuis Android Studio :**
|
||||
1. Clic droit sur la classe de test
|
||||
2. Select "Run 'ResultTest'"
|
||||
|
||||
**Depuis la ligne de commande :**
|
||||
```bash
|
||||
./gradlew testDebugUnitTest
|
||||
```
|
||||
|
||||
*Note : Avec Gradle 8.13, il y a un bug connu. Utilisez Android Studio ou un JDK 17-21.*
|
||||
|
||||
### 4.2 Résultat des tests
|
||||
|
||||
| Classe | Tests | Couverture |
|
||||
|--------|-------|------------|
|
||||
| `ResultTest` | 8 tests | 100% Result |
|
||||
| `GameEngineTest` | 15 tests | Logique jeu complète |
|
||||
|
||||
---
|
||||
|
||||
## 5. Connexion Base de Données
|
||||
|
||||
### 5.1 DatabaseConnection
|
||||
|
||||
Classe moderne pour la connexion PostgreSQL (remplace l'obsolète AsyncTask).
|
||||
|
||||
**Utilisation :**
|
||||
|
||||
```java
|
||||
DatabaseConnection dbConnection = new DatabaseConnection();
|
||||
|
||||
dbConnection.connectAsync(new DatabaseConnection.ConnectionCallback() {
|
||||
@Override
|
||||
public void onSuccess(PGConnection connection) {
|
||||
// Connexion réussie - thread principal (UI)
|
||||
Log.d("Database", "Connecté !");
|
||||
// Utiliser la connexion...
|
||||
}
|
||||
|
||||
@Override
|
||||
public void onFailure(Exception error) {
|
||||
// Erreur - thread principal (UI)
|
||||
Log.e("Database", "Erreur de connexion", error);
|
||||
Toast.makeText(context, "Erreur: " + error.getMessage(), Toast.LENGTH_SHORT).show();
|
||||
}
|
||||
});
|
||||
|
||||
// Dans onDestroy()
|
||||
@Override
|
||||
protected void onDestroy() {
|
||||
super.onDestroy();
|
||||
dbConnection.shutdown(); // Libérer les ressources
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 Configuration
|
||||
|
||||
Les identifiants de connexion sont dans `local.properties` (non versionné) :
|
||||
|
||||
```properties
|
||||
# Database credentials (DO NOT COMMIT)
|
||||
db.url=jdbc:postgresql://your-host:5432/database
|
||||
db.user=your-username
|
||||
db.password=your-password
|
||||
```
|
||||
|
||||
Ils sont injectés automatiquement dans `BuildConfig` par `build.gradle`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Bonnes pratiques
|
||||
|
||||
### 6.1 Gestion des erreurs
|
||||
|
||||
```java
|
||||
// ✅ BON - Utiliser Result
|
||||
Result<Data, Exception> result = repository.loadQuestions();
|
||||
if (result.isSuccess()) {
|
||||
// Traiter les données
|
||||
} else {
|
||||
// Gérer l'erreur
|
||||
}
|
||||
|
||||
// ❌ Mauvais - Exceptions non gérées
|
||||
try {
|
||||
Data data = repository.loadQuestions();
|
||||
} catch (Exception e) {
|
||||
// Peut être oublié...
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 Séparation des responsabilités
|
||||
|
||||
```java
|
||||
// ✅ BON - Logique dans GameEngine
|
||||
ProcessedQuestion processed = gameEngine.processQuestion(question, players, addedGorgees);
|
||||
|
||||
// ❌ Mauvais - Logique dans l'Activity
|
||||
String text = question.getQuestion().replace("<J1>", players.get(0));
|
||||
// ... logique compliquée dans l'UI
|
||||
```
|
||||
|
||||
### 6.3 Cycle de vie
|
||||
|
||||
```java
|
||||
@Override
|
||||
protected void onDestroy() {
|
||||
super.onDestroy();
|
||||
// Toujours nettoyer les ressources
|
||||
if (dbConnection != null) {
|
||||
dbConnection.shutdown();
|
||||
}
|
||||
if (gameEngine != null) {
|
||||
gameEngine.clearManches();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Diagramme de flux
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Jeux Activity │ (UI)
|
||||
└────────┬────────┘
|
||||
│
|
||||
├── loadQuestions() ──────► QuestionRepository
|
||||
│ │
|
||||
│ ├── Lire JSON
|
||||
│ └── Retourner Result<Questions>
|
||||
│
|
||||
├── processQuestion() ──────► GameEngine
|
||||
│ │
|
||||
│ ├── Remplacer <J1>, <J2>, etc.
|
||||
│ ├── Remplacer <variante>
|
||||
│ ├── Gérer <manches>
|
||||
│ └── Retourner ProcessedQuestion
|
||||
│
|
||||
└── Afficher dans TextView
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Migration depuis l'ancien code
|
||||
|
||||
### Ancienne méthode (AsyncTask)
|
||||
|
||||
```java
|
||||
// Ancien code - À NE PAS UTILISER
|
||||
new DatabaseConnection().execute();
|
||||
|
||||
@Override
|
||||
protected void onPostExecute(Connection connection) {
|
||||
if (connection != null) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Nouvelle méthode (ExecutorService + Callback)
|
||||
|
||||
```java
|
||||
// Nouveau code - Recommandé
|
||||
DatabaseConnection db = new DatabaseConnection();
|
||||
db.connectAsync(new ConnectionCallback() {
|
||||
@Override
|
||||
public void onSuccess(PGConnection connection) {
|
||||
// Succès
|
||||
}
|
||||
|
||||
@Override
|
||||
public void onFailure(Exception error) {
|
||||
// Erreur
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Dépannage
|
||||
|
||||
### Problème : Les tests unitaires échouent avec Gradle 8.13
|
||||
|
||||
**Solution :** Exécutez les tests depuis Android Studio, ou utilisez un JDK 17-21 au lieu de Java 24.
|
||||
|
||||
### Problème : "Cannot resolve BuildConfig"
|
||||
|
||||
**Solution :** Faites un Build > Rebuild Project pour régénérer BuildConfig.
|
||||
|
||||
### Problème : "QuestionRepository.QuestionLoadException"
|
||||
|
||||
**Solution :** Importez la classe interne :
|
||||
```java
|
||||
import com.example.boidelov3.data.QuestionRepository.QuestionLoadException;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Ressources supplémentaires
|
||||
|
||||
- [Android Guide to App Architecture](https://developer.android.com/topic/architecture)
|
||||
- [Repository Pattern](https://developer.android.com/topic/architecture/data-layer)
|
||||
- [Result Type in Java](https://www.baeldung.com/java-result-type)
|
||||
|
||||
---
|
||||
|
||||
**Dernière mise à jour :** 31 décembre 2025
|
||||
**Version :** 3.0
|
||||
Reference in New Issue
Block a user