# Prompt Corrigé - Module lions-user-manager

## Objectif

Générer intégralement (A→Z) un module nommé `lions-user-manager` en Java + Quarkus + PrimeFaces Freya, structuré en 3 sous-modules Maven selon l'architecture existante des projets `unionflow` et `btpxpress` :

1. `lions-user-manager-server-api` (JAR)
2. `lions-user-manager-server-impl-quarkus` (JAR)
3. `lions-user-manager-client-quarkus-primefaces-freya` (JAR)

## Contraintes Globales

### Architecture & Structure

- **Respecter strictement l'architecture existante** :
  - Module parent : `lions-user-manager-parent` (pom.xml avec packaging `pom`)
  - GroupId : `dev.lions.user.manager` (convention : points, comme `dev.lions.unionflow`)
  - Version : `1.0.0`
  - Java 17+ (comme `unionflow`)
  - Quarkus `3.15.1` (version stable utilisée dans `unionflow`)
  - PrimeFaces `14.0.5` avec Quarkus PrimeFaces `3.13.3`

- **Séparation des modules** :
  - `server-api` : Contrats uniquement (DTOs, interfaces service, enums, exceptions, validation)
  - `server-impl` : Implémentation métier, Keycloak Admin Client, Resources REST, Services, Entités/Repositories (si nécessaire)
  - `client` : UI PrimeFaces Freya, Beans JSF, Services REST Client (MicroProfile Rest Client), DTOs client simplifiés

### Keycloak - Contraintes Critiques

- **AUCUNE écriture directe dans la DB Keycloak** : Utiliser uniquement Keycloak Admin REST API (client credentials / service account) pour toutes les opérations CREATE/UPDATE/DELETE.
- **Accès DB Keycloak en lecture** : STRICTEMENT contrôlés (read-only, TLS, IP whitelist, journalisation). Toute méthode qui appellerait directement la DB Keycloak doit être commentée `// DISABLED: direct DB access forbidden in prod` et nulle part activée par défaut.
- **Client Keycloak** : Provisionnement via client Keycloak `lions-user-manager` (service account, client credentials).
- **Appels Admin API** : Doivent passer par une classe `KeycloakAdminClient` centralisée, testable (interface + mock).

### Patterns & Conventions (basés sur unionflow)

#### Packages

- **server-api** : `dev.lions.user.manager.server.api`
  - `dto/` : DTOs avec sous-packages par domaine (ex: `dto/user/`, `dto/role/`, `dto/audit/`)
  - `dto/base/` : `BaseDTO` (comme dans unionflow)
  - `enums/` : Enums métiers
  - `service/` : Interfaces de services (ex: `UserService`, `RoleService`)
  - `validation/` : Constantes de validation

- **server-impl** : `dev.lions.user.manager.server`
  - `resource/` : Resources REST JAX-RS (ex: `UserResource`, `RoleResource`)
  - `service/` : Implémentations des services (ex: `UserServiceImpl`, `RoleServiceImpl`)
  - `client/` : Client Keycloak Admin API (`KeycloakAdminClient`, interface + implémentation)
  - `security/` : Configuration sécurité, KeycloakService
  - `entity/` : Entités JPA (si nécessaire pour audit local)
  - `repository/` : Repositories (si nécessaire)
  - `dto/` : DTOs spécifiques à l'implémentation (si nécessaire)

- **client** : `dev.lions.user.manager.client`
  - `service/` : Services REST Client (MicroProfile Rest Client) avec `@RegisterRestClient(configKey = "lions-user-manager-api")`
  - `dto/` : DTOs client simplifiés (mirroir des DTOs server-api mais adaptés)
  - `view/` : Beans JSF avec `@Named("...")` et `@SessionScoped` ou `@RequestScoped`
  - `security/` : Gestion tokens, OIDC, filtres
  - `validation/` : Validateurs client
  - `exception/` : Handlers d'exceptions JSF
  - `converter/` : Converters JSF

#### Resources REST

