Socle V004 – Introduction

Écrit par

dans

01 – Introduction au Socle V4

Version : 4.0.0 Date : 2025-01-25

1. Qu’est-ce que le Socle V4 ?

Le Socle V4 est un framework Java de grade production construit sur Spring Boot 3.2.1 qui implémente le pattern MOP (Main Orchestrator Process). Il fournit une base solide pour construire des applications d’entreprise robustes et observables.

Évolution depuis V3

Le Socle V4 conserve et étend l’architecture V3 en ajoutant :

Nouveauté V4	Description
H2 TechDB	Base embarquée pour état technique (remplace Nitrite)
Log4j2	Framework logging haute performance (remplace Logback)
LogForwarder	Centralisation des logs vers LogHub (HTTP/NATS)
SocleAuthClient	Client authentification JWT
WorkerRegistryClient	Auto-enregistrement des workers
StatusDashboard	Dashboard HTML de supervision temps réel (port 9374)
Pipeline V2	Pipeline asynchrone avec garantie at-least-once (Queue/Claim/Ack)

2. Philosophie « MOP Pilote Tout »

Le Main Orchestrator Process est le cœur du framework :

┌─────────────────────────────────────────────────────────────────┐
│                           MOP                                    │
│  - Orchestre tous les Workers                                   │
│  - Gère le lifecycle (start/stop)                               │
│  - Appelle doWork() automatiquement                             │
│  - Garantit le shutdown gracieux                                │
└─────────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         ▼                    ▼                    ▼
    ┌─────────┐         ┌─────────┐         ┌─────────┐
    │ Worker  │         │ Worker  │         │  HTTP   │
    │ Métier  │         │ Métier  │         │ Worker  │
    └─────────┘         └─────────┘         └─────────┘

Principes clés

Orchestration centralisée : Le MOP contrôle tout le lifecycle
Démarrage ordonné : Workers par priorité (petit → grand), HTTP en dernier
Arrêt gracieux : HTTP d’abord (drain), puis Workers
Scheduling automatique : doWork() appelé selon cron ou interval

3. Les 4 principes fondamentaux V4

3.1 Portabilité

Fonctionne sur ARM/AMD64, Linux/macOS
Aucune dépendance serveur externe obligatoire
Base H2 embarquée pour l’état technique

3.2 Sécurité

Aucun port entrant sur les NUC/agents
Communication sortante uniquement (HTTP/NATS)
Authentification JWT pour les services centraux

3.3 Observabilité

Logs centralisés via LogForwarder
Corrélation par correlationId / execId
Suivi des workers via Registry

3.4 Standardisation

Même authentification partout
Même format de logs
Même enregistrement des workers

4. Stack technique

Composant	Version	Usage
Java	21 LTS	Runtime
Spring Boot	3.2.1	Framework
Log4j2	2.22.1	Logging (nouveau V4)
LMAX Disruptor	4.0.0	AsyncLoggers
H2	2.2.x	Base technique embarquée (nouveau V4)
Kafka	3.6.0	Messaging
NATS	2.17.0	Messaging
Redisson	3.24.3	Redis client
OkHttp	4.12.0	HTTP client
Micrometer	1.12.0	Metrics

5. Composants du Socle

Composants V3 (conservés)

Package	Description
`mop`	Main Orchestrator Process
`worker`	Interface Worker
`config`	SocleConfiguration
`kv`	KvBus (in_memory / Redis)
`shared`	SharedDataRegistry
`supervisor`	Supervision heartbeats
`http`	HttpWorker, TomcatManager
`admin`	AdminRestApi
`metrics`	SocleMetrics
`pipeline`	PipelineEngine
`resilience`	CircuitBreaker, Retry
`scheduler`	WorkerScheduler
`security`	AdminAuthFilter, RateLimit

Nouveaux composants V4

Package	Description
`techdb`	H2 TechDB Manager
`logging`	Log4j2 + LogForwarder
`client/auth`	SocleAuthClient
`client/registry`	WorkerRegistryClient

6. Cas d’usage

Le Socle V4 est idéal pour :

Agents de collecte (DB2 Journal Reader, CDC)
Services de synchronisation (ODH-sync)
Proxies et bridges (Kafka Proxy)
Workers de traitement (ETL, pipelines)
Services multi-région (MTQ, GUA, REU, etc.)

7. Prérequis

Développement

JDK 21+
Maven 3.9+
IDE (IntelliJ IDEA recommandé)

Production

JRE 21+
Docker (optionnel)
Accès NATS ou HTTP pour LogForwarder (optionnel)

8. Premiers pas

# Cloner le projet
git clone <repo>/socle-v004.git

# Build
cd socle-v004
mvn clean package -DskipTests

# Run
java -jar target/socle-v004-4.0.0.jar

# Vérifier
curl http://localhost:8080/health

9. Documentation

Document	Description
02-ARCHITECTURE	Architecture détaillée
03-QUICKSTART	Guide de démarrage
08-SUPERVISOR	Supervision et heartbeats
09-PIPELINE	Pipeline V1 et V2
21-H2-TECHDB	Base H2 (V4)
22-LOG4J2-LOGFORWARDER	Logging V4
25-MIGRATION-V3-V4	Migration
27-STATUS-DASHBOARD	Dashboard supervision
GUIDE-METHODOLOGIQUE	Bonnes pratiques