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 <noreply@anthropic.com>
This commit is contained in:
parent
8f93a18a70
commit
8608fc023c
@ -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<GameState>`), `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<List<Pokemon>>` | Chargement + cache du Pokédex |
|
||||
| `gameProvider` | `Notifier<GameState>` | État de la partie en cours |
|
||||
| `selectedTabProvider` | `StateProvider<int>` | Onglet de navigation courant |
|
||||
| `localeProvider` | `Notifier<Locale>` | Langue active (FR/EN) + persistance |
|
||||
| `themeProvider` | `Notifier<AppPalette>` | Palette de couleurs active (5 thèmes) + persistance |
|
||||
| `genFilterProvider` | `Notifier<Set<int>>` | Générations sélectionnées pour le jeu + persistance |
|
||||
| `caughtCountProvider` | `Provider<int>` | 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.
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user