- **Path** : Utiliser `/api/...` (comme dans unionflow : `/api/membres`, `/api/cotisations`)
- **Annotations** :
  - `@Path("/api/users")` (pas `/realms/{realm}/users`)
  - `@ApplicationScoped`
  - `@Tag(name = "...", description = "...")` pour OpenAPI
  - `@Operation`, `@APIResponse`, `@SecurityRequirement` pour documentation
  - `@RolesAllowed` pour la sécurité
- **Réponses** : Utiliser `Response` de JAX-RS avec codes HTTP appropriés

#### Services

- **Interfaces** : Dans `server-api/src/main/java/.../service/` (ex: `UserService.java`)
- **Implémentations** : Dans `server-impl/src/main/java/.../service/` (ex: `UserServiceImpl.java`)
- **Annotations** : `@ApplicationScoped`, `@Inject` pour les dépendances
- **Logging** : Utiliser `org.jboss.logging.Logger` (comme dans unionflow)

#### Client REST (MicroProfile Rest Client)

- **Pattern** : Comme `MembreService` dans unionflow
  ```java
  @RegisterRestClient(configKey = "lions-user-manager-api")
  @Path("/api/users")
  @Consumes(MediaType.APPLICATION_JSON)
  @Produces(MediaType.APPLICATION_JSON)
  public interface UserService {
      @GET
      List<UserDTO> listerTous();
      // ...
  }
  ```
- **Configuration** : Dans `application.properties` (comme dans unionflow) :
  ```properties
  lions.user.manager.backend.url=http://localhost:8080
  quarkus.rest-client."lions-user-manager-api".url=${lions.user.manager.backend.url}
  quarkus.rest-client."lions-user-manager-api".scope=jakarta.inject.Singleton
  quarkus.rest-client."lions-user-manager-api".connect-timeout=5000
  quarkus.rest-client."lions-user-manager-api".read-timeout=30000
  ```

#### Beans JSF

- **Pattern** : Comme `MembreRechercheBean` dans unionflow
  - `@Named("userRechercheBean")` (nom en camelCase)
  - `@SessionScoped` ou `@RequestScoped`
  - `@Inject` pour les services REST Client
  - `@PostConstruct` pour l'initialisation
  - `private static final Logger LOGGER = Logger.getLogger(...)`
  - Implémenter `Serializable`

#### DTOs

- **server-api** : Comme `MembreDTO` dans unionflow
  - Étendre `BaseDTO` (avec UUID `id`)
  - Utiliser Lombok `@Getter`, `@Setter`
  - Validation Bean (`@NotBlank`, `@Email`, etc.)
  - Package : `dev.lions.user.manager.server.api.dto.user`

- **client** : DTOs simplifiés (mirroir mais adaptés)
  - Package : `dev.lions.user.manager.client.dto`
  - Peuvent avoir des méthodes supplémentaires pour JSF

#### Configuration

- **application.properties** : Comme dans unionflow
  - Profils : `%dev`, `%test`, `%prod`
  - Variables d'environnement pour prod : `${KEYCLOAK_SERVER_URL:...}`
  - Keycloak OIDC configuré via `quarkus.oidc.*`
  - OpenAPI configuré via `quarkus.smallrye-openapi.*`

### Fonctions Principales à Générer

#### 1. AuthN/AuthZ & Sécurité

- **Provisionnement** : Client Keycloak `lions-user-manager` (service account, client credentials)
- **JWT validation** : Côté service, contrôle RBAC : superadmin global et admin de realm
- **Protection CSRF/XSS** : Pour UI PrimeFaces (via Quarkus/PrimeFaces)
- **KeycloakAdminClient** : Classe centralisée pour tous les appels Admin API, avec interface pour tests

#### 2. Gestion Utilisateurs (CRUD)

- **Endpoints REST** :
  - `GET /api/users` : Liste paginée
  - `POST /api/users` : Création
  - `GET /api/users/{id}` : Détails
  - `PUT /api/users/{id}` : Modification
  - `DELETE /api/users/{id}` : Suppression (soft delete si possible via Admin API)
  - `GET /api/users/search` : Recherche avancée
- **Import/Export** : CSV & JSON, mapping attributs métiers -> Keycloak attributes
- **Service** : `UserService` (interface dans api, impl dans impl)

