unionflow-mobile-apps/README.md

UnionFlow Mobile 📱

Application mobile de gestion intégré pour les unions et associations Lions Club de Côte d'Ivoire

Fonctionnalités • Installation • Architecture • Documentation • Sécurité

---

📋 Description

UnionFlow Mobile est une application Flutter moderne conçue pour les membres des Lions Clubs de Côte d'Ivoire. Elle offre une suite complète de fonctionnalités pour la gestion quotidienne des unions et associations.

Modules Principaux

• 🧑‍🤝‍🧑 Membres - Gestion complète des adhérents avec KYC/LCB-FT
• 💰 Finances - Mutuelles d'épargne et crédit avec conformité anti-blanchiment
• 📅 Événements - Organisation et suivi des événements Lions
• 🤝 Solidarité - Système d'entraide entre membres
• 📊 Dashboard - Tableaux de bord en temps réel (WebSocket)
• 🔔 Notifications - Alertes en temps réel
• 📄 Rapports - Export PDF/Excel des données
• 🏢 Organisations - Gestion multi-niveaux des clubs

---

🚀 Installation

Prérequis

Outil	Version	Lien
Flutter	3.5.3+	flutter.dev
Dart	3.5.3+	Inclus avec Flutter
Android Studio	Latest	Pour Android
Xcode	14+	Pour iOS (macOS uniquement)
Git	Latest	git-scm.com

Cloner le Repository

git clone https://git.lions.dev/lionsdev/unionflow-mobile-apps.git
cd unionflow-mobile-apps

Installation des Dépendances

flutter pub get

Génération du Code (Build Runner)

# Génération complète
flutter pub run build_runner build --delete-conflicting-outputs

# Génération en watch mode (développement)
flutter pub run build_runner watch

Configuration des Environnements

L'application supporte 3 environnements: dev, staging, prod.

Développement (par défaut)

flutter run --dart-define=ENV=dev

Staging

flutter run --dart-define=ENV=staging \
  --dart-define=API_URL=https://api-staging.lions.dev \
  --dart-define=KEYCLOAK_URL=https://security-staging.lions.dev \
  --dart-define=WS_URL=wss://api-staging.lions.dev

Production

flutter run --dart-define=ENV=prod \
  --dart-define=API_URL=https://api.lions.dev \
  --dart-define=KEYCLOAK_URL=https://security.lions.dev \
  --dart-define=WS_URL=wss://api.lions.dev

Configuration par défaut (lib/core/config/environment.dart):

Environnement	API Base URL	Keycloak URL	WebSocket URL	Logs
dev	http://localhost:8085	http://localhost:8180	ws://localhost:8085	✅
staging	https://api-staging.lions.dev	https://security-staging.lions.dev	wss://api-staging.lions.dev	✅
prod	https://api.lions.dev	https://security.lions.dev	wss://api.lions.dev	❌

---

📦 Build pour Production

Android APK (Debug)

flutter build apk --debug --dart-define=ENV=dev

Android APK (Release - Production)

flutter build apk --release \
  --dart-define=ENV=prod \
  --dart-define=API_URL=https://api.lions.dev \
  --dart-define=KEYCLOAK_URL=https://security.lions.dev \
  --dart-define=WS_URL=wss://api.lions.dev \
  --obfuscate \
  --split-debug-info=build/app/outputs/symbols

Fichier généré: build/app/outputs/flutter-apk/app-release.apk

Android App Bundle (AAB - Google Play)

flutter build appbundle --release \
  --dart-define=ENV=prod \
  --dart-define=API_URL=https://api.lions.dev \
  --dart-define=KEYCLOAK_URL=https://security.lions.dev \
  --dart-define=WS_URL=wss://api.lions.dev \
  --obfuscate \
  --split-debug-info=build/app/outputs/symbols

Fichier généré: build/app/outputs/bundle/release/app-release.aab

iOS IPA (App Store)

flutter build ipa --release \
  --dart-define=ENV=prod \
  --dart-define=API_URL=https://api.lions.dev \
  --dart-define=KEYCLOAK_URL=https://security.lions.dev \
  --dart-define=WS_URL=wss://api.lions.dev \
  --obfuscate \
  --split-debug-info=build/ios/symbols

Fichier généré: build/ios/ipa/unionflow_mobile_apps.ipa

Scripts de Build Automatisés

Des scripts PowerShell sont disponibles dans scripts/build/:

# Android APK
.\scripts\build\build-android-release.ps1

# Android AAB
.\scripts\build\build-android-bundle.ps1

# iOS IPA
.\scripts\build\build-ios-release.ps1

