lib

[Ghaith-kh]

Mission : Analyse et refactoring des librairies de modèles partagées

Contexte

Je suis architecte Java chez LCL (banque française). J'ai deux groupes de
microservices Spring Boot qui communiquent entre eux. Chaque groupe utilise
sa propre librairie de modèles partagée en interne :

• Groupe A : utilise la lib [NOM_LIB_A] (chemin : [CHEMIN_LIB_A])
  • Microservices consommateurs : [liste des MS du groupe A]
• Groupe B : utilise la lib [NOM_LIB_B] (chemin : [CHEMIN_LIB_B])
  • Microservices consommateurs : [liste des MS du groupe B]

J'ai l'intuition (à valider par toi) qu'une grande partie des entités sont
quasi-identiques entre les deux libs, avec seulement quelques variations
mineures. Je veux fusionner les deux libs en une seule lcl-shared-models
si l'analyse confirme que c'est pertinent.

Contraintes techniques

• Java 25
• Spring Boot 3.5.x (parent POM interne lcl-parent héritant de
  spring-boot-starter-parent)
• Build Maven, déploiement sur Nexus interne, multi-repo Git
• Conformité PCI-DSS et RGPD obligatoire
• GitLab CI/CD avec SonarQube et JFrog Xray
• Package racine cible : com.lcl.shared.models

Phase 1 : Analyse (OBLIGATOIRE avant toute génération)

Avant d'écrire la moindre ligne de code, tu dois produire une analyse
structurée. Procède dans cet ordre :

1.1 Inventaire des deux librairies

Pour chaque lib, liste :

• Toutes les classes/records/enums exposés
• Leur package
• Leurs champs (nom, type, annotations)
• Leurs dépendances externes (Jackson, Lombok, validation, JPA, etc.)
• Leur version Spring Boot / Java cible

1.2 Inventaire des usages dans les microservices

Pour chaque microservice consommateur, identifie :

• Quelles classes de la lib sont importées
• Comment elles sont utilisées (entité JPA ? DTO d'API ? message Kafka ?)
• Si le microservice étend, surcharge ou contourne certaines classes
• Si le microservice définit déjà ses propres DTOs en parallèle

1.3 Matrice de comparaison

Produis une matrice (tableau Markdown) qui croise les entités équivalentes
entre les deux libs :

Entité Lib A	Entité Lib B	Champs identiques	Champs divergents	Décision

Pour la colonne "Décision", choisis parmi :

• FUSION : entités quasi-identiques, fusion directe possible
• FUSION + EXTENSION : fusion avec champs optionnels pour couvrir les
  variantes
• SÉPARATION : les divergences sont métier et justifient deux modèles
  distincts
• VALUE OBJECT COMMUN : extraire un sous-ensemble (ex: PostalAddress)
  qui sera commun, mais garder les agrégats séparés

1.4 Détection des anti-patterns

Identifie dans les libs existantes :

• Les "God Models" (trop de champs, trop de responsabilités)
• Les couplages indésirables (annotations JPA dans une lib partagée,
  dépendances Spring Web, etc.)
• Les violations PCI-DSS potentielles (champs sensibles sans masquage,
  toString() qui exposent des données)
• Les modèles utilisés par un seul microservice (qui ne devraient pas
  être dans la lib partagée selon la règle "2+ microservices de 2+
  applications distinctes")

1.5 Recommandation finale

Sur la base de l'analyse, donne ta recommandation argumentée :

• GO pour la fusion : si >70% des entités relèvent de FUSION ou
  FUSION + EXTENSION
• GO partiel : si une partie justifie la fusion mais qu'il faut
  garder des libs séparées pour certains domaines
• NO GO : si les divergences sont trop importantes et qu'une lib
  lcl-commons-types (uniquement les value objects de base) serait
  plus pertinente

Stop ici et attends ma validation explicite avant de passer à la Phase 2.

Phase 2 : Génération de la première version (uniquement après mon GO)

Une fois ma validation reçue, génère le projet avec :

2.1 Structure Maven multi-module

• pom.xml parent héritant de lcl-parent avec <relativePath/> vide
• Modules :
  • lcl-shared-models-types : value objects de base (Amount, Currency,
    Iban, Bic, MaskedPan, etc.)
  • lcl-shared-models-core : entités/agrégats métier issus de la fusion
  • lcl-shared-models-validation : validateurs Jakarta Bean Validation
    custom
• dependencyManagement (pas dependencies)
• Aucune dépendance Spring Boot runtime imposée aux consommateurs

2.2 Modèles

• Records Java 25 quand pertinent, sinon classes immutables avec Lombok
  @Value
• Javadoc complète en français
• Annotations Jackson déterministes (@JsonInclude(NON_NULL), ordre des
  champs explicite)
• Validation Jakarta Bean Validation
• Pas d'annotations JPA, pas de Spring Web, pas de logique métier

2.3 Value objects PCI-DSS

• MaskedPan, Iban, Bic, Amount, Currency
• toString() qui n'exposent jamais de données sensibles en clair

2.4 Validateurs custom

• @ValidIban (algo MOD-97), @ValidBic, @ValidCurrency,
  @SafePostalAddress

2.5 Tests

• JUnit 5 + AssertJ avec @Nested / @DisplayName
• Couverture ≥ 90% sur value objects et validateurs
• Tests de sérialisation Jackson round-trip
• Tests de validation Bean Validation

2.6 Documentation

• README.md : philosophie, règle d'inclusion (2+ MS de 2+ applis),
  guide d'utilisation côté consommateur avec exemple MapStruct modèle ↔ DTO
• CONTRIBUTING.md : process d'ajout d'un nouveau modèle
• ADR/0001-fusion-libs-partagees.md : Architecture Decision Record
  documentant la décision (avec les conclusions de ton analyse Phase 1)
• MIGRATION.md : guide de migration pour les microservices consommateurs
  (mapping ancienne classe → nouvelle classe)

2.7 Versioning et compatibilité

• SemVer strict, BREAKING_CHANGES.md
• revapi-maven-plugin ou japicmp-maven-plugin pour détection de
  ruptures binaires

2.8 CI/CD GitLab

.gitlab-ci.yml avec stages : build, test (+ JaCoCo), quality (SonarQube),
security (JFrog Xray), deploy (Nexus, sur tags Git uniquement)

Anti-patterns à proscrire

• Annotations JPA dans la lib partagée
• Dépendance sur Spring Web / Spring Data
• Logique métier dans les entités (rester anémique)
• "God Models" avec trop de champs optionnels pour satisfaire tout le monde
• Getters/setters mutables
• Inclusion de modèles utilisés par un seul microservice

Workflow attendu

1. Tu lis et analyses le code des deux libs et des microservices consommateurs
2. Tu produis le rapport d'analyse complet (Phase 1)
3. Tu t'arrêtes et attends ma validation
4. Une fois validé, tu génères la lib (Phase 2)
5. Tu termines par un récapitulatif