#### 3. Gestion Rôles & Privileges Métiers

- **Mappage** : Rôles métiers ↔ Keycloak realm roles / client roles
- **Endpoints** :
  - `GET /api/roles` : Liste des rôles
  - `POST /api/users/{userId}/roles` : Assignation
  - `DELETE /api/users/{userId}/roles/{roleId}` : Désassignation
  - `GET /api/users/{userId}/roles` : Rôles d'un utilisateur
- **Service** : `RoleService` (interface dans api, impl dans impl)

#### 4. Délégation Multi-Realm

- **Superadmin global** : Peut tout faire (tous les realms)
- **Admin de realm** : Limité à son realm
- **Vérification** : Côté API (double-check du token + logique métier)
- **Filtrage** : Les endpoints retournent uniquement les données du realm autorisé

#### 5. Audit & Traçabilité

- **Audit append-only** : Toutes les actions admin (utilisateur, rôle, import/export) : qui, quoi, quand, IP, success/failure
- **Stockage** : Configurable (ex: ES / DB append-only / bucket versionné)
- **Service** : `AuditService` (interface dans api, impl dans impl)
- **Endpoint** : `GET /api/audit` : Consultation des logs d'audit

#### 6. Synchronisation & Consistance

- **Event listener / polling** : Refléter changements faits directement dans Keycloak (EventListener SPI ou Keycloak events via Admin API)
- **Reconciliation périodique** : Configurable (via Admin API)
- **Service** : `SyncService` (interface dans api, impl dans impl)

#### 7. Résilience & Observabilité

- **Retry** : Exponential backoff sur appels Admin API
- **Circuit breaker** : Pour éviter surcharge Keycloak
- **Timeout** : Configuration des timeouts
- **Rate limiting** : Sur appels Admin API
- **Metrics** : Prometheus (Quarkus MicroProfile Metrics)
- **Logs structurés** : Utiliser `org.jboss.logging.Logger`
- **Alerting** : Slack/email (via configuration)

#### 8. Déploiement & Infra

- **Helm chart** : Pour k8s (secrets via Vault/K8s Secret)
- **Readiness/liveness probes** : Endpoints `/health/ready`, `/health/live`
- **Resource requests/limits** : Configuration dans Helm
- **Scripts d'init** : `kcadm.sh` / Admin API curl examples pour créer le client Keycloak et accorder les rôles nécessaires

#### 9. Documentation & SDK

- **SDK Java** : Client lib dans `server-api` (DTOs + interfaces) et exemples d'utilisation
- **Documentation OpenAPI** : Générée automatiquement via Quarkus (accessible sur `/q/swagger-ui`)
- **Guides d'intégration** : Java + JSF (dans `/docs`)

#### 10. Tests & CI

- **Testcontainers** : Instance Keycloak pour CI
- **Tests unitaires** : Services, repositories, client Keycloak (mocks)
- **Tests d'intégration** : Resources REST avec Testcontainers
- **Tests E2E minimal** : UI PrimeFaces (si possible)

## Structure du Repo Demandé

