project-mobile-command/docs/COHERENCE_ANALYSIS.md

Analyse de Cohérence - Mobile Command Project

Date: 2 décembre 2025 Status: Projet incomplet - Modules non intégrés

---

🎯 Résumé Exécutif

Le projet Mobile Command présente une architecture solide et un code de qualité, mais souffre d'un problème critique : seul 1 module sur 7 est actif. Les modules ont été développés mais jamais intégrés dans la boucle principale.

Verdict : 70% théorique, 30% fonctionnel

---

✅ Ce Qui Existe (Code Écrit)

Modules Core (Game-Agnostic)

Tous implémentés et fonctionnels en isolation :

1. ResourceModule (src/modules/core/ResourceModule.cpp - 478 lignes)

   • Inventaire avec stack limits
   • Système de craft avec queue
   • Recipes inputs/outputs
   • Topics pub/sub: resource:craft_complete, resource:inventory_low, resource:inventory_changed
   • Hot-reload avec state preservation ✅

2. CombatModule (src/modules/core/CombatModule.cpp - 581 lignes)

   • Combat Rimworld-style (auto-résolution)
   • Formules: hit chance, damage, armor reduction, morale
   • System de rounds avec casualties
   • Topics pub/sub: combat:started, combat:round_complete, combat:ended
   • Hot-reload avec state preservation ✅

3. StorageModule (src/modules/core/StorageModule.cpp)

   • Save/load game states
   • Serialization JSON
   • Topics pub/sub: storage:save_complete, storage:load_complete

4. EventModule (src/modules/core/EventModule.cpp)

   • Système d'événements scriptés
   • Choix multiples avec conséquences
   • Topics pub/sub: event:triggered, event:choice_made, event:outcome

Modules MC-Specific

5. GameModule (src/modules/GameModule.cpp - 463 lignes)

   • State machine: MainMenu, TrainBuilder, Expedition, Combat, Event, Pause
   • Event handlers pour TOUS les core modules (lignes 216-309)
   • Logique MC-specific bien isolée:
     • handleDroneCrafted() - pub vers expedition:drone_available
     • handleLowSupplies() - warnings fuel/ammo/medical
     • handleCombatVictory() - fame/reputation (placeholder)
   • Hot-reload complet ✅
   • C'EST LE SEUL MODULE ACTIF 🔴

6. TrainBuilderModule (src/modules/mc_specific/TrainBuilderModule.cpp)

   • Gestion des wagons
   • Système de balance (latéral/longitudinal)
   • Topics pub/sub: train:composition_changed, train:performance_updated

7. ExpeditionModule (src/modules/mc_specific/ExpeditionModule.cpp)

   • Lancement d'expéditions
   • Composition team (humains + drones)
   • Topics pub/sub: expedition:started, expedition:progress, expedition:returned

Configuration Files

Tous les fichiers de config existent dans config/ :

• ✅ game.json - GameModule settings
• ✅ resources.json - 10+ resources, 5+ recipes
• ✅ combat.json - Formulas, rules
• ✅ events.json - 5+ événements scriptés
• ✅ train.json - Wagons definitions
• ✅ expeditions.json - Destinations
• ✅ storage.json - Save paths

---

❌ Le Problème Critique

Dans src/main.cpp lignes 115-117 :

std::vector<std::pair<std::string, std::string>> moduleList = {
    {"GameModule", "game.json"},
    // ← TOUS LES AUTRES MODULES MANQUENT ICI
};

Conséquence :

• GameModule tourne seul dans la boucle principale
• GameModule subscribe à tous les topics (lignes 52-69)
• MAIS aucun module ne publie car ils ne sont pas instanciés
• Le pub/sub est câblé mais inactif

Diagramme du Système Actuel

┌─────────────────────────────────────┐
│  main.cpp - Loop 10Hz               │
│  ├─ Load GameModule ✅              │
│  ├─ Load ResourceModule ❌          │
│  ├─ Load CombatModule ❌            │
│  ├─ Load StorageModule ❌           │
│  ├─ Load EventModule ❌             │
│  ├─ Load TrainBuilderModule ❌      │
│  └─ Load ExpeditionModule ❌        │
└─────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────┐
│  GameModule (actif)                 │
│  ├─ Subscribe to resource:* ✅     │
│  ├─ Subscribe to combat:* ✅       │
│  ├─ Subscribe to storage:* ✅      │
│  ├─ Subscribe to event:* ✅        │
│  └─ ... attend des messages ...    │
│      qui n'arrivent JAMAIS 🔴      │
└─────────────────────────────────────┘

ResourceModule, CombatModule, etc.
→ Code existe mais ne tourne pas
→ Fichiers .cpp compilés mais .so jamais loadés

---

🔍 Analyse Détaillée

1. Architecture Pub/Sub Orpheline

GameModule.cpp lignes 44-72 :

void GameModule::setupEventSubscriptions() {
    // Subscribe to ResourceModule events
    m_io->subscribe("resource:craft_complete");     // ← Personne ne publie
    m_io->subscribe("resource:inventory_low");      // ← Personne ne publie

    // Subscribe to CombatModule events
    m_io->subscribe("combat:started");              // ← Personne ne publie
    m_io->subscribe("combat:ended");                // ← Personne ne publie

    // etc...
}

