مستندات جامع Griffin Guard

فلسفه و هدف اصلی

Griffin Guard صرفاً یک ابزار محاسبه ریسک نیست؛ بلکه یک دستیار معامله‌گری هوشمند و نگهبان حساب شماست. این اکسپرت با دو هدف اصلی طراحی شده است:

• کاهش خطای انسانی: خودکارسازی محاسبات پیچیده، اعتبارسنجی لحظه‌ای تصمیمات و جلوگیری از اشتباهات رایج.
• افزایش سرعت و تمرکز: فراهم کردن یک رابط کاربری سریع، روان و کارآمد تا معامله‌گر بتواند تمام تمرکز خود را به تحلیل بازار معطوف کند، به‌جای آنکه درگیر تنظیمات ابزار شود.

این پروژه به‌صورت کاملاً متن‌باز (Open Source) تحت مجوز GPLv3 توسعه داده شده تا شفافیت کامل را تضمین کرده و به جامعه معامله‌گران اجازه دهد در توسعه و بهبود آن مشارکت کنند.

پیش‌نیازها

• پلتفرم معاملاتی MetaTrader 5
• سیستم عامل ویندوز، مک یا لینوکس (با استفاده از Wine)

بخش ۱: رابط کاربری (UI) و اجزای اصلی

گریفین گارد از سه پنل گرافیکی مجزا برای ارائه اطلاعات و دریافت دستورات استفاده می‌کند.

۱.۱. پنل اصلی معاملات (PanelDialog)

این پنل، مرکز اصلی کنترل و مدیریت معاملات شماست و به سه بخش منطقی تقسیم شده است:

الف) بخش Market Execution

• منطق: برای ورود آنی به معامله با قیمت فعلی بازار.
• عملکرد:
  1. با کلیک روی دکمه Buy یا Sell، خطوط حد ضرر (قرمز) و حد سود (سبز) روی چارت ظاهر می‌شوند. خط ورود روی قیمت فعلی بازار قفل می‌شود.
  2. کاربر خطوط حد ضرر (SL) و حد سود (TP) را به محل مورد نظر خود منتقل (Drag) می‌کند.
  3. اکسپرت به‌صورت لحظه‌ای حجم لات را بر اساس ریسک وارد شده و فاصله استاپ‌لاس محاسبه می‌کند.
  4. یک برچسب وضعیت به کاربر بازخورد می‌دهد (مثلاً "Ready"، "Invalid SL Position" یا "Lot Size Too Small").
  5. تنها در صورتی که تمام شرایط معتبر باشند، دکمه Execute فعال شده و معامله را ارسال می‌کند.

ب) بخش Pending Order

• منطق: برای ثبت سفارشات شرطی (Stop/Limit).
• عملکرد:
  1. با کلیک روی Buy یا Sell، سه خط ورود (سفید)، حد ضرر و حد سود ظاهر می‌شوند.
  2. کاربر هر سه خط را به قیمت‌های دلخواه خود منتقل می‌کند.
  3. منطق هوشمند تشخیص نوع سفارش: اکسپرت به‌صورت خودکار نوع سفارش (Buy Stop, Buy Limit, Sell Stop, Sell Limit) را بر اساس موقعیت خط ورود نسبت به قیمت فعلی بازار تشخیص می‌دهد.
  4. پس از اعتبارسنجی کامل، دکمه Place سفارش را ثبت می‌کند.

ج) بخش Stairway Entry (ورود پلکانی)

• منطق: یک استراتژی منحصربه‌فرد برای ورود به معامله در پولبک (Pullback) پس از شکست یک سطح کلیدی. این استراتژی ریسک را کاهش داده و نقطه ورود بهینه‌تری فراهم می‌کند.
• عملکرد:
  1. با کلیک روی Arm Buy/Sell، دو خط اصلی روی چارت ظاهر می‌شود: خط شکست (Breakout - نارنجی) و خط ورود به پولبک (Pending Entry - سفید).
  2. کاربر خط شکست را روی سطح مقاومت/حمایت و خط ورود را در محلی که انتظار پولبک دارد، تنظیم می‌کند.
  3. اکسپرت بازار را تحت نظر می‌گیرد. به محض اینکه قیمت از خط شکست عبور کند، یک سفارش لیمیت به‌صورت خودکار روی خط ورود به پولبک قرار می‌دهد.
  4. این فرآیند به معامله‌گر اجازه می‌دهد تا بدون نیاز به حضور پای چارت، در بهترین قیمت ممکن پس از تأیید شکست، وارد معامله شود.

۱.۲. پنل نمایش اطلاعات (DisplayCanvas)

این پنل یک داشبورد کامل و زنده از وضعیت حساب و معامله در حال تنظیم شماست.

