From 6395026e9ba26373b1c8a7ed398e95190b2fe0ce Mon Sep 17 00:00:00 2001 From: Rene Luria Date: Thu, 9 Jul 2026 16:22:58 +0200 Subject: [PATCH] docs: Rewrite README with full project documentation Replace the default Flutter starter README with comprehensive documentation covering features, prerequisites, installation, configuration, API endpoints, architecture, testing and build. --- README.md | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 143 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index a24f0ae..f2014e8 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,149 @@ -# myice_mobile +# MyIce Mobile -A new Flutter project. +Application mobile Flutter pour [MyIce](https://myice.parano.ch), la plateforme de gestion du club de hockey sur glace. Elle permet aux membres de consulter les calendriers de matchs, les convocations (joueurs et staff) et les détails des événements. -## Getting Started +## Fonctionnalités -This project is a starting point for a Flutter application. +- **Connexion via Infomaniak** — authentification OAuth via `flutter_web_auth_2` avec redirection sur le schéma personnalisé `myice://`. +- **Multi-comptes** — bascule entre plusieurs comptes/équipes, le compte sélectionné est persisté. +- **Calendrier des matchs** — liste les événements de type « Jeu » avec filtrage par tranche d'âge (`agegroup`) et sous-groupe. +- **Détail d'un match** — récapitulatif (type, lieu, horaires) et convocation : joueurs disponibles (poste, numéro, date de naissance) et personnel (rôle, nom). +- **Cache hors-ligne** — les événements et les filtres sont mis en cache par compte via `SharedPreferences` ; rafraîchissement manuel disponible. +- **Interface Material 3** en français. -A few resources to get you started if this is your first Flutter project: +## Pré-requis -- [Learn Flutter](https://docs.flutter.dev/get-started/learn-flutter) -- [Write your first Flutter app](https://docs.flutter.dev/get-started/codelab) -- [Flutter learning resources](https://docs.flutter.dev/reference/learning-resources) +- Flutter >= 3.1.0 (Dart SDK `>=3.1.0 <4.0.0`) +- Un éditeur compatible Dart ([liste des IDE](https://dart.dev/tools#ides-and-editors)) +- Accès au backend MyIce (`https://myice.parano.ch`) -For help getting started with Flutter development, view the -[online documentation](https://docs.flutter.dev/), which offers tutorials, -samples, guidance on mobile development, and a full API reference. +## Installation + +```bash +git clone git@gitea.parano.ch:herel/myice_mobile.git +cd myice_mobile +flutter pub get +``` + +### Génération des icônes de lancement + +```bash +dart run flutter_launcher_icons +``` + +L'icône source est `assets/icon/logo.png` (configurée dans `pubspec.yaml`). + +## Exécution + +```bash +flutter run # appareil par défaut +flutter run -d chrome # navigateur web +flutter run -d macos # macOS +``` + +## Configuration + +### URL du backend + +L'adresse de l'API est définie dans `lib/config/api_config.dart` : + +```dart +class ApiConfig { + static const String baseUrl = 'https://myice.parano.ch'; +} +``` + +### Schéma d'authentification + +L'authentification OAuth utilise le schéma d'URL personnalisé `myice://callback`. Il est déjà configuré : + +- **Android** — `android/app/src/main/AndroidManifest.xml` (activité `CallbackActivity`) +- **iOS / macOS** — `ios/Runner/Info.plist` (`CFBundleURLSchemes`) + +### Endpoints API consommés + +| Méthode | Route | Description | +| ------- | ------------------------------ | -------------------------------------------- | +| GET | `/login?redirect_uri=...` | Déclenche le flux OAuth Infomaniak | +| GET | `/userinfo` | Informations de l'utilisateur connecté | +| GET | `/accounts` | Liste des comptes/équipes accessibles | +| GET | `/schedule?account=` | Calendrier des événements d'un compte | +| GET | `/game/{gameId}?account=` | Détail d'un match et sa convocation | + +## Architecture + +Le projet suit une architecture en couches avec le pattern **Provider** pour la gestion d'état : + +``` +lib/ +├── main.dart # Point d'entrée, MultiProvider, routage racine +├── config/ +│ └── api_config.dart # Configuration de l'API (baseUrl) +├── models/ # Modèles de données (fromJson / toJson) +│ ├── account.dart +│ ├── event.dart +│ ├── event_detail.dart +│ ├── convocation.dart +│ ├── player.dart +│ ├── staff.dart +│ └── user_info.dart +├── services/ # Logique d'accès aux données +│ ├── api_service.dart # Client HTTP (Dio) + bearer token +│ ├── auth_service.dart # OAuth + stockage du token/compte +│ └── schedule_cache_service.dart # Cache des événements et filtres +├── providers/ # ChangeNotifiers (état réactif) +│ ├── auth_provider.dart +│ ├── schedule_provider.dart +│ └── event_detail_provider.dart +├── screens/ # Pages de l'application +│ ├── login_screen.dart +│ ├── schedule_screen.dart +│ └── event_detail_screen.dart +└── widgets/ # Composants UI réutilisables + ├── event_card.dart + ├── filter_dropdown.dart + └── loading_indicator.dart +``` + +### Flux de l'application + +1. Au démarrage, `AuthProvider.init()` restaure le token stocké et valide la session via `/userinfo`. +2. Si authentifié → `ScheduleScreen` : charge les comptes, puis le calendrier depuis le cache (ou rafraîchit si vide). +3. L'utilisateur filtre par tranche d'âge et sous-groupe (persistés par compte). +4. Un appui sur un événement ouvre `EventDetailScreen` qui charge `/game/{id}`. + +## Tests + +```bash +flutter test # suite de tests widget +flutter analyze # analyse statique (lints flutter_lints) +``` + +La configuration des lints se trouve dans `analysis_options.yaml`. + +## Build de production + +```bash +flutter build apk --release # Android +flutter build ios --release # iOS +flutter build macos --release # macOS +flutter build web --release # Web +``` + +## Dépendances principales + +| Package | Rôle | +| ------------------------- | ------------------------------------------- | +| `dio` | Client HTTP | +| `provider` | Gestion d'état réactive | +| `shared_preferences` | Stockage local (token, cache, filtres) | +| `flutter_web_auth_2` | Flux d'authentification OAuth (navigateur) | +| `intl` | Internationalisation | +| `flutter_launcher_icons` | Génération des icônes de lancement (dev) | + +## Contribuer + +1. Créer une branche depuis `main`. +2. Respecter les conventions de code (vérifier avec `flutter analyze`). +3. S'assurer que `flutter test` passe. +4. Ouvrir une merge request sur [Gitea](https://gitea.parano.ch/herel/myice_mobile).