project-mobile-command/plans/SHARED_MODULES_PLAN.md

# Plan de Modules Partagés - Mobile Command & WarFactory

**Objectif**: Créer une bibliothèque de modules GroveEngine réutilisables entre les deux projets.

**Date**: 1er décembre 2025
**Version**: grove-modules v0.1.0

---

## Vision

### Problème
- Mobile Command et WarFactory partagent de nombreux systèmes (ressources, économie, combat)
- Dupliquer le code = 2x bugs, 2x maintenance, 2x développement
- GroveEngine permet modules hot-reloadable indépendants

### Solution
Créer une **bibliothèque de modules core** partagée entre les projets, avec des **adaptateurs spécifiques** par jeu.

---

## Architecture Proposée

### Structure
```
../grove-modules/               # Bibliothèque partagée
├── core/                       # Modules 100% réutilisables
│   ├── ResourceModule/
│   ├── StorageModule/
│   ├── EconomyModule/
│   └── EventModule/
├── common/                     # Modules 60-80% réutilisables
│   ├── CombatModule/
│   ├── TransportModule/
│   ├── TechTreeModule/
│   └── MapModule/
├── CMakeLists.txt
└── README.md

../mobilecommand/
├── src/modules/
│   ├── mc_adapters/            # Adaptateurs MC-spécifiques
│   │   ├── MCResourceAdapter.cpp
│   │   └── MCCombatAdapter.cpp
│   ├── TrainBuilderModule/     # MC-only
│   ├── ExpeditionModule/       # MC-only
│   └── DroneModule/            # MC-only
└── external/
    ├── GroveEngine/            # Symlink
    └── grove-modules/          # Symlink

../warfactoryracine/
├── modules/
│   ├── wf_adapters/            # Adaptateurs WF-spécifiques
│   │   ├── WFResourceAdapter.cpp
│   │   └── WFCombatAdapter.cpp
│   ├── factory/                # WF-only
│   ├── vehicle_design/         # WF-only
│   └── doctrine/               # WF-only
└── external/
    └── grove-modules/          # Symlink
```

---

## Modules Core (grove-modules/core/)

### ResourceModule
**Réutilisabilité: 90%**

**Responsabilités communes**:
- Inventaire (add/remove/query)
- Stack management
- Quality grades (poor/normal/good/excellent)
- Craft system (inputs → outputs)
- Resource constraints

**Interface commune**:
```cpp
class IResourceManager {
    virtual bool addResource(string id, int quantity, Quality quality) = 0;
    virtual bool removeResource(string id, int quantity) = 0;
    virtual int getResourceCount(string id) = 0;
    virtual bool canCraft(string recipe_id) = 0;
    virtual void craft(string recipe_id) = 0;
};
```

**Configuration commune**:
```json
{
  "resources": {
    "resource_id": {
      "name": "Display Name",
      "maxStack": 100,
      "weight": 1.5,
      "baseValue": 10,
      "category": "material"
    }
  },
  "recipes": {
    "recipe_id": {
      "inputs": {"resource_a": 2, "resource_b": 1},
      "outputs": {"resource_c": 1},
      "craftTime": 30.0
    }
  }
}
```

**Adaptateurs spécifiques**:
- **MC**: Scavenge, munitions, fuel, timeline evolution (2022→2025)
- **WF**: Minerais, composants industriels, quality impact production

**Fichiers**:
- `grove-modules/core/ResourceModule/ResourceModule.cpp`
- `grove-modules/core/ResourceModule/ResourceModule.h`
- `grove-modules/core/ResourceModule/IResourceManager.h`

---

### StorageModule
**Réutilisabilité: 95%**

**Responsabilités communes**:
- Save game complet (JSON)
- Load game complet
- Auto-save périodique
- Versioning
- State serialization

**Interface commune**:
```cpp
class IStorageManager {
    virtual bool saveGame(string filename) = 0;
    virtual bool loadGame(string filename) = 0;
    virtual void collectModuleStates(vector<IDataNode*> states) = 0;
    virtual void restoreModuleStates(const IDataNode& saveData) = 0;
};
```

