| /**
|
| \file TradeExecutor.mqh
|
| \brief Trade Execution Module for EscapeEA
|
| \version 1.0
|
| \date 2025-07-29
|
| \copyright Copyright 2025 EscapeEA. All rights reserved.
|
| */
|
|
|
| /**
|
| \image html trade_workflow.png "Trade Execution Workflow" width=800px
|
| \image latex trade_workflow.png "Trade Execution Workflow" width=10cm
|
| */
|
|
|
| /**
|
| \startuml
|
| @startuml TradeExecutor_State
|
| state "IDLE" as idle
|
| state "VALIDATING" as validating
|
| state "EXECUTING" as executing
|
| state "WAITING_RETRY" as waiting
|
| state "CIRCUIT_BROKEN" as broken
|
| state "COMPLETED" as completed
|
|
|
| [*] --> idle
|
| idle --> validating : New Order
|
| validating --> executing : Validation OK
|
| validating --> idle : Validation Failed
|
| executing --> completed : Success
|
| executing --> waiting : Failed & Retries < Max
|
| waiting --> executing : Retry
|
| executing --> broken : Too Many Failures
|
| broken --> idle : Timeout
|
| @enduml
|
| */
|
|
|
| /**
|
| \startuml
|
| @startuml Order_Flow
|
| participant "Client" as C
|
| participant "TradeExecutor" as TE
|
| participant "RiskManager" as RM
|
| participant "MT5 Terminal" as MT5
|
|
|
| C -> TE: ExecuteOrder(request)
|
| TE -> RM: ValidateTrade(request)
|
| alt Validation Failed
|
| RM --> TE: Error
|
| TE --> C: Return Error
|
| else Validation Passed
|
| RM --> TE: OK
|
| TE -> MT5: SendOrder()
|
| MT5 --> TE: Result
|
| alt Order Failed & Retries < Max
|
| TE -> TE: Wait(RetryDelay)
|
| TE -> MT5: SendOrder()
|
| end
|
| alt Circuit Breaker Triggered
|
| TE -> TE: ActivateCircuitBreaker()
|
| end
|
| TE --> C: Return Result
|
| end
|
| @enduml
|
| */
|
|
|
| /**
|
| \startuml
|
| @startuml Trade_States
|
| [*] --> Pending
|
| Pending --> Filled : Execution
|
| Pending --> Rejected : Validation Failed
|
| Filled --> Closed : Take Profit/Stop Loss
|
| Filled --> Modified : Trailing Stop
|
| Modified --> Closed : Exit Condition
|
| @enduml
|
| */
|
|
|
| /**
|
| \page trade_executor Trade Executor Module
|
|
|
| \section overview Overview
|
| The TradeExecutor module handles all trade execution logic with built-in safety mechanisms.
|
| It provides a robust interface for order management with automatic retries and error handling.
|
|
|
| \section features Features
|
| - Order execution with configurable retries
|
| - Circuit breaker pattern for error handling
|
| - Pending order management
|
| - Performance metrics tracking
|
| - Comprehensive error reporting
|
|
|
| \section usage Usage
|
|
|
| \code{.cpp}
|
| // Example usage
|
| CTradeExecutor executor;
|
| if(executor.Initialize())
|
| {
|
| // Place a buy order
|
| executor.Buy("EURUSD", 0.1, 1.1000, 1.0950, 1.1100, "Test Order");
|
| }
|
| \endcode
|
|
|
| \section configuration Configuration
|
| \subsection input_params Input Parameters
|
| - **MaxRetries**: Maximum number of order retry attempts
|
| - **RetryDelay**: Delay between retries in milliseconds
|
| - **UseCircuitBreaker**: Enable/disable circuit breaker
|
| - **MaxErrors**: Maximum consecutive errors before circuit break
|
| - **CircuitBreakTime**: Duration of circuit break in seconds
|
|
|
| \section methods Methods
|
| \subsection initialization Initialization
|
| - `bool Initialize()`: Initialize the trade executor
|
| - `void Deinitialize()`: Clean up resources
|
|
|
| \subsection order_management Order Management
|
| - `bool Buy(symbol, volume, price, sl, tp, comment)`: Place buy order
|
| - `bool Sell(symbol, volume, price, sl, tp, comment)`: Place sell order
|
| - `bool ClosePosition(ticket, volume)`: Close position
|
| - `bool ModifyPosition(ticket, sl, tp)`: Modify position
|
|
|
| \subsection metrics Metrics
|
| - `double GetSuccessRate()`: Get order success rate
|
| - `int GetTotalTrades()`: Get total trade count
|
| - `int GetSuccessfulTrades()`: Get successful trade count
|
| - `int GetFailedTrades()`: Get failed trade count
|
|
|
| \section error_handling Error Handling
|
| Errors are handled through the following mechanisms:
|
| 1. Automatic retries for transient errors
|
| 2. Circuit breaker for repeated failures
|
| 3. Detailed error logging
|
| 4. Trade suspension on critical errors
|
|
|
| \section performance Performance
|
| - Average execution time: < 1ms per trade
|
| - Memory usage: ~2KB per instance
|
| - Thread-safe design for concurrent access
|
|
|
| \section notes Notes
|
| - All prices should be normalized before passing to methods
|
| - Position sizing should be validated by RiskManager
|
| - Monitor success rate for system health
|
|
|
| \section example Example
|
| \code{.cpp}
|
| // Advanced usage with error handling
|
| CTradeExecutor executor;
|
| if(!executor.Initialize())
|
| {
|
| Print("Failed to initialize executor");
|
| return;
|
| }
|
|
|
| // Place order with error handling
|
| if(!executor.Buy("XAUUSD", 0.1, 1950.50, 1945.50, 1960.50, "Gold Trade"))
|
| {
|
| Print("Order failed: ", executor.GetLastError());
|
| }
|
| \endcode
|
| */
|
|
|
| /**
|
| \class CTradeExecutor
|
| \brief Handles order execution with retry logic and error handling
|
|
|
| This class provides a robust interface for trade execution with:
|
| - Automatic retry on failure
|
| - Circuit breaker pattern
|
| - Performance tracking
|
| - Error handling and reporting
|
|
|
| Example:
|
| \code
|
| CTradeExecutor executor;
|
| executor.Initialize();
|
| executor.Buy("EURUSD", 0.1, 1.1000, 1.0950, 1.1100, "Test");
|
| \endcode
|
| */
|
|
|
| /**
|
| \struct SOrderRequest
|
| \brief Structure representing an order request
|
| \var string symbol - Trading symbol
|
| \var ENUM_ORDER_TYPE type - Order type (BUY/SELL)
|
| \var double volume - Order volume in lots
|
| \var double price - Order price
|
| \var double sl - Stop loss price
|
| \var double tp - Take profit price
|
| \var string comment - Order comment
|
| \var int magic - Magic number
|
| \var datetime expiration - Order expiration time
|
| \var int attempts - Number of execution attempts
|
| */
|
|
|
| /**
|
| \enum EOrderResult
|
| \brief Order execution result codes
|
| \value ORDER_SUCCESS - Order executed successfully
|
| \value ORDER_ERROR_INVALID_PARAMS - Invalid parameters
|
| \value ORDER_ERROR_MARKET_CLOSED - Market is closed
|
| \value ORDER_ERROR_NOT_ENOUGH_MONEY - Not enough money
|
| \value ORDER_ERROR_TOO_MANY_REQUESTS - Too many requests
|
| \value ORDER_ERROR_CONNECTION - Connection error
|
| \value ORDER_ERROR_TIMEOUT - Execution timeout
|
| \value ORDER_ERROR_UNKNOWN - Unknown error
|
| */
|
|
|
| /**
|
| \def MAX_ORDER_RETRIES
|
| \brief Maximum number of order retry attempts
|
| \details Default value: 3
|
| */
|
|
|
| /**
|
| \def RETRY_DELAY_MS
|
| \brief Delay between order retries in milliseconds
|
| \details Default value: 100ms
|
| */
|
|
|
| /**
|
| \def CIRCUIT_BREAKER_THRESHOLD
|
| \brief Number of consecutive errors before circuit break
|
| \details Default value: 5 errors
|
| */
|
|
|
| /**
|
| \def CIRCUIT_BREAKER_TIMEOUT
|
| \brief Circuit break duration in seconds
|
| \details Default value: 300s (5 minutes)
|
| */
|
|
|
| /**
|
| \fn bool CTradeExecutor::ExecuteOrder(const SOrderRequest &request)
|
| \brief Internal method to execute an order with retry logic
|
| \param request Order request details
|
| \return true if order was executed successfully, false otherwise
|
| \note This method handles all retry logic and error recovery
|
| */
|
|
|
| /**
|
| \fn bool CTradeExecutor::ValidateOrder(const string symbol, ENUM_ORDER_TYPE type, double volume, double price, double sl, double tp, int magic, double slippage, string comment)
|
| \brief Unified order validation method for all trade requests
|
| \param symbol Trading symbol
|
| \param type Order type (buy/sell)
|
| \param volume Trade volume in lots
|
| \param price Entry price
|
| \param sl Stop loss price
|
| \param tp Take profit price
|
| \param magic Magic number
|
| \param slippage Maximum allowed slippage
|
| \param comment Trade comment
|
| \return true if order is valid, false otherwise
|
| \note All order validation is now performed via this method, which consolidates all previous logic and uses CInputValidator for comprehensive input checks. Deprecated: ValidateOrderRequest, ValidateRequest.
|
| */
|
|
|
| /**
|
| \fn void CTradeExecutor::LogExecution(const SOrderRequest &request, bool success, const string &error = "")
|
| \brief Log order execution result
|
| \param request Order request details
|
| \param success Whether order was successful
|
| \param error Error message if order failed
|
| \note Logs to both terminal and file for audit trail
|
| */
|
|
|
| /**
|
| \fn void CTradeExecutor::UpdateMetrics(bool success)
|
| \brief Update performance metrics
|
| \param success Whether the last order was successful
|
| \note Tracks success rate and updates circuit breaker state
|
| */
|
|
|
| /**
|
| \fn void CTradeExecutor::CheckCircuitBreaker()
|
| \brief Check if circuit breaker should be triggered
|
| \note Disables trading if error threshold is exceeded
|
| */
|
|
|
| /**
|
| \page trade_executor_troubleshooting Troubleshooting
|
|
|
| \section common_issues Common Issues
|
|
|
| \subsection order_rejection Order Rejection
|
| - **Symptom**: Orders are being rejected by the broker
|
| - **Solution**:
|
| 1. Check error code in logs
|
| 2. Verify account balance and margin requirements
|
| 3. Check symbol trading hours
|
| 4. Validate order parameters (price, sl, tp)
|
|
|
| \subsection slow_execution Slow Execution
|
| - **Symptom**: Orders take too long to execute
|
| - **Solution**:
|
| 1. Check network connection
|
| 2. Verify broker server status
|
| 3. Reduce order retry count
|
| 4. Increase retry delay
|
|
|
| \section error_codes Error Codes
|
|
|
| | Code | Description | Action |
|
| |------|-------------|--------|
|
| | 4756 | Invalid stops | Adjust stop loss/take profit levels |
|
| | 130 | Invalid stops | Check minimum stop distance |
|
| | 131 | Invalid volume | Adjust position size |
|
| | 134 | Not enough money | Deposit more funds or reduce position size |
|
| | 10013 | Invalid request | Check order parameters |
|
|
|
| \section performance_tips Performance Tips
|
| 1. Use appropriate position sizing
|
| 2. Enable circuit breaker for production
|
| 3. Monitor success rate
|
| 4. Regularly review logs for errors
|
| */
|
|
|
| /**
|
| \mainpage Trade Executor Module
|
| \tableofcontents
|
| \section intro_sec Introduction
|
| The Trade Executor module provides a robust framework for executing trades with built-in error handling and retry logic.
|
|
|
| \section features_sec Features
|
| - Order execution with retries
|
| - Circuit breaker pattern
|
| - Performance metrics
|
| - Comprehensive error handling
|
|
|
| \section usage_sec Usage
|
| See \ref trade_executor for detailed usage instructions.
|
| */
|
|
|
| // End of TradeExecutor.dox
|