• بخش Setup: نمایش ریسک به ارز پایه حساب، حجم لات محاسبه‌شده و سود احتمالی (Reward).
• بخش Details: نمایش قیمت دقیق خطوط ورود، حد ضرر و حد سود.
• بخش Live: اگر معامله‌ای باز داشته باشید، سود/ضرر لحظه‌ای (P/L)، مجموع ریسک تمام معاملات باز و نسبت ریسک به بازده زنده (Live R:R) را نمایش می‌دهد.
• بخش Prop Firm Guardian: دو نوار پیشرفت که وضعیت شما را نسبت به محدودیت‌های ضرر روزانه و کلی نمایش می‌دهند.

۱.۳. پنل تحلیل اسپرد و ATR (SpreadAtrAnalysis)

• منطق: این پنل کوچک به‌عنوان یک راهنمای سریع، اسپرد فعلی را با نوسان متوسط بازار (ATR) مقایسه می‌کند.
• کاربرد: به معامله‌گر کمک می‌کند تا تشخیص دهد آیا اسپرد فعلی برای انجام معامله مناسب است یا به دلیل ریسک بالا، بهتر است از معامله صرف نظر کند.

بخش ۲: موتور مدیریت ریسک و اعتبارسنجی

این بخش، هسته مرکزی و موتور محاسباتی گریفین گارد است و از تصمیمات شما محافظت می‌کند.

۲.۱. محاسبه دقیق حجم لات (CalculateLotSize)

• دو حالت محاسبه: کاربر می‌تواند در تنظیمات ورودی، مبنای محاسبه ریسک را بین درصدی از موجودی حساب (RISK_PERCENT) یا مبلغ ثابت (RISK_MONEY) انتخاب کند.
• دکمه‌های ریسک سریع: سه دکمه با مقادیر از پیش‌تعیین‌شده (قابل تنظیم در ورودی‌ها) به کاربر اجازه می‌دهد با یک کلیک، ریسک مورد نظر خود را انتخاب کند.
• اعتبارسنجی حجم: حجم محاسبه‌شده همیشه با حداقل و حداکثر حجم مجاز بروکر (SYMBOL_VOLUME_MIN, SYMBOL_VOLUME_MAX) مقایسه شده و در صورت نیاز رُند می‌شود. اگر حجم نهایی کمتر از حداقل مجاز باشد، معامله نامعتبر تلقی می‌شود.

۲.۲. اعتبارسنجی لحظه‌ای (ValidateTradeLogicAndUpdateUI)

• منطق: این تابع با هر حرکت ماوس یا تغییر در ورودی‌ها فراخوانی می‌شود و تمام شرایط لازم برای یک معامله سالم را بررسی می‌کند:
  • آیا خطوط حد ضرر و ورود در جای مناسبی قرار دارند؟ (مثلاً برای خرید، SL باید پایین‌تر از Entry باشد).
  • آیا با توجه به فاصله SL، حجم لات قابل محاسبه و معتبر است؟
• بازخورد آنی: نتیجه این اعتبارسنجی فوراً روی برچسب وضعیت پنل نمایش داده شده و دکمه "Execute/Place" را فعال یا غیرفعال می‌کند.

بخش ۳: محافظ پراپ فرم (Prop Firm Guardian)

این ماژول برای معامله‌گرانی طراحی شده که در چالش‌های شرکت‌های پراپ تریدینگ شرکت می‌کنند.

• منطق: قبل از ارسال هر معامله، تابع `IsTradeRequestSafe` یک شبیه‌سازی از بدترین سناریوی ممکن را اجرا می‌کند. این تابع فرض می‌کند که تمام معاملات باز شما به همراه معامله جدیدی که قصد باز کردن آن را دارید، همزمان به حد ضرر خود می‌رسند.
• محاسبه ضرر بالقوه: مجموع ضرر این سناریو محاسبه شده و با دو حد مجاز مقایسه می‌شود:
  1. حد ضرر روزانه (Daily Drawdown): بر اساس موجودی حساب (Balance) یا موجودی شناور (Equity) در شروع روز معاملاتی.
  2. حد ضرر کلی (Max Drawdown): بر اساس موجودی اولیه حساب (Static) یا بالاترین اکوئیتی ثبت‌شده (Trailing).
• عملکرد: اگر ضرر بالقوه از هر یک از این حدود فراتر رود، اکسپرت به‌صورت خودکار جلوی ارسال معامله را گرفته و دلیل آن را به کاربر اطلاع می‌دهد.

بخش ۴: مدیریت وضعیت پایدار (StateManager)

• منطق: برای جلوگیری از دست رفتن اطلاعات در زمان ری‌استارت متاتریدر، این ماژول وضعیت‌های حساس را در یک فایل باینری (`.dat`) ذخیره می‌کند.
• کاربرد اصلی: این قابلیت برای استراتژی **Stairway** حیاتی است. اگر در میانه اجرای این استراتژی (مثلاً پس از شکست قیمت و قبل از فعال شدن سفارش لیمیت) متاتریدر بسته شود، پس از اجرای مجدد، اکسپرت تمام اطلاعات (قیمت خطوط، وضعیت فعلی و ...) را بازیابی کرده و به کار خود ادامه می‌دهد، گویی هیچ اتفاقی نیفتاده است.