**Format universel**:
```json
{
  "version": "1.0.0",
  "game": "MobileCommand",  // ou "WarFactory"
  "timestamp": "2025-12-01T10:00:00Z",
  "gameTime": 3600.0,
  "modules": {
    "ModuleName": { /* module state */ }
  }
}
```

**Adaptateurs spécifiques**:
- **MC**: Expedition history, commander deaths
- **WF**: Factory blueprints, tech tree progress

**Fichiers**:
- `grove-modules/core/StorageModule/StorageModule.cpp`
- `grove-modules/core/StorageModule/IStorageManager.h`

---

### EconomyModule
**Réutilisabilité: 85%**

**Responsabilités communes**:
- Prix dynamiques (offre/demande)
- Marchés/trading
- Inflation/deflation
- Transaction history

**Interface commune**:
```cpp
class IEconomyManager {
    virtual float getPrice(string resource_id) = 0;
    virtual void updateMarket(string resource_id, int supply_delta) = 0;
    virtual bool buy(string resource_id, int quantity, float& total_cost) = 0;
    virtual bool sell(string resource_id, int quantity, float& total_revenue) = 0;
};
```

**Modèle économique**:
```cpp
// Prix = base * (demand / supply)^elasticity
float price = basePrice * pow(demand / supply, elasticity);

// Avec bounds
price = clamp(price, basePrice * 0.1, basePrice * 10.0);
```

**Adaptateurs spécifiques**:
- **MC**: Marché noir, dons, fame impact prices
- **WF**: Contracts PMC, military-industrial complex

**Fichiers**:
- `grove-modules/core/EconomyModule/EconomyModule.cpp`
- `grove-modules/core/EconomyModule/IEconomyManager.h`

---

### EventModule
**Réutilisabilité: 80%**

**Responsabilités communes**:
- Event scripting (JSON)
- Condition evaluation
- Choice handling
- Outcome application

**Interface commune**:
```cpp
class IEventManager {
    virtual void checkTriggers() = 0;
    virtual void triggerEvent(string event_id) = 0;
    virtual void handleChoice(string event_id, string choice_id) = 0;
    virtual bool evaluateConditions(const IDataNode& conditions) = 0;
};
```

**Format événement universel**:
```json
{
  "event_id": "unique_id",
  "title": "Event Title",
  "description": "Event description text",
  "conditions": {
    "game_time_min": 600,
    "resource_min": {"fuel": 50},
    "custom_flag": "value"
  },
  "choices": [
    {
      "id": "choice_1",
      "text": "Choice text",
      "requirements": {"reputation": 20},
      "outcomes": {
        "resources": {"fuel": -10, "ammo": +50},
        "flags": {"quest_complete": true},
        "trigger_event": "next_event_id"
      }
    }
  ]
}
```

**Adaptateurs spécifiques**:
- **MC**: Survival events, moral impact, commander death
- **WF**: Diplomatic events, faction relations

**Fichiers**:
- `grove-modules/core/EventModule/EventModule.cpp`
- `grove-modules/core/EventModule/IEventManager.h`

---

## Modules Common (grove-modules/common/)

### CombatModule
**Réutilisabilité: 60%**

**Responsabilités communes**:
- Damage calculations
- Armor/penetration
- Hit probability
- Unit health
- Combat resolution

**Interface commune**:
```cpp
class ICombatResolver {
    virtual CombatResult resolveCombat(
        const CombatSetup& setup,
        int maxRounds
    ) = 0;

    virtual float calculateDamage(
        float firepower,
        float armor,
        float penetration
    ) = 0;

    virtual bool checkHit(
        float accuracy,
        float evasion,
        float cover
    ) = 0;
};

struct CombatResult {
    bool victory;
    vector<Casualty> casualties;
    vector<Resource> loot;
    int roundsElapsed;
};
```

**Formules partagées**:
```cpp
// Hit chance
float hit = base_accuracy * (1.0 - cover) * (1.0 - evasion);

// Damage
float damage = max(0, firepower * penetration - armor);

// Casualty check
if (unit_health <= 0) {
    casualties.push_back(unit);
}
```

**Adaptateurs spécifiques**:
- **MC**: Pertes permanentes, moral, drones vs humans
- **WF**: Auto-battler, frontlines, doctrine modifiers