Les handlers existent (lignes 216-309) mais ne sont jamais appelés.

2. Event Handlers Inutilisés

GameModule.cpp lignes 217-236 :

void GameModule::onResourceCraftComplete(const grove::IDataNode& data) {
    // MC-SPECIFIC LOGIC: Check if this is a drone
    if (recipe.find("drone_") == 0) {
        handleDroneCrafted(recipe);  // Jamais exécuté
    }
}

Cette logique MC-specific intelligente ne tourne jamais car ResourceModule n'existe pas dans le runtime.

3. Config Files Orphelins

• config/resources.json (2406 bytes) - Parse par ResourceModule qui n'existe pas
• config/combat.json (1342 bytes) - Parse par CombatModule qui n'existe pas
• config/events.json (7317 bytes) - Parse par EventModule qui n'existe pas

4. Hot-Reload Implémenté mais Inutile

Tous les modules ont getState()/setState() implémentés pour hot-reload... mais seul GameModule peut être hot-reloadé car c'est le seul chargé.

---

📊 Metrics du Problème

Aspect	Planifié	Implémenté	Actif	Gap
Modules Core	4	4 (100%)	0 (0%)	-100%
Modules MC	3	3 (100%)	1 (33%)	-67%
Config Files	7	7 (100%)	1 (14%)	-86%
Pub/Sub Topics	~20	~20 (100%)	0 (0%)	-100%
Loop Complet	1	0 (0%)	0 (0%)	-100%

Total: 70% code écrit, 15% fonctionnel

---

🛠️ Solution (5 Minutes de Fix)

Étape 1: Modifier src/main.cpp lignes 115-122

Remplacer :

std::vector<std::pair<std::string, std::string>> moduleList = {
    {"GameModule", "game.json"},
};

Par :

std::vector<std::pair<std::string, std::string>> moduleList = {
    // Core modules (game-agnostic)
    {"ResourceModule", "resources.json"},
    {"StorageModule", "storage.json"},
    {"CombatModule", "combat.json"},
    {"EventModule", "events.json"},

    // MC-specific modules
    {"TrainBuilderModule", "train.json"},
    {"ExpeditionModule", "expeditions.json"},

    // Game orchestrator (MC-specific)
    {"GameModule", "game.json"},
};

Étape 2: Rebuild

cmake --build build --target modules

Étape 3: Run

cd build && ./mobilecommand

Résultat attendu :

• 7 modules chargés au lieu de 1
• Pub/sub topics actifs
• Loop complet fonctionnel
• Hot-reload de tous les modules

---

🎓 Leçons Apprises

Ce Qui a Bien Fonctionné

1. Architecture modulaire - Clean separation core/MC-specific
2. Pub/sub design - Modules découplés correctement
3. Hot-reload - State preservation bien implémenté
4. Code quality - Logging, error handling, RAII

Ce Qui a Échoué

1. Intégration incrémentale manquante - Modules développés en isolation
2. Pas de tests d'intégration - Aucune validation du système complet
3. Sur-planification - Documentation détaillée mais exécution partielle
4. Validation tardive - Problème découvert après 7 modules écrits

Pattern Anti-Pattern Identifié

"Waterfall Module Development" :

Plan → Write GameModule → Write ResourceModule → Write CombatModule → ...
                                                                      ↑
                                                        Discover integration issue HERE

Meilleure approche :

Plan → Write GameModule → INTEGRATE → Test
    → Write ResourceModule → INTEGRATE → Test loop
    → Write CombatModule → INTEGRATE → Test loop
    → etc.

---

📝 Recommandations Futures

Pour Ce Projet

1. Activer tous les modules (5 min)
2. Créer un test d'intégration :

   // Test: craft resource → trigger event → start combat
   io->publish("resource:craft_request", droneRecipe);
   // Wait for craft_complete
   // Verify GameModule received it
   // Verify drone added to expedition system
   

3. Valider le loop complet avec logs verbose
4. Documenter les dépendances entre modules

Pour Futurs Projets

1. Intégration continue - Ne jamais écrire plus de 1-2 modules sans intégrer
2. Tests d'intégration dès le début - Valider pub/sub immédiatement
3. Main.cpp comme source de vérité - Si pas dans moduleList, n'existe pas
4. Hot-reload comme validation - Si un module hot-reload, il est actif

---

🔗 Références

• Architecture détaillée: docs/MODULES_ARCHITECTURE.md
• Plan prototype: plans/PROTOTYPE_PLAN.md
• Instructions dev: CLAUDE.md
• Code analysis: Ce document

---

⚠️ Status Actuel du Projet

État : Prototype incomplet Cause : Modules non intégrés dans main loop Effort pour fix : ~5 minutes (7 lignes de code) Effort de développement investi : ~3000 lignes de code + docs ROI actuel : 15% (seul GameModule utilisable)

Prochain commit devrait : Activer tous les modules et valider l'intégration

---

Document créé pour analyse post-mortem et guide de résolution