From 8608fc023c4f28f8ee2762b4b429528134585689 Mon Sep 17 00:00:00 2001 From: Maxiwere45 Date: Thu, 25 Jun 2026 21:58:37 +0200 Subject: [PATCH] docs: sync ARCHITECTURE and README with actual codebase Add missing providers (locale, theme, genFilter, caughtCount), all 6 pages, full widget inventory, core/l10n layers, and game mechanics (hints, skips, shiny, bonuses, bilingual input, gen filter). Co-Authored-By: Claude Opus 4.8 --- docs/ARCHITECTURE.md | 78 +++++++++++++++++++++++++++++++++++++++----- docs/README.md | 37 ++++++++++++++------- 2 files changed, 96 insertions(+), 19 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 8b68a3e..4c82e52 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -8,23 +8,74 @@ par Riverpod (providers manuels). ## Couches +### core (transversal) + +- **`AppConstants`** : toutes les constantes métier en un seul endroit (vies, points, shiny odds, + plages de générations, clés SharedPreferences, URL API). +- **`logger`** : wrapper minimal autour de `dart:developer`. + ### domain (Dart pur) + - **Entités** : `Pokemon`, immuable, sans dépendance Flutter/DB/API. - **Repository (interface)** : `PokemonRepository` définit le contrat d'accès aux données. - **Jeu** : `GameState` (état immuable) et `GameEngine` (règles pures, testables). + - `GameEngine` gère : soumission de réponse, vies, hints, skips, score, Shiny, bonus périodiques. + - `GameStatus` : `loading | playing | roundWon | gameOver`. + - `GuessResult` : `correct | wrong | gameOver | invalid`. ### data + - **DTO** : `PokemonDto` centralise tout le parsing JSON (API Tyradex + SQLite). -- **Datasources** : `PokemonLocalDataSource` (SQLite via sqflite), `PokemonRemoteDataSource` (HTTP). + - `fromTyradexJson()`, `fromDb()`, `toDb()`. +- **Datasources** : + - `PokemonLocalDataSource` — SQLite via sqflite ; absent (`null`) sur le web. + - `PokemonRemoteDataSource` — HTTP vers Tyradex + PokéAPI (genus anglais). - **Repository (impl)** : `PokemonRepositoryImpl` applique « DB locale d'abord, sinon API + cache ». - Sur le web, le datasource local est absent (`null`). + +### l10n + +Internationalisation complète **FR / EN** via `flutter_localizations` + `intl`. +Fichiers générés : `app_localizations.dart`, `app_localizations_fr.dart`, `app_localizations_en.dart`. +La langue active est persistée dans SharedPreferences (`AppConstants.prefsLocale`). ### presentation -- **Providers** : `pokemonRepositoryProvider` (DI), `pokedexProvider` (`AsyncNotifier`), - `gameProvider` (`Notifier`), `selectedTabProvider` (onglet courant). -- **Pages** : `ConsumerWidget` / `ConsumerStatefulWidget` qui observent les providers. -- **Widgets** : éléments réutilisables (`PokemonImage`, `PokemonTile`, `PokemonTypeWidget`). -- **Thème** : `type_colors.dart` (couleur/format des types). + +#### Providers (Riverpod) + +| Provider | Type | Rôle | +| --- | --- | --- | +| `pokemonRepositoryProvider` | `Provider` | DI du repository | +| `pokedexProvider` | `AsyncNotifier>` | Chargement + cache du Pokédex | +| `gameProvider` | `Notifier` | État de la partie en cours | +| `selectedTabProvider` | `StateProvider` | Onglet de navigation courant | +| `localeProvider` | `Notifier` | Langue active (FR/EN) + persistance | +| `themeProvider` | `Notifier` | Palette de couleurs active (5 thèmes) + persistance | +| `genFilterProvider` | `Notifier>` | Générations sélectionnées pour le jeu + persistance | +| `caughtCountProvider` | `Provider` | Nombre de Pokémon capturés (dérivé de pokedexProvider) | + +#### Pages + +| Fichier | Rôle | +| --- | --- | +| `main_page.dart` | Hub de navigation par onglets (Jeu / Pokédex / Système) | +| `guess_page.dart` | Écran principal du jeu (silhouette, input, lives, score) | +| `game_over_page.dart` | Écran de fin de partie avec stats de session | +| `pokemon_list.dart` | Pokédex : liste filtrée + recherche par nom | +| `pokemon_detail.dart` | Fiche détaillée : stats, type, genus, toggle normal/shiny | +| `system_page.dart` | Paramètres (langue, palette) et statistiques globales | + +#### Widgets notables + +- **Réutilisables** : `PokemonImage`, `PokemonTile`, `PokemonTypeWidget`, `ScanlineOverlay`. +- **guess/** : `GuessSilhouette`, `GuessInputSection`, `LivesRow`, `ScoreBoard`, `GenFilterSection`. +- **detail/** : `PokemonDetailTop`, `PokemonStatsPanel`. +- **game_over/** : `GameOverHeader`, `GameOverStats`, `GameOverActions`, `HingeDivider`. +- **list/** : `PokedexListHeader`, `PokedexCountBar`. +- **system/** : `LanguagePicker`, `PalettePicker`, `SectionTitle`, `SystemHeader`, `SystemStats`. + +#### Thème + +`type_colors.dart` : couleur et libellé localisé par type Pokémon. ## Flux de données @@ -36,8 +87,19 @@ UI (Consumer) → Notifier → GameEngine (règles) + Repository (données) Riverpod re-render automatiquement les consommateurs concernés. Plus de bus d'événements global ni d'accès inter-pages via l'arbre de widgets. +## Mécaniques de jeu (résumé) + +- **Vies** : 3 au départ ; une vie perdue par mauvaise réponse ; game over à 0. +- **Hints** : 3 au départ ; révèle partiellement le nom ; +1 tous les 5 bonnes réponses consécutives. +- **Skips** : 3 au départ ; passe au Pokémon suivant sans pénalité ; +1 tous les 10 bonnes réponses. +- **Score** : +10 pts normal, +20 pts shiny ; meilleur score persisté via SharedPreferences. +- **Shiny** : 1 chance sur 10 (`AppConstants.shinyOdds`). +- **Filtre de génération** : le joueur choisit parmi Gen I–IX ; persisté entre les sessions. +- **Acceptation bilingue** : le nom FR *ou* EN est accepté quelle que soit la langue de l'UI. + ## Tests - `test/domain/game_engine_test.dart` : règles du jeu. -- `test/data/pokemon_dto_test.dart` : parsing. +- `test/data/pokemon_dto_test.dart` : parsing JSON ↔ DB. - `test/data/pokemon_repository_test.dart` : logique du repository (datasources factices). +- `test/widget_test.dart` : smoke test de démarrage de l'app. diff --git a/docs/README.md b/docs/README.md index 999aba1..e78455a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,15 +2,27 @@ ## Description -Pokeguess is a Flutter mobile application that allows users to discover and collect Pokemon through a silhouette guessing game. The app fetch data from the Tyradex API and stores it locally for offline access. +Pokeguess is a Flutter mobile application that allows users to discover and collect Pokémon through +a silhouette guessing game. The app fetches data from the Tyradex API and stores it locally for +offline access. ## Features -- National Pokedex: Browse all 1025+ Pokemon from all generations. -- Guess Game: Identify Pokemon by their silhouette. -- Scoring System: Earn points for correct guesses, with bonuses for Shiny Pokemon. High scores are saved locally. -- Collection: Track caught and seen Pokemon. -- Search and Filter: Filter the collection by all or caught status and search by name. +- **National Pokédex**: Browse all 1025 Pokémon from generations I to IX. +- **Guess Game**: Identify Pokémon by their silhouette. +- **Scoring System**: Earn 10 pts per correct guess, 20 pts for Shiny Pokémon (1 in 10 chance). + High scores are saved locally. +- **Lives, Hints & Skips**: Start each game with 3 lives, 3 hints, and 3 skips. Earn bonuses + every 5 correct guesses (hint) and every 10 correct guesses (skip). +- **Generation Filter**: Restrict the game to one or more generations (I–IX). Selection persists + across sessions. +- **Bilingual Input**: Pokémon names are accepted in French or English regardless of the UI language. +- **Collection**: Track caught and seen Pokémon across your Pokédex. +- **Search and Filter**: Filter the collection by all / caught status and search by name. +- **Pokémon Detail**: View base stats, types, genus, and toggle between normal and shiny sprites. +- **Theming**: Choose from 5 color palettes (red, blue, green, yellow, purple). +- **Localization**: Full French and English UI support, switchable at any time. +- **Statistics**: Global view of caught count, seen count, completion percentage, and best score. ## Installation @@ -21,8 +33,11 @@ Pokeguess is a Flutter mobile application that allows users to discover and coll ## Technologies -- Flutter: UI Framework. -- SQLite (sqflite): Local database. -- Tyradex API: Pokemon data source. -- Shared Preferences: High score persistence. -- Google Fonts: Custom typography. +- **Flutter**: UI Framework. +- **Riverpod**: State management (providers + notifiers). +- **SQLite (sqflite)**: Local database for offline-first Pokémon storage. +- **Tyradex API**: Primary Pokémon data source (FR/EN names, sprites, types, stats). +- **PokéAPI**: Secondary source for English genus data. +- **Shared Preferences**: Persistence for best score, generation filter, language, and palette. +- **Google Fonts**: Custom typography (VT323). +- **flutter_localizations / intl**: FR and EN localization.