/**
\file EscapeEA.mq5
\brief EscapeEA - Advanced Trading Expert Advisor
\version 2.0
\date 2025-07-29
\copyright Copyright 2025 EscapeEA. All rights reserved.
*/

/**
\image html ea_architecture.png "EscapeEA Architecture" width=900px
\image latex ea_architecture.png "EscapeEA Architecture" width=12cm
*/

/**
\startuml
@startuml EscapeEA_Workflow
start
:Initialize EA;
:Load Indicators;
:Initialize TradeExecutor;
:Initialize RiskManager;

repeat
    :OnTick Event;
    if (Paper Trading Mode?) then (yes)
        :Process Paper Trade;
        if (3/5 Wins Achieved?) then (yes)
            :Switch to Live Mode;
        else (no)
            :Continue Paper Trading;
        endif
    else (no)
        :Check Trading Hours;
        :Check Market Conditions;
        :Generate Trading Signals;
        :Validate with RiskManager;
        if (Signal Valid?) then (yes)
            :Execute Trade via TradeExecutor;
            :Update Performance Metrics;
        else (no)
            :Skip Trade;
        endif
    endif
    :Update Chart Display;
repeat while (EA Running?) is (yes)
stop
@enduml
*/

/**
\startuml
@startuml Paper_Trading_Flow
state "Paper Trading Mode" as paper
state "Live Trading Mode" as live
state "Evaluation" as eval
state "Success" as success
state "Failure" as fail

[*] --> paper
paper --> eval : Trade Completed
eval --> paper : More Trades Needed
eval --> success : 3/5 Wins
success --> live
paper --> fail : Max Trades Reached
fail --> [*]
@enduml
*/

/**
\startuml
@startuml Trading_Signals
skinparam monochrome true

state "Signal Generation" as signals {
    [*] --> CheckMA
    CheckMA --> CheckPrice : MA Crossover
    CheckPrice --> GenerateSignal : Price Confirmation
    GenerateSignal --> [*]
}

state "Trade Execution" as execution {
    [*] --> ValidateRisk
    ValidateRisk --> ExecuteTrade
    ExecuteTrade --> MonitorPosition
    MonitorPosition --> ClosePosition
    ClosePosition --> [*]
}

signals --> execution : Valid Signal
@enduml
*/

/**
\startuml
@startuml EA_State_Machine
state "Initialization" as init
state "Paper Trading" as paper
state "Live Trading" as live
state "Error" as error
state "Shutdown" as shutdown

[*] --> init
init --> paper : Success
init --> error : Failure
paper --> live : 3/5 Wins
paper --> error : Max Failures
live --> error : Critical Error
error --> shutdown : Auto-Recover
error --> [*] : Manual Reset
@enduml
*/

/**
\page escape_ea EscapeEA Main Module

\section overview Overview
EscapeEA is a sophisticated trading system designed for OTC markets with built-in risk management and paper trading capabilities.

\section features Features
- Dual-mode operation (Paper/Live trading)
- Moving Average crossover strategy
- Comprehensive risk management
- Paper trading validation system
- Visual feedback and monitoring

\section strategy Trading Strategy
\subsection entry_signals Entry Signals
1. **Buy Signal**:
   - Fast MA crosses above Slow MA
   - Price is above main MA
   - All risk parameters are satisfied

2. **Sell Signal**:
   - Fast MA crosses below Slow MA
   - Price is below main MA
   - All risk parameters are satisfied

\subsection exit_signals Exit Signals
1. **Take Profit**: Fixed pips from entry
2. **Stop Loss**: Fixed pips from entry
3. **Trailing Stop**: Optional trailing stop
4. **Time-based**: Friday close (optional)

\section paper_trading Paper Trading System
\subsection requirements Requirements
- Must complete 5 paper trades
- Must win at least 3 trades
- Each paper trade is validated before live execution

\subsection simulation Simulation Features
- Realistic spread simulation
- Slippage modeling
- Commission calculation
- Real-time performance tracking

\section usage Usage
\subsection installation Installation
1. Copy `EscapeEA.mq5` to `MQL5/Experts/`
2. Copy `TradeExecutor.mqh` and `RiskManager.mqh` to `MQL5/Include/Escape/`
3. Compile the EA in MetaEditor
4. Attach to a chart with sufficient historical data

\subsection configuration Configuration
```mql5
//--- Strategy Parameters
input int      InpMAPeriod = 14;          // MA Period
input int      InpMAFastPeriod = 10;      // Fast MA Period
input int      InpMASlowPeriod = 21;      // Slow MA Period

//--- Risk Parameters
input double   InpLotSize = 0.1;          // Lot Size
input int      InpStopLoss = 100;         // Stop Loss (points)
input int      InpTakeProfit = 200;       // Take Profit (points)

//--- Trailing Stop
input bool     InpUseTrailingStop = true;  // Use Trailing Stop
input int      InpTrailingStop = 50;       // Trailing Stop (points)
input int      InpTrailingStep = 10;       // Trailing Step (points)

//--- Time Filters
input bool     InpUseTimeFilter = false;   // Use Time Filter
input int      InpStartHour = 8;           // Trading Start Hour
input int      InpEndHour = 20;            // Trading End Hour
input bool     InpFridayClose = true;      // Close on Friday
input int      InpFridayCloseHour = 16;    // Friday Close Hour
```

\section components Components
\subsection trade_executor Trade Executor
- Handles all order execution
- Implements retry logic
- Manages order lifecycle

\subsection risk_manager Risk Manager
- Validates all trades
- Calculates position sizes
- Enforces risk parameters

\section example Example
```mql5
// Example of manual trade execution
double ask = SymbolInfoDouble(_Symbol, SYMBOL_ASK);
double sl = ask - InpStopLoss * _Point;
double tp = ask + InpTakeProfit * _Point;

trade.Buy(InpLotSize, _Symbol, ask, sl, tp, "EscapeEA Buy");
```
*/