---

🏗️ Architecture

Clean Architecture + BLoC Pattern

lib/
├── core/                       # Code partagé
│   ├── cache/                  # Système de cache (CacheService, Decorator)
│   ├── config/                 # Configuration environnements
│   ├── constants/              # Constantes app (timeouts, URLs, etc.)
│   ├── di/                     # Injection de dépendances (get_it)
│   ├── navigation/             # Routing (go_router)
│   ├── network/                # API client (Dio)
│   ├── storage/                # Cache managers
│   └── utils/                  # Logger, helpers
│
├── features/                   # Modules métier
│   ├── authentication/
│   │   ├── data/              # Data sources, repositories, models
│   │   ├── domain/            # Entities, use cases
│   │   └── presentation/      # BLoC, pages, widgets
│   ├── dashboard/
│   ├── members/
│   ├── contributions/
│   ├── events/
│   ├── solidarity/
│   ├── organizations/
│   ├── notifications/
│   ├── profile/
│   ├── reports/
│   └── admin/
│
├── shared/                     # Composants UI réutilisables
│   ├── design_system/         # Design tokens, thème
│   └── widgets/               # Widgets partagés (buttons, cards, etc.)
│
└── main.dart                   # Point d'entrée

Technologies Clés

Catégorie	Package	Version	Usage
State Management	flutter_bloc	^8.1.6	BLoC pattern
Dependency Injection	get_it	^7.7.0	Service locator
	injectable	^2.4.4	Code generation DI
Networking	dio	^5.7.0	HTTP client
	pretty_dio_logger	^1.4.0	Logging HTTP
Authentication	flutter_appauth	^6.0.2	OAuth/OIDC
	jwt_decoder	^2.0.1	JWT validation
	flutter_secure_storage	^9.2.2	Secure token storage
Cache	shared_preferences	^2.3.2	Preferences L2 cache
UI	fl_chart	^0.66.2	Graphiques
	cached_network_image	^3.4.1	Images avec cache
	shimmer	^3.0.0	Loading placeholders
Routing	go_router	^15.1.2	Navigation déclarative
WebSocket	web_socket_channel	^3.0.1	Temps réel
Export	pdf	^3.11.1	Export PDF
	excel	^4.0.6	Export Excel
	csv	^6.0.0	Export CSV

---

🎯 Fonctionnalités

1. Dashboard Temps Réel

• WebSocket pour mises à jour en temps réel
• Cache multi-niveaux (L1: mémoire, L2: disque)
• Auto-refresh via Kafka events
• Métriques: membres, cotisations, épargne, crédit
• Graphiques: Évolution mensuelle, répartition

2. Gestion des Membres

• CRUD complet avec pagination (20 items/page)
• Recherche avancée avec debounce (300ms)
• KYC/LCB-FT : niveau vigilance, statut, date vérification
• Fiche membre : photo, coordonnées, statut, historique
• Scroll infini (lazy loading)

3. Mutuelles Épargne & Crédit

• Dépôts/Retraits avec validation LCB-FT
• Transferts entre comptes
• Demandes de crédit avec workflow approbation
• Validation seuils anti-blanchiment (≤500k FCFA sans justificatif)
• Upload pièces justificatives (JPEG, PNG, PDF < 5MB)
• Calcul intérêts automatique

4. Événements

• Création/Modification d'événements
• Inscriptions en ligne
• Paiements intégrés
• Notifications push pour rappels

5. Solidarité

• Demandes d'aide entre membres
• Propositions d'aide avec budget
• Workflow validation par admin
• Historique transparent

6. Notifications

• Temps réel via WebSocket
• Push notifications (flutter_local_notifications)
• Badge de compteur non lues
• Filtres par type et statut

7. Rapports & Export

• PDF : reçus de paiement, rapports mensuels
• Excel : listes membres, cotisations
• CSV : export données brutes
• Share via share_plus

---

🔒 Sécurité

Documentation complète: SECURITE_PRODUCTION.md

Mesures Implémentées

✅ Stockage sécurisé

• FlutterSecureStorage (AES-256 Android, Keychain iOS)
• Tokens JWT chiffrés

✅ Authentification

• OAuth 2.0 / OIDC avec Keycloak
• JWT validation (expiry + issuer)
• Auto-refresh token avec verrouillage global
• Logout automatique si token invalide

✅ Network Security

• HTTPS obligatoire en production
• WSS (WebSocket Secure)
• Cleartext traffic désactivé (android:usesCleartextTrafficPermitted="false")
• Network security config (exceptions dev seulement)
• HTTP timeouts (15s connect/receive)

