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.
This commit is contained in:
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user