**Fichiers**:
- `grove-modules/common/CombatModule/CombatModule.cpp`
- `grove-modules/common/CombatModule/ICombatResolver.h`

---

### TransportModule
**Réutilisabilité: 70%**

**Responsabilités communes**:
- Pathfinding (A*)
- Route optimization
- Travel time calculation
- Convoy management

**Interface commune**:
```cpp
class ITransportManager {
    virtual Path findPath(Point from, Point to) = 0;
    virtual float calculateTravelTime(Path path, float speed) = 0;
    virtual bool moveConvoy(string convoy_id, Point destination) = 0;
};

struct Path {
    vector<Point> waypoints;
    float totalDistance;
    float estimatedTime;
    int dangerLevel;
};
```

**Adaptateurs spécifiques**:
- **MC**: Train movement, expedition routes
- **WF**: Supply chains, factory logistics

**Fichiers**:
- `grove-modules/common/TransportModule/TransportModule.cpp`
- `grove-modules/common/TransportModule/ITransportManager.h`

---

### TechTreeModule
**Réutilisabilité: 75%**

**Responsabilités communes**:
- Tech progression
- Unlock system
- Dependencies
- Research time/cost

**Interface commune**:
```cpp
class ITechTreeManager {
    virtual bool canResearch(string tech_id) = 0;
    virtual void startResearch(string tech_id) = 0;
    virtual bool isUnlocked(string tech_id) = 0;
    virtual vector<string> getAvailableTechs() = 0;
};
```

**Configuration universelle**:
```json
{
  "technologies": {
    "tech_id": {
      "name": "Technology Name",
      "cost": {"research_points": 100, "credits": 1000},
      "time": 3600.0,
      "prerequisites": ["tech_a", "tech_b"],
      "unlocks": ["feature_x", "recipe_y"]
    }
  }
}
```

**Adaptateurs spécifiques**:
- **MC**: Timeline 2022→2025 (forced progression)
- **WF**: 3000+ techs, player choice

**Fichiers**:
- `grove-modules/common/TechTreeModule/TechTreeModule.cpp`
- `grove-modules/common/TechTreeModule/ITechTreeManager.h`

---

### MapModule
**Réutilisabilité: 50%**

**Responsabilités communes**:
- Chunk system (64x64 tiles)
- Streaming/loading
- Multi-scale (world/regional/local)
- Tile properties

**Interface commune**:
```cpp
class IMapManager {
    virtual Chunk* getChunk(int x, int y) = 0;
    virtual void loadChunk(int x, int y) = 0;
    virtual void unloadChunk(int x, int y) = 0;
    virtual Tile getTile(int x, int y) = 0;
};

struct Chunk {
    int x, y;
    Tile tiles[64][64];
    bool loaded;
    bool modified;
};
```

**Adaptateurs spécifiques**:
- **MC**: Ukraine map statique, expedition sites
- **WF**: Procedural generation, geological sim

**Fichiers**:
- `grove-modules/common/MapModule/MapModule.cpp`
- `grove-modules/common/MapModule/IMapManager.h`

---

## Roadmap de Développement

### Phase 1: Mobile Command Prototype (Mois 1-3)
**Objectif**: Créer modules pour MC, les garder réutilisables

1. **ResourceModule** - Développer pour MC avec interface claire
2. **StorageModule** - Format universel dès le départ
3. **EventModule** - Scripting JSON générique
4. **CombatModule** - Formulas paramétrées

**Livrable**: MC prototype fonctionnel, code dans `src/modules/`

### Phase 2: Extraction Core Library (Mois 4)
**Objectif**: Identifier et extraire le core stable

