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
• Architecture
• Prérequis
• Installation
• Configuration
• Lancement
• Sécurité
• Tests
• Déploiement
• 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

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:

<settings>
  <servers>
    <server>
      <id>gitea</id>
      <username>${env.GITEA_USERNAME}</username>
      <password>${env.GITEA_TOKEN}</password>
    </server>
  </servers>
</settings>

3. Compilation

# 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

# Keycloak
export KEYCLOAK_CLIENT_SECRET="votre-secret-keycloak-dev"

# Backend
export UNIONFLOW_BACKEND_URL="https://localhost:8085"

Production

# 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

# Lancement avec rechargement automatique (Live Reload)
./mvnw quarkus:dev

# Accès
# - Application: http://localhost:8086
# - Dev UI: http://localhost:8086/q/dev

Mode Production

# 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)

# 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.

🧪 Tests

Lancement des Tests

# 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

# 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

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
• Guide de Contribution: /docs/CONTRIBUTING.md
• Changelog: 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