مستندات فنی

نگاهی عمیق به معماری کد، کلاس‌های اصلی و منطق داخلی گریفین گارد.

فلسفه طراحی

گریفین گارد با دو اصل کلیدی طراحی شده است: **ماژولار بودن** و **برنامه‌نویسی شیءگرا (OOP)**. هدف اصلی، ایجاد کدی تمیز، قابل نگهداری و قابل توسعه بوده است. هر بخش از منطق برنامه در فایل هدر (`.mqh`) مخصوص به خود قرار دارد تا از وابستگی‌های پیچیده جلوگیری شود.

معماری فایل‌ها

پروژه از چندین فایل هدر تشکیل شده که هر کدام مسئولیت مشخصی دارند:

  • griffin-guard.mq5: فایل اصلی و نقطه شروع اکسپرت. مسئولیت مقداردهی اولیه، مدیریت رویدادهای اصلی (`OnInit`, `OnTick`) و اتصال ماژول‌ها به یکدیگر را بر عهده دارد.
  • Defines.mqh: محل تعریف تمام ورودی‌های (`input`) اکسپرت، `enum` ها، `define` ها و متغیرهای سراسری.
  • PanelDialog.mqh: یک کلاس قدرتمند که از کتابخانه استاندارد `CAppDialog` ارث‌بری کرده و تمام جنبه‌های پنل اصلی (ایجاد کنترل‌ها، مدیریت رویدادها و وضعیت UI) را مدیریت می‌کند.
  • DisplayCanvas.mqh: کلاسی که مسئولیت تمام عملیات ترسیم روی پنل نمایش اطلاعات را با استفاده از کتابخانه `CCanvas` بر عهده دارد.
  • SharedLogic.mqh: شامل توابع مشترکی است که در بخش‌های مختلف برنامه استفاده می‌شوند، مانند `CalculateLotSize` و `IsTradeRequestSafe`.
  • Lines.mqh: توابع مربوط به ایجاد، حذف و مدیریت لیبل‌های متصل به خطوط معاملاتی در این فایل قرار دارند.
  • MarketExecution.mqh, PendingExecution.mqh, StairwayExecution.mqh: هر کدام از این فایل‌ها منطق خالص مربوط به یکی از سه استراتژی معاملاتی را در خود جای داده‌اند.
  • StateManager.mqh: مسئولیت ذخیره و بازیابی وضعیت اکسپرت (مانند قیمت خطوط در حالت پلکانی) در یک فایل باینری (`.dat`) را بر عهده دارد.

کلاس CPanelDialog

این کلاس، مغز متفکر رابط کاربری است. این کلاس با ارث‌بری از `CAppDialog`، از یک ماشین وضعیت (State Machine) داخلی برای مدیریت حالت‌های مختلف برنامه (مانند `STATE_IDLE`, `STATE_PREP_MARKET_BUY`) استفاده می‌کند. تمام رویدادهای کلیک روی دکمه‌ها از طریق `EVENT_MAP` به توابع مربوطه متصل شده‌اند، که این امر کد را بسیار تمیز و خوانا می‌کند.


// نمونه‌ای از نقشه رویداد در PanelDialog.mqh
EVENT_MAP_BEGIN(CPanelDialog)
    ON_EVENT(ON_CLICK, m_btn_prep_market_buy, OnClickPrepMarketBuy)
    ON_EVENT(ON_CLICK, m_btn_execute_market, OnClickExecuteMarket)
    // ...
EVENT_MAP_END(CAppDialog)

کلاس CDisplayCanvas

این کلاس به طور کامل از منطق اصلی برنامه جدا شده است. وظیفه آن این است که داده‌های خام را از تابع `UpdateDisplayData` دریافت کرده و آن‌ها را به شکل گرافیکی و زیبا روی بوم نقاشی (`CCanvas`) ترسیم کند. این جداسازی باعث می‌شود که در آینده بتوان به راحتی ظاهر داشبورد را بدون تغییر در منطق اصلی برنامه، عوض کرد.

مدیریت وضعیت

یکی از چالش‌های اصلی، حفظ وضعیت اکسپرت پس از ری‌استارت متاتریدر بود. این مشکل با استفاده از `StateManager.mqh` حل شده است. در تابع `OnDeinit`، وضعیت فعلی و قیمت‌های مهم خطوط در یک فایل باینری (`.dat`) ذخیره می‌شوند. سپس در تابع `OnInit`، این مقادیر از فایل خوانده شده و تمام اشیاء گرافیکی و حالت‌های داخلی برنامه به وضعیت قبلی خود بازگردانده می‌شوند.

لایسنس و مشارکت

گریفین گارد تحت لایسنس **GNU General Public License v3.0** منتشر شده است. این به شما اجازه می‌دهد که کد را بررسی کنید، آن را برای نیازهای خود تغییر دهید و حتی نسخه‌های بهبودیافته خود را با دیگران به اشتراک بگذارید (به شرطی که آن‌ها نیز تحت همین لایسنس منتشر شوند).

ما از مشارکت شما در این پروژه استقبال می‌کنیم. اگر ایده‌ای برای بهبود دارید یا باگی پیدا کرده‌اید، لطفاً آن را در بخش Issues صفحه گیت‌هاب پروژه مطرح کنید.