/**
\class CEscapeEA
\brief Main Expert Advisor class

This class implements the core trading logic and coordinates between components.

Example:
\code
// In OnInit()
if(!ExtTradeExecutor.Initialize())
{
    Print("Failed to initialize trade executor");
    return INIT_FAILED;
}
\endcode
*/

/**
\struct SPaperTrade
\brief Structure for paper trading simulation
\var double entryPrice - Entry price
\var double stopLoss - Stop loss level
\var double takeProfit - Take profit level
\var ENUM_ORDER_TYPE type - Trade type (BUY/SELL)
\var datetime openTime - Entry time
\var bool isClosed - Whether trade is closed
\var double closePrice - Close price
\var datetime closeTime - Close time
\var double profit - Profit/Loss
*/

/**
\enum ESignalType
\brief Trading signal types
\value SIGNAL_BUY - Buy signal
\value SIGNAL_SELL - Sell signal
\value SIGNAL_NONE - No signal
*/

/**
\def PAPER_TRADES_REQUIRED
\brief Number of paper trades required before live trading
\details Default: 5 trades
*/

/**
\def PAPER_WINS_REQUIRED
\brief Number of winning paper trades required
\details Default: 3 wins
*/

/**
\fn int OnInit()
\brief EA initialization function
\return INIT_SUCCEEDED or INIT_FAILED
\note Initializes indicators, trade executor, and risk manager
*/

/**
\fn void OnDeinit(const int reason)
\brief EA deinitialization function
\param reason Deinitialization reason code
\note Cleans up resources and saves state
*/

/**
\fn void OnTick()
\brief Main tick processing function
\note Called on every tick/bar
*/

/**
\fn void ProcessTrades()
\brief Process trading signals and execute trades
\note Handles both paper and live trading
*/

/**
\fn void ProcessPaperTrading()
\brief Process paper trading simulation
\note Simulates trades without real money
*/

/**
\fn void UpdateChart()
\brief Update chart with trading information
\note Displays status, positions, and performance
*/

/**
\page ea_troubleshooting Troubleshooting

\section common_issues Common Issues

\subsection ea_not_trading EA Not Trading
- **Symptom**: EA is attached but not placing trades
- **Solution**:
  1. Check Experts tab for errors
  2. Verify account is connected
  3. Check symbol is enabled for trading
  4. Verify risk parameters

\subsection incorrect_signals Incorrect Signals
- **Symptom**: Trades in wrong direction
- **Solution**:
  1. Check indicator settings
  2. Verify timeframes match
  3. Check for repainting indicators

\section optimization Optimization

\subsection parameters Parameters to Optimize
1. Moving Average periods
2. Stop Loss/Take Profit levels
3. Position sizing
4. Time filters

\subsection backtesting Backtesting Tips
1. Use 90% quality model
2. Test multiple market conditions
3. Include spread and commission
4. Verify with forward testing

\section risk_warning Risk Warning
Trading involves substantial risk of loss. This software is for educational purposes only.
Past performance is not indicative of future results.
*/

/**
\mainpage EscapeEA Documentation
\tableofcontents
\section intro_sec Introduction
EscapeEA is a professional trading system with built-in risk management.

\section features_sec Features
- Advanced trading strategy
- Comprehensive risk management
- Paper trading system
- Real-time monitoring

\section usage_sec Usage
See \ref escape_ea for detailed usage instructions.

\section support_sec Support
For support contact: support@escapeea.com
*/

// End of EscapeEA.dox