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 :

```cpp
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** :
```cpp
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** :
```cpp
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** :
```cpp
std::vector<std::pair<std::string, std::string>> moduleList = {
    {"GameModule", "game.json"},
};
```

**Par** :
```cpp
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

```bash
cmake --build build --target modules
```

### Étape 3: Run

```bash
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** :
   ```cpp
   // 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*