8 · Documentation et Connaissance Métier

8.1 État de la Documentation Technique

Audit Exhaustif (via scripts audit_tool.py)

Exemple de Javadoc Manquante (God Class)

​x
// app-pre-main/src/.../controller/EcSatPreWkf001Controller.java
/**
 * Contrôleur workflow WKF001.
 * TODO: compléter documentation
 */
@Controller
public class EcSatPreWkf001Controller {

    // ❌ Aucune Javadoc sur méthode publique critique
    public String traiterIncident(IncidentDTO incident) {
        // 350 lignes de code...
    }

    // ❌ Pas de @param, @return, @throws
    public List<Tache> getTachesEnAttente(String acteur, Date debut, Date fin) {
        // ...
    }
}

Recommandations Documentation

1. Court terme (0–3 mois)

   • ✅ Créer package-info.java pour 35 modules (effort : 7 j/h)

   • ✅ Documenter 14 God Classes (méthodes publiques uniquement) — effort : 10 j/h

   • ✅ Générer diagrammes C4 niveau 1–2 (Context + Container) — effort : 3 j/h

2. Moyen terme (3–6 mois) — si Option A (Refactoring) retenue

   • Documenter toutes APIs publiques (cible 80% couverture) — effort : 25 j/h

   • Créer 15 ADRs pour décisions architecturales passées — effort : 5 j/h

   • Reverse engineering User Stories depuis code + interviews PO — effort : 15 j/h

3. Option B (Greenfield) — Documentation Native

   • ✅ Documentation First : Javadoc obligatoire pour tout nouveau code (Checkstyle enforced)

   • ✅ ADRs systématiques : toute décision architecture documentée (template Markdown)

   • ✅ Living Documentation : génération automatique doc depuis tests BDD (Cucumber)

8.2 Connaissance Métier — Risques Identifiés

Bus Factor Analysis

Actions Urgentes

1. Event Storming SIAS (2 semaines) — capturer processus métier complets

   • Participants : PO SIAS, architecte, 3 développeurs seniors

   • Livrable : 200+ User Stories, diagramme événements métier

2. Knowledge Transfer Sessions (1 mois)

   • 10 sessions × 2h avec experts techniques

   • Enregistrement vidéo + transcription

   • Création documentation "How-To" (Confluence)

3. Pair Programming Systématique (continu)

   • Rotation développeurs juniors ↔ seniors

   • Code review obligatoire (≥2 reviewers par PR)

9 · Tests et Qualité

9.1 Couverture de Tests — État Actuel

⚠️ Absence de Données Empiriques

• JaCoCo non configuré dans POMs Maven

• Aucun rapport de couverture disponible dans /target/

• Estimation par inspection manuelle (via Glob "**/*Test.java") :

Exemples de Tests Existants

xxxxxxxxxx
// Exemple test unitaire basique (utilitaire)
@Test
public void testDateFormatter() {
    String result = DateUtils.formatToFrench(new Date());
    assertNotNull(result);
    assertTrue(result.matches("\\d{2}/\\d{2}/\\d{4}"));
}

// ❌ Aucun test sur logique métier critique
// Ex: pas de test pour TraitementMasseServiceImpl (44 dépendances, 380 LOC)

Métrique Qualité Estimée

xxxxxxxxxx
Couverture globale estimée : 25–35% (LOC testés / LOC total)
Cible recommandée : ≥80% (ISO 25010 — Software Product Quality)
Déficit : ~45–55% → effort 60–80 j/h pour rattrapage complet

9.2 Stratégie Tests — Option B (Greenfield)

Test Pyramid (approche moderne)

xxxxxxxxxx
                  ▲
                 / \
                /   \
               / E2E \ ← 5% (Selenium, Cypress)
              /_______\
             /         \
            / Intégrat. \ ← 15% (TestContainers, Spring Test)
           /_____________\
          /               \
         /    Unitaires    \ ← 80% (JUnit 5, Mockito, AssertJ)
        /___________________\

Outils et Frameworks Cibles

BDD (Behavior-Driven Development) — Recommandé

xxxxxxxxxx
# features/incident_creation.feature
Fonctionnalité: Création d'incident SIAS depuis SPQR

  Contexte:
    Étant donné un opérateur SIAS authentifié
    Et un compteur matricule "GZ78459032" valide dans le référentiel

  Scénario: Création incident fuite de gaz priorité P1
    Quand SPQR envoie une requête de création incident avec :
      | type       | FUITE_GAZ |
      | priorite   | P1        |
      | adresse    | 12 Rue de la Paix, 75002 Paris |
      | matricule  | GZ78459032 |
    Alors l'incident est créé avec succès
    Et un identifiant incident est retourné
    Et une notification est envoyée au topic Kafka "sias.incidents.created"
    Et l'opérateur SIAS reçoit une alerte email dans les 30 secondes

Implémentation avec Cucumber

xxxxxxxxxx
@SpringBootTest
@CucumberContextConfiguration
public class IncidentCreationSteps {

    @Autowired
    private IncidentService incidentService;

    @Autowired
    private KafkaTemplate<String, IncidentEvent> kafkaTemplate;

    private IncidentDTO createdIncident;

    @Quand("SPQR envoie une requête de création incident avec :")
    public void spqr_envoie_requete(DataTable dataTable) {
        Map<String, String> data = dataTable.asMap(String.class, String.class);
        IncidentCreateRequest request = IncidentCreateRequest.builder()
            .type(IncidentType.valueOf(data.get("type")))
            .priorite(Priorite.valueOf(data.get("priorite")))
            .adresse(data.get("adresse"))
            .matriculeCompteur(data.get("matricule"))
            .build();

        createdIncident = incidentService.createIncident(request);
    }

    @Alors("l'incident est créé avec succès")
    public void incident_cree_succes() {
        assertThat(createdIncident).isNotNull();
        assertThat(createdIncident.getId()).isNotNull();
    }
}

Couverture Cible Option B