# 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