From 21f3703fbc24d12de77b5c16d68d1432070234d9 Mon Sep 17 00:00:00 2001
From: dahoud <dahoud@dgbf.ci>
Date: Wed, 18 Feb 2026 16:15:48 +0000
Subject: [PATCH] refactoring

---
 README.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 162 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6e924d0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,162 @@
+# lions-user-manager-server-impl-quarkus
+
+> Backend REST Quarkus — Gestion des utilisateurs, rôles et realms via Keycloak Admin API
+
+## Dépôt Git
+
+`https://git.lions.dev/lionsdev/lions-user-manager-server-impl-quarkus`
+
+---
+
+## Responsabilités
+
+- Exposition d'une API REST sécurisée (OIDC)
+- Gestion CRUD des utilisateurs et rôles Keycloak via Admin API
+- Synchronisation des données entre Keycloak et PostgreSQL
+- Audit complet des actions (traçabilité en base)
+- Export / import CSV
+- Health checks, métriques Prometheus, Swagger UI
+
+---
+
+## API REST
+
+| Ressource | Path | Description |
+|-----------|------|-------------|
+| Utilisateurs | `GET/POST/PUT/DELETE /api/users` | CRUD utilisateurs |
+| Export CSV | `GET /api/users/export/csv` | Export utilisateurs au format CSV |
+| Import CSV | `POST /api/users/import/csv` | Import en masse |
+| Rôles | `GET/POST/DELETE /api/roles` | Gestion des rôles par realm |
+| Audit | `GET /api/audit` | Consultation des logs |
+| Analytics | `GET /api/audit/analytics/*` | Statistiques d'activité |
+| Sync | `POST /api/sync` | Déclencher une synchronisation |
+| Sync status | `GET /api/sync/status` | Dernier statut de sync |
+| Sync check | `GET /api/sync/consistency` | Vérification de cohérence |
+| Realms | `GET /api/realms` | Liste des realms autorisés |
+| Assignments | `GET/POST/DELETE /api/realm-assignments` | Assignation realm/utilisateur |
+
+Documentation complète : `https://api.lions.dev/lions-user-manager/q/swagger-ui`
+
+---
+
+## Stack
+
+| Composant | Technologie |
+|-----------|-------------|
+| Framework | Quarkus 3.17.8 |
+| API | Quarkus REST (RESTEasy Reactive) + Jackson |
+| Auth | `quarkus-oidc` (Keycloak) |
+| Admin | `quarkus-keycloak-admin-rest-client` |
+| ORM | Hibernate ORM Panache |
+| Base de données | PostgreSQL 15 |
+| Migration | Flyway |
+| Health | SmallRye Health |
+| Métriques | Micrometer + Prometheus |
+| Docs | SmallRye OpenAPI (Swagger UI) |
+
+---
+
+## Développement local
+
+### Prérequis
+
+- Java 17+, Maven 3.9+
+- Keycloak sur `localhost:8180`
+- PostgreSQL sur `localhost:5432` (DB : `lions_user_manager`)
+
+### Démarrage
+
+```bash
+mvn quarkus:dev
+```
+
+Swagger UI disponible sur : `http://localhost:8081/q/swagger-ui`
+
+### Configuration dev
+
+Fichier : `src/main/resources/application-dev.properties`
+
+```properties
+quarkus.http.port=8081
+quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/lions_user_manager
+quarkus.oidc.auth-server-url=http://localhost:8180/realms/lions-user-manager
+```
+
+---
+
+## Configuration production
+
+Fichier : `src/main/resources/application-prod.properties`
+
+Toutes les valeurs sensibles sont passées via variables d'environnement :
+
+| Variable | Description |
+|----------|-------------|
+| `DB_HOST` | Hôte PostgreSQL |
+| `DB_PORT` | Port (défaut : 5432) |
+| `DB_NAME` | Nom de la base (défaut : lions_user_manager) |
+| `DB_USERNAME` | Utilisateur PostgreSQL |
+| `DB_PASSWORD` | Mot de passe PostgreSQL |
+| `KEYCLOAK_AUTH_SERVER_URL` | URL du realm Keycloak |
+| `KEYCLOAK_SERVER_URL` | URL base Keycloak |
+| `KEYCLOAK_ADMIN_USERNAME` | Admin Keycloak |
+| `KEYCLOAK_ADMIN_PASSWORD` | Mot de passe admin Keycloak |
+| `CORS_ORIGINS` | Origines CORS autorisées |
+
+---
+
+## Build
+
+```bash
+# Build standard (développement)
+mvn clean package -DskipTests
+
+# Build production
+mvn clean package -P prod -DskipTests
+```
+
+---
+
+## Déploiement (lionsctl)
+
+```bash
+lionsctl pipeline \
+  -u https://git.lions.dev/lionsdev/lions-user-manager-server-impl-quarkus \
+  -b main -j 17 -e production -c k1 -p prod
+```
+
+**Pipeline** : clone → `mvn package -P prod` → `docker build -f Dockerfile.prod` → push `registry.lions.dev` → `kubectl apply` → health check
+
+**URL prod** : `https://api.lions.dev/lions-user-manager`
+
+---
+
+## Tests
+
+```bash
+# Unitaires
+mvn test
+
+# Intégration (Testcontainers)
+mvn verify
+```
+
+---
+
+## Structure
+
+```
+src/main/java/dev/lions/user/manager/server/impl/
+├── entity/          # Entités JPA (AuditLogEntity, SyncHistoryEntity, ...)
+├── mapper/          # MapStruct mappers
+├── repository/      # Repositories Panache
+├── resource/        # Resources JAX-RS (UserResource, RoleResource, ...)
+└── service/
+    └── impl/        # Implémentations des services
+```
+
+---
+
+## Licence
+
+Propriétaire — Lions Dev © 2025