✅ Android Hardening

• ProGuard/R8 obfuscation activée
• Resource shrinking activé
• Backup désactivé (android:allowBackup="false")

✅ Logging Sécurisé

• Logs désactivés en production (AppConfig.enableLogging=false)
• Tokens jamais loggés
• Crash reporting (Sentry/Crashlytics ready)

✅ File Upload

• Validation taille (max 5MB)
• Validation MIME type (JPEG, PNG, PDF)
• Hash MD5 + SHA256 pour intégrité
• UUID pour noms de fichiers (no path traversal)

✅ OWASP Mobile Top 10 Compliant

TODO Production

⚠️ Keystore de production (Android)

• Générer keystore release
• Configurer android/key.properties
• Activer signingConfig = signingConfigs.release

📊 Crash Reporting (Recommandé)

• Intégrer Sentry ou Firebase Crashlytics
• Enregistrer AppLogger.onMonitoringReport

🔐 Certificate Pinning (Optionnel - Haute sécurité)

---

⚡ Performance

Documentation complète: OPTIMISATIONS_PERFORMANCE.md

Optimisations Implémentées

✅ Pagination

• Backend: 20 items/page
• Mobile: Scroll infini avec lazy loading

✅ Cache Multi-niveaux

• L1: Mémoire (instant)
• L2: Disque (persiste après redémarrage)
• TTL configurables (1min - 1h selon type de données)
• Cache-aside pattern avec CachedDatasourceDecorator

✅ Network

• Debounce recherche (300ms)
• Cached network images
• Chargement parallèle (Future.wait)

✅ UI

• ListView.builder (lazy loading)
• Const constructors partout
• Shimmer loading states

Résultats

Métrique	Avant	Après	Gain
Chargement dashboard	~4s	<1s (cache) / ~2s (sans cache)	75-50%
Scroll 1000+ items	30-40fps	60fps	100%
Recherche	Lag visible	Instantané	N/A

---

🧪 Tests

Tests Unitaires

flutter test

Tests d'Intégration

flutter test integration_test/

Tests E2E (Device/Emulator)

flutter drive --target=test_driver/app.dart

Coverage

flutter test --coverage
genhtml coverage/lcov.info -o coverage/html

---

📚 Documentation

Document	Description
ARCHITECTURE.md	Architecture Clean + BLoC détaillée
SECURITE_PRODUCTION.md	Mesures de sécurité complètes
OPTIMISATIONS_PERFORMANCE.md	Optimisations et cache
CONTRIBUTING.md	Guide de contribution
CHANGELOG.md	Historique des versions

---

🔧 Développement

Hot Reload

Flutter supporte le hot reload pour le développement rapide:

# Appuyer sur 'r' pour hot reload
# Appuyer sur 'R' pour hot restart
# Appuyer sur 'q' pour quitter
flutter run --dart-define=ENV=dev

Debug Mode

# Activer les logs verbeux
flutter run --dart-define=ENV=dev --verbose

# Performance overlay
flutter run --dart-define=ENV=dev --profile

Code Generation (Watch Mode)

# Auto-génération au changement de fichier
flutter pub run build_runner watch

Linting

# Analyse statique
flutter analyze

# Formatage code
flutter format lib/

---

🚀 Déploiement

Google Play Store (Android)

1. Build AAB:

   flutter build appbundle --release --dart-define=ENV=prod ...
   

2. Signer l'APK avec le keystore de production

3. Upload sur Google Play Console:

   • Internal testing → Closed testing → Open testing → Production

4. Remplir Store Listing:

   • Screenshots, description, icône, etc.

Apple App Store (iOS)

1. Build IPA:

   flutter build ipa --release --dart-define=ENV=prod ...
   

2. Ouvrir Xcode:

   open ios/Runner.xcworkspace
   

3. Archive & Upload via Xcode Organizer

4. App Store Connect:

   • TestFlight → App Review → Release

---

📄 Licence

Propriétaire - Lions Club Côte d'Ivoire

Tous droits réservés. Toute utilisation, modification ou distribution sans autorisation est strictement interdite.

---

👥 Équipe

UnionFlow Development Team

Lions Club Côte d'Ivoire - District 403 A1

---

📞 Support

Pour toute question ou problème:

• 📧 Email: support@lions.ci
• 🌐 Website: https://lions.dev
• 📱 WhatsApp: +225 XX XX XX XX XX

---

📊 Statistiques

---

Version actuelle: 1.0.0 Dernière mise à jour: 2026-03-15 Status: ✅ Production Ready

Made with ❤️ by Lions Club Côte d'Ivoire