lionsdev/unionflow-mobile-apps
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7e9b1c0bdb806a07b7b83839e88959d760b6761f
unionflow-mobile-apps/PROMPT_LIONS_USER_MANAGER_CORRIGE.md
dahoud 3b9ffac8cd Refactoring - Version OK
2025-11-17 16:02:04 +00:00

19 KiB
Raw Blame History

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 
    @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) : 
    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 : 
    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)