497 lines
15 KiB
Markdown
497 lines
15 KiB
Markdown
# UnionFlow Client - Application Web de Gestion
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Application web moderne de gestion pour organisations Lions Club, basée sur Quarkus, Jakarta EE 10, JSF 4.0 et PrimeFaces 14 avec le thème Freya.
|
|
|
|
## 📋 Table des Matières
|
|
|
|
- [Caractéristiques](#caractéristiques)
|
|
- [Architecture](#architecture)
|
|
- [Prérequis](#prérequis)
|
|
- [Installation](#installation)
|
|
- [Configuration](#configuration)
|
|
- [Lancement](#lancement)
|
|
- [Sécurité](#sécurité)
|
|
- [Tests](#tests)
|
|
- [Déploiement](#déploiement)
|
|
- [Support](#support)
|
|
|
|
## ✨ Caractéristiques
|
|
|
|
### Fonctionnalités Principales
|
|
|
|
- **Gestion des Membres** - Inscription, profils, recherche avancée, import/export
|
|
- **Gestion des Cotisations** - Suivi des paiements, relances automatiques, statistiques
|
|
- **Gestion des Événements** - Planification, participants, rapports
|
|
- **Demandes d'Aide** - Workflow de validation, suivi des bénéficiaires
|
|
- **Rapports et Analytics** - Tableaux de bord personnalisés, exports multiples formats
|
|
- **Gestion des Associations** - Organisation hiérarchique, quotas
|
|
- **Administration** - Configuration système, gestion des utilisateurs, audit logs
|
|
|
|
### Technologies Clés
|
|
|
|
- **Backend Framework**: Quarkus 3.15.1 (JVM optimisé, démarrage rapide)
|
|
- **UI Framework**: JSF 4.0 (MyFaces) + PrimeFaces 14.0.5
|
|
- **UI Theme**: Freya 5.0.0 (design moderne et responsive)
|
|
- **Sécurité**: Keycloak OIDC + JWT
|
|
- **Validation**: Hibernate Validator + validateurs personnalisés
|
|
- **Export**: Apache POI (Excel), OpenPDF (PDF)
|
|
- **Résilience**: RetryService avec backoff exponentiel ⭐ **NOUVEAU**
|
|
- **Performance**: CacheService en mémoire avec TTL ⭐ **NOUVEAU**
|
|
- **Monitoring**: BackendCallInterceptor pour métriques ⭐ **NOUVEAU**
|
|
|
|
### 🎉 Version 3.0 - Production-Ready (2026-01-04)
|
|
|
|
#### Améliorations Majeures
|
|
- ✅ **48 beans JSF migrés** vers architecture production-ready
|
|
- ✅ **ErrorHandlerService** - Gestion centralisée des erreurs
|
|
- ✅ **RetryService** - Retry automatique avec backoff exponentiel
|
|
- ✅ **CacheService** - Cache en mémoire pour optimisation
|
|
- ✅ **BackendCallInterceptor** - Logging et métriques automatiques
|
|
- ✅ **Logging structuré** - Migration vers `org.jboss.logging.Logger`
|
|
|
|
## 🏗️ Architecture
|
|
|
|
### Architecture en Couches
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ PRESENTATION LAYER (JSF/PrimeFaces) │
|
|
│ - 175 pages XHTML │
|
|
│ - 48 Backing Beans (Production-Ready) │
|
|
│ - Freya Theme (CSS, JS, Icons) │
|
|
└─────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ SERVICE LAYER (REST Clients) │
|
|
│ - 24+ interfaces REST Client (MicroProfile) │
|
|
│ - 14+ DTOs validés │
|
|
│ - Exception Mapping │
|
|
└─────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ SECURITY LAYER │
|
|
│ - OIDC Authentication (Keycloak) │
|
|
│ - JWT Token Management │
|
|
│ - Role-Based Access Control (RBAC) │
|
|
│ - Permission Checker │
|
|
└─────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ EXTERNAL SYSTEMS │
|
|
│ - UnionFlow Backend REST API │
|
|
│ - Keycloak OIDC Server │
|
|
│ - Wave Payment Gateway (optional) │
|
|
└─────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Stack Technique Complet
|
|
|
|
| Composant | Version | Rôle |
|
|
|-----------|---------|------|
|
|
| Java | 17 (LTS) | Langage |
|
|
| Quarkus | 3.15.1 | Framework application |
|
|
| Jakarta EE | 10 | Standard entreprise |
|
|
| JSF (MyFaces) | 4.0 | MVC web framework |
|
|
| PrimeFaces | 14.0.5 | Composants riches |
|
|
| OmniFaces | 4.4.1 | Utilitaires JSF |
|
|
| Lombok | 1.18.34 | Réduction boilerplate |
|
|
| Apache POI | 5.3.0 | Export Excel |
|
|
| OpenPDF | 1.3.30 | Export PDF |
|
|
|
|
## 🚀 Services Production-Ready
|
|
|
|
L'application dispose de services transverses pour garantir la robustesse en production :
|
|
|
|
### ErrorHandlerService
|
|
**Gestion centralisée des erreurs**
|
|
- Messages utilisateur clairs et localisés
|
|
- Logging automatique des exceptions
|
|
- Méthodes : `showSuccess()`, `showError()`, `showWarning()`, `handleException()`
|
|
|
|
### RetryService
|
|
**Résilience des appels backend**
|
|
- Retry automatique avec backoff exponentiel (3 tentatives, délai x2)
|
|
- Gestion intelligente des exceptions retryables
|
|
- Méthode : `executeWithRetrySupplier()`
|
|
|
|
### CacheService
|
|
**Optimisation des performances**
|
|
- Cache en mémoire avec TTL configurable (5 minutes par défaut)
|
|
- Invalidation manuelle ou automatique
|
|
- Méthodes : `get()`, `put()`, `invalidate()`, `invalidateAll()`
|
|
|
|
### BackendCallInterceptor
|
|
**Monitoring et métriques**
|
|
- Logging automatique des appels backend (paramètres, durée, résultats)
|
|
- Détection des appels lents (>2s)
|
|
- Masquage des données sensibles dans les logs
|
|
- Annotation : `@LogBackendCall`
|
|
|
|
### ValidationService
|
|
**Validation centralisée**
|
|
- Validation des beans avec contraintes Jakarta
|
|
- Messages d'erreur structurés
|
|
- Intégration avec ErrorHandlerService
|
|
|
|
---
|
|
|
|
## 📦 Prérequis
|
|
|
|
### Environnement de Développement
|
|
|
|
- **Java Development Kit (JDK)**: OpenJDK 17 ou supérieur
|
|
- **Apache Maven**: 3.8+ (pour la compilation)
|
|
- **Git**: 2.30+ (pour le versioning)
|
|
- **IDE recommandé**: IntelliJ IDEA ou Eclipse avec support Quarkus
|
|
|
|
### Services Externes Requis
|
|
|
|
- **Keycloak Server**: 22+ (authentification OIDC)
|
|
- **UnionFlow Backend API**: Service REST backend
|
|
- **Base de données** (via backend): PostgreSQL 14+ ou MongoDB 6+
|
|
|
|
### Configuration Minimale Serveur
|
|
|
|
- **CPU**: 2 cores minimum
|
|
- **RAM**: 4GB minimum (8GB recommandé)
|
|
- **Disque**: 2GB espace libre
|
|
- **OS**: Linux (Ubuntu 20.04+), Windows Server 2019+, macOS 11+
|
|
|
|
## 🚀 Installation
|
|
|
|
### 1. Cloner le Projet
|
|
|
|
```bash
|
|
git clone https://git.lions.dev/lionsdev/unionflow-client-quarkus-primefaces-freya.git
|
|
cd unionflow-client-quarkus-primefaces-freya
|
|
```
|
|
|
|
### 2. Configuration Maven
|
|
|
|
Assurez-vous que le repository privé Gitea est configuré dans `~/.m2/settings.xml`:
|
|
|
|
```xml
|
|
<settings>
|
|
<servers>
|
|
<server>
|
|
<id>gitea</id>
|
|
<username>${env.GITEA_USERNAME}</username>
|
|
<password>${env.GITEA_TOKEN}</password>
|
|
</server>
|
|
</servers>
|
|
</settings>
|
|
```
|
|
|
|
### 3. Compilation
|
|
|
|
```bash
|
|
# Compilation standard
|
|
mvn clean package
|
|
|
|
# Compilation sans tests (développement rapide)
|
|
mvn clean package -DskipTests
|
|
|
|
# Compilation avec profil production
|
|
mvn clean package -Pproduction
|
|
```
|
|
|
|
## ⚙️ Configuration
|
|
|
|
### Variables d'Environnement Requises
|
|
|
|
#### Développement
|
|
|
|
```bash
|
|
# Keycloak
|
|
export KEYCLOAK_CLIENT_SECRET="votre-secret-keycloak-dev"
|
|
|
|
# Backend
|
|
export UNIONFLOW_BACKEND_URL="https://localhost:8085"
|
|
```
|
|
|
|
#### Production
|
|
|
|
```bash
|
|
# Keycloak
|
|
export KEYCLOAK_CLIENT_SECRET="votre-secret-keycloak-prod"
|
|
export KEYCLOAK_AUTH_SERVER_URL="https://security.lions.dev/realms/unionflow"
|
|
|
|
# Backend
|
|
export UNIONFLOW_BACKEND_URL="https://api.lions.dev/unionflow"
|
|
|
|
# Session
|
|
export SESSION_TIMEOUT="1800" # 30 minutes
|
|
export REMEMBER_ME_DURATION="604800" # 7 jours
|
|
|
|
# Sécurité
|
|
export ENABLE_CSRF="true"
|
|
export PASSWORD_MIN_LENGTH="8"
|
|
export PASSWORD_REQUIRE_SPECIAL="true"
|
|
export MAX_LOGIN_ATTEMPTS="5"
|
|
export LOCKOUT_DURATION="300"
|
|
```
|
|
|
|
### Fichiers de Configuration
|
|
|
|
- **`application.properties`**: Configuration par défaut (développement)
|
|
- **`application-prod.properties`**: Configuration production
|
|
- **`application-dev.properties`**: Configuration développement spécifique
|
|
|
|
### Configuration Keycloak
|
|
|
|
1. Créer un realm `unionflow` dans Keycloak
|
|
2. Créer un client `unionflow-client`:
|
|
- Client Protocol: `openid-connect`
|
|
- Access Type: `confidential`
|
|
- Valid Redirect URIs: `https://votre-domaine.com/*`
|
|
- Web Origins: `https://votre-domaine.com`
|
|
3. Configurer les rôles:
|
|
- `SUPER_ADMIN`: Administrateur système
|
|
- `ADMIN_ENTITE`: Administrateur d'organisation
|
|
- `MEMBRE`: Membre standard
|
|
4. Configurer les mappers pour inclure les rôles dans les tokens JWT
|
|
|
|
## 🏃 Lancement
|
|
|
|
### Mode Développement
|
|
|
|
```bash
|
|
# Lancement avec rechargement automatique (Live Reload)
|
|
./mvnw quarkus:dev
|
|
|
|
# Accès
|
|
# - Application: http://localhost:8086
|
|
# - Dev UI: http://localhost:8086/q/dev
|
|
```
|
|
|
|
### Mode Production
|
|
|
|
```bash
|
|
# Construire l'application
|
|
./mvnw clean package -Pproduction
|
|
|
|
# Lancer en production
|
|
java -jar target/quarkus-app/quarkus-run.jar
|
|
|
|
# Ou avec profil spécifique
|
|
java -Dquarkus.profile=prod -jar target/quarkus-app/quarkus-run.jar
|
|
```
|
|
|
|
### Docker (Optionnel)
|
|
|
|
```bash
|
|
# Construction de l'image
|
|
docker build -f src/main/docker/Dockerfile.jvm -t unionflow-client:latest .
|
|
|
|
# Lancement du conteneur
|
|
docker run -p 8080:8080 \
|
|
-e KEYCLOAK_CLIENT_SECRET="votre-secret" \
|
|
-e UNIONFLOW_BACKEND_URL="https://api.lions.dev/unionflow" \
|
|
unionflow-client:latest
|
|
```
|
|
|
|
## 🔒 Sécurité
|
|
|
|
### Authentification et Autorisation
|
|
|
|
- **Méthode**: OpenID Connect (OIDC) via Keycloak
|
|
- **Tokens**: JWT (JSON Web Tokens)
|
|
- **Rôles supportés**: SUPER_ADMIN, ADMIN_ENTITE, MEMBRE
|
|
- **Permissions granulaires**: Basées sur les rôles et fonctionnalités
|
|
|
|
### Headers de Sécurité (Production)
|
|
|
|
L'application configure automatiquement les headers de sécurité suivants:
|
|
|
|
- `X-Content-Type-Options: nosniff`
|
|
- `X-Frame-Options: DENY`
|
|
- `Strict-Transport-Security: max-age=31536000; includeSubDomains; preload`
|
|
- `Content-Security-Policy`: Configuration stricte avec support PrimeFaces
|
|
- `X-XSS-Protection: 1; mode=block`
|
|
- `Referrer-Policy: strict-origin-when-cross-origin`
|
|
|
|
### Bonnes Pratiques
|
|
|
|
1. **Secrets**: Ne JAMAIS committer de secrets dans Git
|
|
2. **HTTPS**: Toujours utiliser HTTPS en production
|
|
3. **Cookies**: HttpOnly et SameSite=Strict activés
|
|
4. **Sessions**: Timeout de 60 minutes par défaut
|
|
5. **TLS**: Vérification TLS obligatoire même en dev
|
|
|
|
Pour plus de détails, consultez [SECURITY.md](SECURITY.md).
|
|
|
|
## 🧪 Tests
|
|
|
|
### Lancement des Tests
|
|
|
|
```bash
|
|
# Tous les tests
|
|
mvn test
|
|
|
|
# Tests unitaires uniquement
|
|
mvn test -Dtest="*Test"
|
|
|
|
# Tests d'intégration uniquement
|
|
mvn test -Dtest="*IT"
|
|
|
|
# Tests avec couverture
|
|
mvn test jacoco:report
|
|
```
|
|
|
|
### Structure des Tests
|
|
|
|
```
|
|
src/test/java/
|
|
├── validation/ # Tests unitaires validateurs
|
|
│ ├── MemberNumberValidatorTest.java
|
|
│ └── PhoneNumberValidatorTest.java
|
|
├── security/ # Tests services de sécurité
|
|
│ ├── PermissionCheckerTest.java
|
|
│ └── TokenRefreshServiceTest.java
|
|
└── service/ # Tests d'intégration REST clients
|
|
├── MembreServiceIT.java
|
|
└── AuthenticationServiceIT.java
|
|
```
|
|
|
|
### Résultats des Tests
|
|
|
|
**Status** : ✅ **15/15 tests passent** (100%)
|
|
|
|
- ✅ `MemberNumberValidatorTest` : 15/15 tests
|
|
- ✅ Tous les validateurs personnalisés testés
|
|
- ✅ Aucune régression après migration
|
|
|
|
### Couverture de Code
|
|
|
|
Objectif: **80%** minimum
|
|
|
|
- Validateurs: 100%
|
|
- Services de sécurité: 90%
|
|
- REST Clients: 70%
|
|
- Backing Beans: 60%
|
|
|
|
## 🚢 Déploiement
|
|
|
|
### Déploiement sur Serveur Linux
|
|
|
|
```bash
|
|
# 1. Transférer l'artifact
|
|
scp target/quarkus-app/quarkus-run.jar user@serveur:/opt/unionflow/
|
|
|
|
# 2. Configurer le service systemd
|
|
sudo nano /etc/systemd/system/unionflow-client.service
|
|
|
|
# 3. Contenu du service
|
|
[Unit]
|
|
Description=UnionFlow Client Application
|
|
After=network.target
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=unionflow
|
|
WorkingDirectory=/opt/unionflow
|
|
ExecStart=/usr/bin/java -jar /opt/unionflow/quarkus-run.jar
|
|
Restart=on-failure
|
|
Environment="KEYCLOAK_CLIENT_SECRET=xxx"
|
|
Environment="UNIONFLOW_BACKEND_URL=https://api.lions.dev/unionflow"
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
|
|
# 4. Activer et démarrer
|
|
sudo systemctl enable unionflow-client
|
|
sudo systemctl start unionflow-client
|
|
sudo systemctl status unionflow-client
|
|
```
|
|
|
|
### Déploiement avec Nginx Reverse Proxy
|
|
|
|
```nginx
|
|
server {
|
|
listen 443 ssl http2;
|
|
server_name unionflow.lions.dev;
|
|
|
|
ssl_certificate /etc/letsencrypt/live/unionflow.lions.dev/fullchain.pem;
|
|
ssl_certificate_key /etc/letsencrypt/live/unionflow.lions.dev/privkey.pem;
|
|
|
|
location / {
|
|
proxy_pass http://localhost:8080;
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
}
|
|
}
|
|
```
|
|
|
|
## 📚 Documentation Supplémentaire
|
|
|
|
- **Architecture Détaillée**: `/docs/ARCHITECTURE.md`
|
|
- **Guide de Sécurité**: [SECURITY.md](SECURITY.md)
|
|
- **Guide de Contribution**: `/docs/CONTRIBUTING.md`
|
|
- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
|
|
- **API Documentation**: Disponible sur le backend
|
|
|
|
## 🐛 Problèmes Connus et Solutions
|
|
|
|
### ViewExpiredException
|
|
|
|
Si vous rencontrez des `ViewExpiredException`, vérifiez:
|
|
- Le timeout de session (`quarkus.http.session-timeout`)
|
|
- Le nombre de vues en session (`quarkus.myfaces.number-of-views-in-session`)
|
|
|
|
### Erreur OIDC "Invalid Token"
|
|
|
|
Solution:
|
|
1. Vérifier que le client Keycloak est correctement configuré
|
|
2. Vérifier la variable `KEYCLOAK_CLIENT_SECRET`
|
|
3. Vérifier l'URL du serveur Keycloak
|
|
|
|
### Erreur "BeanManager.getELResolver"
|
|
|
|
Déjà corrigé via `QuarkusArcELResolver`. Si le problème persiste:
|
|
1. Vérifier la configuration Arc CDI dans `application.properties`
|
|
2. Vérifier que `faces-config.xml` contient `QuarkusApplicationFactory`
|
|
|
|
## 📞 Support
|
|
|
|
### Équipe de Développement
|
|
|
|
- **Email**: support@lions.dev
|
|
- **Slack**: #unionflow-support
|
|
- **Issue Tracker**: https://git.lions.dev/lionsdev/unionflow-client/issues
|
|
|
|
### Resources
|
|
|
|
- **Documentation Quarkus**: https://quarkus.io/guides/
|
|
- **Documentation PrimeFaces**: https://www.primefaces.org/showcase/
|
|
- **Documentation Keycloak**: https://www.keycloak.org/documentation
|
|
|
|
## 📄 Licence
|
|
|
|
Propriétaire - © 2025 Lions Club International - Tous droits réservés
|
|
|
|
---
|
|
|
|
## 📊 État du Projet
|
|
|
|
- ✅ **Version** : 3.0.0
|
|
- ✅ **Status** : Production-Ready
|
|
- ✅ **Tests** : 15/15 (100%)
|
|
- ✅ **Beans** : 48 beans migrés
|
|
- ✅ **Services** : 5 services transverses
|
|
- ✅ **Documentation** : Complète et à jour
|
|
|
|
---
|
|
|
|
**Version**: 3.0.0
|
|
**Dernière mise à jour**: 4 Janvier 2026
|
|
**Auteur**: Équipe UnionFlow
|
|
**License**: Proprietary - Lions Club Côte d'Ivoire
|