```
lions-user-manager/
├── pom.xml                          # Parent multi-modules
├── lions-user-manager-server-api/
│   ├── pom.xml
│   └── src/main/java/dev/lions/user/manager/server/api/
│       ├── dto/
│       │   ├── base/
│       │   │   └── BaseDTO.java
│       │   ├── user/
│       │   │   ├── UserDTO.java
│       │   │   ├── UserSearchCriteria.java
│       │   │   └── UserSearchResultDTO.java
│       │   ├── role/
│       │   │   ├── RoleDTO.java
│       │   │   └── RoleAssignmentDTO.java
│       │   └── audit/
│       │       └── AuditLogDTO.java
│       ├── enums/
│       │   ├── user/
│       │   │   └── StatutUser.java
│       │   └── role/
│       │       └── TypeRole.java
│       ├── service/
│       │   ├── UserService.java
│       │   ├── RoleService.java
│       │   ├── AuditService.java
│       │   └── SyncService.java
│       └── validation/
│           └── ValidationConstants.java
├── lions-user-manager-server-impl-quarkus/
│   ├── pom.xml
│   └── src/main/java/dev/lions/user/manager/server/
│       ├── resource/
│       │   ├── UserResource.java
│       │   ├── RoleResource.java
│       │   ├── AuditResource.java
│       │   └── HealthResource.java
│       ├── service/
│       │   ├── UserServiceImpl.java
│       │   ├── RoleServiceImpl.java
│       │   ├── AuditServiceImpl.java
│       │   └── SyncServiceImpl.java
│       ├── client/
│       │   ├── KeycloakAdminClient.java        # Interface
│       │   └── KeycloakAdminClientImpl.java    # Implémentation
│       ├── security/
│       │   ├── KeycloakService.java
│       │   └── SecurityConfig.java
│       ├── entity/                              # Si nécessaire pour audit local
│       │   └── AuditLog.java
│       ├── repository/                          # Si nécessaire
│       │   └── AuditLogRepository.java
│       └── UserManagerServerApplication.java
│   └── src/main/resources/
│       ├── application.properties
│       ├── application-dev.properties          # Optionnel
│       ├── application-prod.properties         # Optionnel
│       └── db/migration/                       # Si nécessaire pour audit local
│           └── V1.0__Create_Audit_Log_Table.sql
├── lions-user-manager-client-quarkus-primefaces-freya/
│   ├── pom.xml
│   └── src/main/java/dev/lions/user/manager/client/
│       ├── service/
│       │   ├── UserService.java                 # REST Client
│       │   ├── RoleService.java                 # REST Client
│       │   └── AuditService.java                # REST Client
│       ├── dto/
│       │   ├── UserDTO.java                     # DTO client simplifié
│       │   ├── RoleDTO.java
│       │   └── AuditLogDTO.java
│       ├── view/
│       │   ├── UserRechercheBean.java
│       │   ├── UserListeBean.java
│       │   ├── UserProfilBean.java
│       │   ├── RoleGestionBean.java
│       │   └── AuditConsultationBean.java
│       ├── security/
│       │   ├── JwtTokenManager.java
│       │   ├── AuthenticationFilter.java
│       │   └── PermissionChecker.java
│       └── UserManagerClientApplication.java
│   └── src/main/resources/
│       ├── application.properties
│       └── META-INF/resources/
│           └── pages/                          # Pages XHTML PrimeFaces
├── helm/
│   ├── Chart.yaml
│   ├── values.yaml
│   ├── values.yaml.example
│   └── templates/
│       ├── deployment.yaml
│       ├── service.yaml
│       ├── ingress.yaml
│       └── configmap.yaml
├── scripts/
│   ├── kcadm-provision.sh                      # Création client Keycloak
│   ├── rotate-secrets.sh                       # Rotation secrets
│   └── setup-keycloak-client.ps1               # Alternative PowerShell
├── tests/
│   ├── integration/                            # Tests Testcontainers
│   │   ├── UserResourceIT.java
│   │   └── RoleResourceIT.java
│   └── unit/                                   # Tests unitaires
│       ├── UserServiceImplTest.java
│       └── KeycloakAdminClientTest.java
└── docs/
    ├── architecture.md
    ├── runbook.md
    ├── security-policy.md
    └── integration-guide.md
```

## Contraintes Techniques Précises

### Keycloak Admin Client

- **Classe centralisée** : `KeycloakAdminClient` (interface + implémentation)
- **Interface** : Pour permettre le mocking dans les tests
- **Configuration** : Via `application.properties` :
  ```properties
  lions.user.manager.keycloak.server-url=${KEYCLOAK_SERVER_URL:http://localhost:8180}
  lions.user.manager.keycloak.realm=${KEYCLOAK_REALM:master}
  lions.user.manager.keycloak.client-id=${KEYCLOAK_CLIENT_ID:lions-user-manager}
  lions.user.manager.keycloak.client-secret=${KEYCLOAK_CLIENT_SECRET}
  lions.user.manager.keycloak.connection-timeout=5000
  lions.user.manager.keycloak.read-timeout=30000
  ```
