lionsdev/unionflow-client-quarkus-primefaces-freya
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactoring

Browse Source
This commit is contained in:
dahoud
2026-03-01 22:00:28 +00:00
parent c0e2c4da45
commit 6b28cf751e
469 changed files with 26866 additions and 14768 deletions
Download Patch File Download Diff File Expand all files Collapse all files

496
README.md Normal file
View File

@@ -0,0 +1,496 @@
# UnionFlow Client - Application Web de Gestion
![Java](https://img.shields.io/badge/Java-17-blue)
![Quarkus](https://img.shields.io/badge/Quarkus-3.15.1-red)
![PrimeFaces](https://img.shields.io/badge/PrimeFaces-14.0.5-green)
![Jakarta EE](https://img.shields.io/badge/Jakarta%20EE-10-orange)
![License](https://img.shields.io/badge/License-Proprietary-red)
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