aissia/docs/03-implementation/configuration/transport-economic-system.md

Rapport : Système Transport & Économique

🚛 Architecture Transport System

Transport Mode Hierarchy

Selection Cascade basée sur optimisation économique pure :

Decision Tree (Cost Optimization) - Points 90-95:
1. Volume ≥ 1000t + Port Access → Ship (0.10€/kg)
2. Else + Rail Access → Train (0.50€/kg)
3. Else + Airport Access → Air (2.00€/kg)
4. Else → Truck (5.00€/kg)

Storage Cost: €0.02/kg/day
Delivery Times: Ship 14j, Train 3j, Air 1j, Truck 2j
Ship Volume Threshold: ≥1000 tonnes minimum

Pas de facteur urgency - pure economic optimization

Justification Économique

• Coût maritime : 50x moins cher que camion (économies d'échelle massives)
• Seuil volume : 1000 tonnes nécessaire pour rentabiliser navire
• Infrastructure binaire : Access ou pas access, pas de gradients
• Simplification décisionnelle : Arbre de décision clair pour IA

Infrastructure Access Binary

Propriétés géographiques des entreprises :

struct CompanyLocation {
    bool hasPortAccess = false;      // Access maritime
    bool hasRailAccess = false;      // Access ferroviaire
    bool hasAirportAccess = false;   // Access aérien
    bool alwaysTruckAccess = true;   // Camion toujours disponible

    float transportMultiplier() {
        // Geographic competitive advantage
        return hasPortAccess ? 0.10f :
               hasRailAccess ? 0.50f :
               hasAirportAccess ? 2.00f : 5.00f;
    }
};

Avantage Concurrentiel Géographique

• Coastal locations : Avantage économique structurel
• Inland accessible par rail : Compromis coût/accessibilité
• Remote locations : Coût transport élevé = premium prices
• Strategic positioning : Infrastructure access = competitive moat

📊 Market Mechanics

Order System (Passes Économiques)

Phases économiques séquentielles :

Economic Cycle (24h):
1. Offer Phase (6h): Producers submit sell orders
2. Demand Phase (6h): Consumers submit buy orders
3. Market Clearing (1h): Price discovery & matching
4. Transport Assignment (1h): Mode selection per transaction
5. Execution Phase (10h): Delivery + payment processing

Order Stacking Strategy:
├─ Multiple sellers combine orders during Offer Phase
├─ Volume aggregation unlock ship transport thresholds
├─ Waiting mechanism incentivizes collaboration
├─ Economic pressure creates natural cooperation

Benefits Système Passes

• Price discovery efficient : Concentration temporelle des échanges
• Volume optimization : Incitation à collaboration pour seuils
• Market transparency : Informations disponibles pour tous
• Strategic timing : Players peuvent anticiper cycles

Dynamic Pricing Mechanism

Formation des prix multi-facteurs :

class PriceFormation {
    float calculatePrice(Good good, Region region) {
        float basePrice = supplyDemandEquilibrium(good);
        float transportPremium = calculateTransportCosts(region);
        float scarcityMultiplier = getScarcityPressure(good, region);
        float regionGradient = getRegionalPriceGradient(good, region);

        return basePrice * (1 + transportPremium + scarcityMultiplier + regionGradient);
    }
};

Price Formation Components

Base Price (Supply/Demand Equilibrium)

• Market clearing price : Intersection offre/demande
• Global reference : Prix de base mondial
• Volatility buffer : Mécanismes anti-manipulation

Transport Cost Limits (Buyer-Defined)

• Maximum transport % : Buyers set acceptable transport cost ratio
• Example : "Transport max 15% of goods value"
• Market filtering : Orders rejected if transport too expensive
• Geographic arbitrage limits : Natural price convergence mechanism

Scarcity Premium (Desperation Bidding)

• Stock depletion : Companies with low inventory bid premium
• Regional shortages : Isolated regions pay survival premiums
• Urgent orders : Rush delivery commands price multipliers
• Market psychology : Fear of shortage drives irrational bidding

Regional Price Gradients (Geographic Arbitrage)

Price Examples (Iron):
├─ Coastal Region: 10€/kg (baseline + ship transport)
├─ Rail Accessible: 11€/kg (baseline + rail premium)
├─ Airport Only: 20€/kg (baseline + air premium)
├─ Remote Truck: 50€/kg (baseline + truck premium + scarcity)

🏗️ Storage & Inventory System

Company Storage Strategy

Adaptive Inventory Management basée sur niveaux de stock :

enum InventoryStrategy {
    DESPERATE,   // Stock < 20% → Premium bidding
    NORMAL,      // Stock 20-50% → Market price buying
    CAUTIOUS,    // Stock 50-80% → Opportunistic buying only
    OVERSUPPLIED // Stock > 80% → Stop purchasing
};

class InventoryManager {
    PurchaseDecision evaluate(float stockLevel, float marketPrice) {
        if(stockLevel < 0.20f) return {true, marketPrice * 1.5f}; // Desperate
        if(stockLevel < 0.50f) return {true, marketPrice};         // Normal
        if(stockLevel < 0.80f) return {false, marketPrice * 0.8f}; // Opportunistic
        return {false, 0.0f}; // Stop buying
    }
};

Inventory Trade-offs

• Large inventory : Security vs storage costs (€0.02/kg/day)
• Small inventory : Lower costs vs supply chain risk
• Timing optimization : Buy during market oversupply
• Geographic arbitrage : Coastal storage → Inland distribution

Bulk Purchase Cycles

Natural market pulse patterns :

Market Cycle Pattern:
1. Multiple companies hit 20% stock simultaneously
2. Competing desperate bids create price spikes
3. Large combined volumes enable ship transport unlock
4. Price normalization as inventory restored
5. Market oversupply as orders arrive simultaneously
6. Price correction downward
7. Cycle repeats with natural frequency

Emergent Behavior

• Synchronized depletion : Similar consumption patterns
• Bidding wars : Scarcity-driven competition
• Transport optimization : Volume consolidation benefits
• Natural cycles : Self-organizing market rhythms

💼 Trading Companies

Business Models Emergents

Pure Arbitrage Strategy

class ArbitrageTrader {
    Strategy coastalToInland() {
        // 1. Buy coastal (cheap ship transport access)
        // 2. Store in strategic inland locations
        // 3. Sell to remote regions (premium prices)
        // Profit = Price differential - storage - transport
        return {buyCoastal, storeStrategic, sellRemote};
    }
};

Transport Optimization Strategy

class TransportOptimizer {
    Strategy aggregateSmallProducers() {
        // 1. Aggregate small producer outputs
        // 2. Combine orders to unlock ship thresholds
        // 3. Share transport savings with producers
        // Profit = Transport efficiency gains
        return {aggregateOrders, unlockShipping, shareGains};
    }
};

Market Making Strategy

class MarketMaker {
    Strategy stabilizeSupply() {
        // 1. Buffer supply volatility with inventory
        // 2. Provide reliable supply to consumers
        // 3. Smooth price fluctuations
        // Profit = Stability service premium
        return {bufferVolatility, guaranteeSupply, chargePremium};
    }
};

Specialization Types

Geographic Specialists

• Regional expertise : Deep knowledge specific areas
• Infrastructure relationships : Port/rail access deals
• Local market intelligence : Cultural/regulatory knowledge
• Logistics optimization : Region-specific transport solutions

Commodity Specialists

• Deep vertical knowledge : Single commodity expertise
• Quality assessment : Grading, certification, standards
• Technical logistics : Specialized handling, storage
• Market prediction : Supply/demand pattern expertise

Logistics Specialists

• Transport optimization : Multi-modal route planning
• Volume consolidation : Order aggregation expertise
• Infrastructure leverage : Maximum transport efficiency
• Timing coordination : Economic cycle optimization

Financial Specialists

• Risk management : Hedging, insurance, derivatives
• Futures markets : Long-term contract management
• Credit facilities : Financing for trade operations
• Currency hedging : International trade protection

🌍 Geographic Economics

Natural Economic Geography Evolution

Coastal Concentration Dynamics

Market Forces Sequence:
1. Initial coastal rush (transport cost advantages)
2. Land price premiums develop (scarcity)
3. Congestion costs emerge (infrastructure limits)
4. Port capacity bottlenecks (throughput limits)
5. Labor shortage premiums (competition)
6. Economic equilibrium reached (cost parity)

Regional Specialization Patterns

enum RegionType {
    RESOURCE_EXTRACTION,  // Fixed by geological deposits
    MANUFACTURING_HUB,    // Transport cost optimization
    TRADING_CENTER,       // Infrastructure convergence
    CONSUMER_MARKET      // Population concentration
};

class RegionalSpecialization {
    RegionType determineOptimalFocus(Region region) {
        if(hasNaturalResources(region)) return RESOURCE_EXTRACTION;
        if(hasTransportHub(region)) return TRADING_CENTER;
        if(hasManufacturingCosts(region)) return MANUFACTURING_HUB;
        return CONSUMER_MARKET;
    }
};

Infrastructure Investment Economics

Economic Justification Model

class InfrastructureROI {
    bool justifyRailInvestment(Region region) {
        float currentTransportCosts = calculateTruckCosts(region);
        float projectedVolume = estimateTradeVolume(region);
        float railConstructionCost = calculateRailCost(region);
        float railOperatingCost = calculateRailOperations(region);

        float savings = (currentTransportCosts - railOperatingCost) * projectedVolume;
        float paybackPeriod = railConstructionCost / savings;

        return paybackPeriod < MAX_PAYBACK_YEARS;
    }
};

Investment Triggers

• Sustained high transport costs : Market signals infrastructure need
• Volume thresholds reached : Economies of scale justify investment
• Regional economic pressure : Political/social demand for development
• Competitive necessity : Rival regions gaining advantages

Infrastructure Impact Simulation

Pre-Rail Region:
├─ Truck transport only (5.00€/kg)
├─ High consumer prices
├─ Limited economic activity
├─ Population outmigration

Post-Rail Region:
├─ Rail transport available (0.50€/kg)
├─ 90% transport cost reduction
├─ Economic boom, new businesses
├─ Population influx, urbanization

⚙️ Implementation Details

Economic Agents (Player-Agnostic Design)

Tous les entités = agents économiques :

class EconomicAgent {
public:
    virtual void submitOrders() = 0;
    virtual void processTransactions() = 0;
    virtual void updateStrategy() = 0;

    // No special player privileges
    // Pure economic simulation
};

class ProductionCompany : public EconomicAgent { ... };
class ConsumptionCompany : public EconomicAgent { ... };
class TransportCompany : public EconomicAgent { ... };
class TradingCompany : public EconomicAgent { ... };
class InfrastructureInvestor : public EconomicAgent { ... };

Agent Equality Principle

• No player privileges : Tous agents soumis aux mêmes règles
• Pure simulation : Économie émergente sans intervention arbitraire
• Fair competition : Success basé sur strategy, pas status
• Realistic behavior : AI agents comportement économique rationnel

Market Clearing Algorithm

Order Matching Process :

class MarketClearingEngine {
    void processMarketCycle() {
        // 1. Collect all orders from economic phases
        auto sellOrders = collectSellOrders();
        auto buyOrders = collectBuyOrders();

        // 2. Sort for optimal matching
        std::sort(sellOrders.begin(), sellOrders.end(), priceAscending);
        std::sort(buyOrders.begin(), buyOrders.end(), priceDescending);

        // 3. Match orders within transport cost limits
        auto matches = matchOrdersWithTransportLimits(sellOrders, buyOrders);

        // 4. Apply volume consolidation for shipping
        auto consolidatedMatches = applyVolumeConsolidation(matches);

        // 5. Calculate optimal transport modes
        for(auto& match : consolidatedMatches) {
            match.transportMode = selectOptimalTransport(match);
        }

        // 6. Execute deliveries with realistic time delays
        scheduleDeliveries(consolidatedMatches);
    }
};

Algorithm Benefits

• Economic efficiency : Optimal price discovery
• Transport optimization : Automatic mode selection
• Volume benefits : Consolidation incentives
• Realistic timing : Delivery delays based on transport mode

Configuration Parameters

Système de configuration économique :

{
    "transport": {
        "ship_threshold_tonnes": 1000,
        "ship_cost_per_kg": 0.10,
        "train_cost_per_kg": 0.50,
        "air_cost_per_kg": 2.00,
        "truck_cost_per_kg": 5.00,
        "delivery_time_ship_days": 14,
        "delivery_time_train_days": 3,
        "delivery_time_air_days": 1,
        "delivery_time_truck_days": 2
    },
    "storage": {
        "cost_per_kg_per_day": 0.02,
        "urgent_stock_threshold": 0.20,
        "normal_stock_threshold": 0.50,
        "oversupplied_threshold": 0.80,
        "max_storage_capacity_multiplier": 10.0
    },
    "market": {
        "transport_cost_limit_percentage": 0.15,
        "order_stacking_wait_days": 7,
        "economic_phase_duration_hours": 6,
        "price_volatility_damping": 0.1,
        "scarcity_premium_multiplier": 2.0
    },
    "infrastructure": {
        "rail_construction_cost_per_km": 1000000,
        "port_construction_cost": 50000000,
        "airport_construction_cost": 100000000,
        "max_infrastructure_payback_years": 15
    }
}

Configuration Benefits

• Tunable economics : Adjust economic parameters for gameplay
• Progressive complexity : Start simple, add sophistication
• A/B testing : Compare different economic models
• Regional variation : Different parameters per geographic region

🎯 System Benefits & Integration

Economic Realism Achievements

Natural Geographic Specialization

• Resource-based clustering : Mining near deposits
• Manufacturing optimization : Transport cost minimization
• Trading hub emergence : Infrastructure convergence points
• Realistic urban development : Economic forces drive settlement patterns

Infrastructure ROI Modeling

• Investment justification : Economic case for infrastructure
• Regional transformation : Infrastructure changes economic landscape
• Competitive dynamics : Regions compete for transport access
• Long-term planning : Infrastructure decisions have lasting impact

Market Cycle Emergence

• Natural rhythms : Supply/demand cycles self-organize
• Price discovery : Efficient market mechanisms
• Arbitrage opportunities : Geographic and temporal price differences
• Risk/reward balance : Higher profits require higher risks

Emergent Complexity Demonstration

Trading Company Evolution

• Business model innovation : New strategies emerge from economic pressure
• Specialization development : Companies find profitable niches
• Market efficiency improvement : Traders reduce transaction costs
• Economic ecosystem richness : Multiple business models coexist

Regional Economic Development

• Coastal advantage phase : Early transport cost benefits
• Infrastructure investment phase : Economic pressure drives development
• Economic equilibrium phase : Costs equalize across regions
• Competitive specialization phase : Regions find comparative advantages

Supply Chain Sophistication

• Simple direct trade → Multi-hop arbitrage → Complex logistics networks
• Individual transactions → Volume consolidation → Integrated supply chains
• Local markets → Regional trade → Global economic integration

Simple Implementation Strategy

Clear Decision Trees

TransportMode selectTransport(Order order, Route route) {
    if(order.volume >= 1000 && route.hasPortAccess()) return SHIP;
    if(route.hasRailAccess()) return TRAIN;
    if(route.hasAirportAccess()) return AIR;
    return TRUCK;
}

Binary Infrastructure Access

• No gradients : Access or no access, simple boolean
• Clear competitive advantage : Infrastructure = economic moat
• Easy AI reasoning : Simple rules for AI decision-making
• Scalable complexity : Add infrastructure types without algorithm changes

Modular Economic Components

// Easy integration with existing architecture
class TransportModule : public IModule { ... };
class TradingModule : public IModule { ... };
class InfrastructureModule : public IModule { ... };
class MarketModule : public IModule { ... };

Scalability Architecture

Progressive Sophistication

• Phase 1 : Basic transport cost differences
• Phase 2 : Order stacking and volume optimization
• Phase 3 : Trading companies and arbitrage
• Phase 4 : Infrastructure investment and regional development
• Phase 5 : Complex economic simulation (Victoria 3-level)

Performance Scaling

• Local decisions : Transport mode selection (real-time)
• Regional coordination : Market clearing (hourly)
• Economic simulation : Complex modeling (daily)
• Infrastructure planning : Long-term investment (monthly)

Player-Agnostic Benefits

Pure Economic Simulation

• No artificial advantages : Players compete on equal terms
• Emergent strategies : Success comes from economic insight
• Educational value : Players learn real economic principles
• Sandbox flexibility : Multiple valid approaches to success

AI Agent Integration

• Consistent behavior : All agents follow same economic rules
• Realistic competition : AI competitors use rational strategies
• Market depth : Many agents create liquid markets
• Economic ecosystem : Rich environment for player interaction

---

Conclusion

Le système transport & économique crée une simulation économique réaliste où :

• Geographic advantages émergent naturellement des coûts de transport
• Business models sophistiqués évoluent des pressions économiques
• Infrastructure investment suit la logique économique ROI
• Market dynamics créent cycles et opportunités réalistes

Ready for integration dans l'architecture modulaire :

• ProductionModule : Interface avec transport costs
• TradingModule : Business logic des trading companies
• InfrastructureModule : Investment et construction logic
• MarketModule : Economic phases et price discovery

Résultat : Economic simulation depth comparable aux meilleurs strategy games, avec implementation simplicity compatible Claude Code development ! 🚛💰🏗️