- **Retry & Circuit Breaker** : Implémenter dans `KeycloakAdminClientImpl`
- **Token management** : Récupération automatique via client credentials, refresh si expiré

### Feature Toggles

- **`lions.user.manager.keycloak.write.enabled`** : `false` par défaut en staging, `true` en prod
- **Validation utilisateur** : Confirmation finale avant toute action destructive (DELETE)

### Health & Metrics

- **Health endpoints** : Utiliser Quarkus MicroProfile Health
  - `/health/ready` : Readiness probe
  - `/health/live` : Liveness probe
  - `/health` : Health check général
- **Metrics** : Utiliser Quarkus MicroProfile Metrics
  - Exposer sur `/metrics` (Prometheus format)
  - Métriques : nombre d'appels Admin API, taux d'erreur, latence

### Gestion d'Erreurs

- **Keycloak 5xx** : Retry avec exponential backoff + circuit breaker
- **Si échec prolongé** : Bloquer opérations sensibles et informer superadmin (log + métrique)
- **Token service account expiré** : Récupération automatique via client credentials; log & alert si échec
- **Conflit de rôle** : Transactionnel côté application (idempotence) et reconciliation par background job

### Logging

- **Utiliser** : `org.jboss.logging.Logger` (comme dans unionflow)
- **Format structuré** : JSON en prod (configurable)
- **Niveaux** : INFO par défaut, DEBUG en dev

## Livrables Concrets

1. **Diagramme d'architecture** : Components + flows AuthN/AuthZ + secrets distribution (fichier `docs/architecture.md`)
2. **Arborescence de repo** : Complète avec pom parent + modules (comme décrit ci-dessus)
3. **Code complet** :
   - Controllers (Resources REST)
   - Services (interfaces + implémentations)
   - DTOs (server-api + client)
   - Client Keycloak Admin API (interface + impl)
   - UI PrimeFaces Freya (pages XHTML + Beans JSF)
4. **Scripts** : Provisionner Keycloak client/service account (kcadm & Admin API examples)
5. **Helm chart** : Manifest k8s complet
6. **Testcontainers** : Tests d'intégration
7. **OpenAPI spec** : Générée automatiquement via Quarkus
8. **SDK Java** : DTOs + interfaces dans `server-api`
9. **Runbook ops** : Création client, rotation secret, rollback, procédure d'urgence
10. **Checklist sécurité** : Logs, no plaintext passwords, RGPD notes

## Critères d'Acceptation

- ✅ Endpoints CRUD utilisateurs + gestion rôles fonctionnels via Admin API (tests CI green)
- ✅ Admin realm ne voit/agit que sur son realm (filtrage côté API)
- ✅ UI PrimeFaces Freya totalement intégrée et authentifiée via OIDC
- ✅ Tests d'intégration avec Testcontainers Keycloak passés
- ✅ Scripts de provisioning Keycloak fournis + Helm déployable sur cluster staging
- ✅ Aucune écriture directe dans DB Keycloak (vérification code + tests)
- ✅ Code conforme aux patterns de `unionflow` (packages, annotations, structure)

## Instructions Finales pour l'IA

- **Générer le code Java complet** : Controllers, services, DTOs, client Keycloak, UI PrimeFaces Freya (templates & composants), tests, CI (GitHub Actions ou équivalent), scripts k8s/helm
- **Respecter strictement** : L'interdiction d'écriture directe sur la DB Keycloak — toute option DB doit être read-only et documentée comme « usage d'investigation seulement »
- **Fournir un README** : D'intégration clair pour les autres modules lions.dev (comment utiliser le SDK, créer un admin realm, etc.)
- **Alignement architecture** : Respecter strictement les patterns, conventions et structure de `unionflow` (packages, annotations, nommage, organisation)

## Notes Spécifiques

- **Pas de base de données locale** : Sauf pour l'audit (optionnel, configurable)
- **Tous les appels Keycloak** : Via Admin REST API uniquement
- **UI PrimeFaces Freya** : Utiliser les composants PrimeFaces 14.0.5 avec thème Freya
- **Tests** : Minimum 80% de couverture (comme unionflow avec Jacoco)
- **Documentation** : En français (comme unionflow)