1. **Audit code MC** - Identifier parties 100% réutilisables
2. **Créer grove-modules/** - Structure de base
3. **Extraire ResourceModule** - Première extraction
4. **Tester réintégration** - MC utilise grove-modules/ResourceModule

**Livrable**: grove-modules/ avec 1 module stable

### Phase 3: Stabilisation Core (Mois 5-6)
**Objectif**: Tous les core modules extraits et stables

1. **Extraire StorageModule** - Save/load universel
2. **Extraire EconomyModule** - Marché dynamique
3. **Extraire EventModule** - Event system
4. **Versioning v1.0.0** - Premier release stable

**Livrable**: grove-modules/core/ complet et versionné

### Phase 4: Common Modules (Mois 7-9)
**Objectif**: Modules partagés avec adaptateurs

1. **CombatModule** - Combat resolver + adaptateurs MC/WF
2. **TransportModule** - Pathfinding + logistics
3. **TechTreeModule** - Progression system
4. **MapModule** - Chunk system base

**Livrable**: grove-modules/common/ complet

### Phase 5: WarFactory Integration (Mois 10-12)
**Objectif**: WF utilise grove-modules

1. **WF setup** - Symlink grove-modules/
2. **Adaptateurs WF** - wf_adapters/ pour customisation
3. **Tests cross-projet** - Valider compatibilité
4. **CI/CD** - Tests automatiques MC + WF

**Livrable**: Les deux projets partagent grove-modules/

---

## Conventions de Code

### Namespaces
```cpp
namespace grove::modules::core {
    class ResourceModule { };
}

namespace grove::modules::common {
    class CombatModule { };
}
```

### Versioning
```cpp
// ResourceModule v1.2.3
#define RESOURCE_MODULE_VERSION_MAJOR 1
#define RESOURCE_MODULE_VERSION_MINOR 2
#define RESOURCE_MODULE_VERSION_PATCH 3
```

### Configuration
```json
{
  "module_version": "1.2.3",
  "game_specific": {
    "mobile_command": { /* MC config */ },
    "war_factory": { /* WF config */ }
  },
  "common": { /* Shared config */ }
}
```

### Topics Pub/Sub
```cpp
// Namespace par module
"resource:craft_complete"
"storage:save_complete"
"economy:price_changed"
"event:triggered"
"combat:ended"
```

---

## Tests Cross-Projet

### Test Framework
```cpp
// grove-modules/tests/ResourceModuleTest.cpp
TEST_CASE("ResourceModule - MC Scenario") {
    ResourceModule module;
    // Test MC-specific behavior
}

TEST_CASE("ResourceModule - WF Scenario") {
    ResourceModule module;
    // Test WF-specific behavior
}
```

### CI/CD Pipeline
```yaml
# .github/workflows/grove-modules.yml
jobs:
  test-mobile-command:
    runs-on: ubuntu-latest
    steps:
      - Checkout grove-modules
      - Checkout mobilecommand
      - Build & test MC with grove-modules

  test-war-factory:
    runs-on: ubuntu-latest
    steps:
      - Checkout grove-modules
      - Checkout warfactoryracine
      - Build & test WF with grove-modules
```

---

## Maintenance

### Semantic Versioning
- **Major**: Breaking changes (interface changes)
- **Minor**: New features (backward compatible)
- **Patch**: Bug fixes

### Release Process
1. Tests passent (MC + WF)
2. Update CHANGELOG.md
3. Tag version (v1.2.3)
4. Update both projects

### Bug Fixes
1. Fix in grove-modules/
2. Test MC
3. Test WF
4. Release patch version

---

## Metrics de Succès

### Court Terme (6 mois)
- [ ] 4 core modules extraits
- [ ] MC utilise grove-modules/
- [ ] 0 duplication code entre MC et grove-modules/

### Moyen Terme (12 mois)
- [ ] 8 modules total (core + common)
- [ ] WF utilise grove-modules/
- [ ] CI/CD tests cross-projet
- [ ] Documentation API complète

### Long Terme (18+ mois)
- [ ] grove-modules/ stable (v2.0+)
- [ ] 3rd party usage possible (open source?)
- [ ] Community contributions
- [ ] Grove ecosystem

---

## Conclusion

**Objectif**: Ne pas réinventer la roue deux fois.

**Stratégie**:
1. Développer pour MC d'abord (focus prototype)
2. Identifier patterns réutilisables
3. Extraire core library progressivement
4. WF bénéficie du travail MC

**Bénéfices**:
- ✅ Moins de code à maintenir
- ✅ Bugs fixés une seule fois
- ✅ Features profitent aux deux projets
- ✅ Validation GroveEngine en production

---

*Plan créé le 1er décembre 2025*
*Prochaine review: Fin MC Prototype (Mois 3)*