مستندات پروژه Griffin

Griffin چیست؟

موتور تحلیلی Griffin یک سیستم جامع و ماژولار است که برای نظارت، ارزیابی و امتیازدهی به کیفیت داده‌های دریافتی از کارگزاران (بروکرها) طراحی شده است. در دنیای معاملات الگوریتمی و دستی که هر میلی‌ثانیه و هر پیپ اهمیت دارد، کیفیت فید قیمت می‌تواند تفاوت بین سود و زیان باشد. Griffin با تحلیل بی‌درنگ معیارهای کلیدی، این شفافیت را برای معامله‌گران فراهم می‌کند.

چرا Griffin اهمیت دارد؟

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

معماری سیستم

پروژه Griffin با یک معماری ماژولار و مبتنی بر FastAPI در پایتون ساخته شده است. این ساختار، توسعه و نگهداری سیستم را ساده کرده و هر بخش وظیفه مشخصی دارد.

الگوریتم‌ها و معیارهای کلیدی

امتیاز نهایی کیفیت از ترکیب وزنی چندین معیار کلیدی به دست می‌آید. در ادامه، هر معیار به تفصیل شرح داده می‌شود.

امتیاز اصالت داده (Authenticity Score)

این معیار بررسی می‌کند که آیا فید قیمت واقعی و طبیعی است یا خیر.

• همبستگی با رهبر (Correlation): سیستم به صورت خودکار یک "کارگزار رهبر" (معمولاً با بیشترین تعداد تیک) را انتخاب می‌کند. سپس، سری زمانی قیمت دیگر کارگزاران با رهبر مقایسه شده و ضریب همبستگی آن‌ها محاسبه می‌شود. همبستگی نزدیک به ۱ نشان‌دهنده اصالت است.
• تحلیل توزیع تیک‌ها (Shapiro-Wilk Test): یک فید طبیعی دارای فواصل زمانی نامنظم بین تیک‌هاست. این سیستم از آزمون آماری شاپیرو-ویلک برای ارزیابی نرمال بودن توزیع این فواصل استفاده می‌کند. p-value پایین می‌تواند نشانه‌ای از یک الگوی مصنوعی باشد.

امتیاز یکپارچگی داده (Integrity Score)

این معیار به شناسایی و جریمه کردن گلیچ‌ها (Price Glitches) یا پرش‌های قیمتی غیرعادی می‌پردازد.

• شناسایی گلیچ بالقوه: هر تیک جدید با میانگین و انحراف معیار تیک‌های اخیر مقایسه می‌شود. اگر تغییر قیمت از یک آستانه دینامیک فراتر رود، به عنوان "گلیچ بالقوه" نشانه‌گذاری می‌شود.
• تأیید گلیچ: گلیچ‌های بالقوه با قیمت کارگزار رهبر در یک پنجره زمانی کوتاه مقایسه می‌شوند. اگر انحراف قیمت از میانگین قیمت رهبر زیاد باشد، گلیچ تأیید شده و یک امتیاز منفی به کارگزار اختصاص می‌یابد.
• زوال جریمه (Penalty Decay): امتیاز جریمه به مرور زمان کاهش می‌یابد تا یک گلیچ تا ابد روی امتیاز کارگزار تأثیر منفی نگذارد.

امتیاز کیفیت اجرا (Execution Score)

این معیار انصاف کارگزار در اجرای معاملات را از طریق تحلیل لغزش قیمت (Slippage) می‌سنجد.

• عدم تقارن لغزش (Asymmetric Slippage): سیستم میانگین لغزش‌های مثبت (به نفع مشتری) و منفی (به ضرر مشتری) را محاسبه می‌کند. اگر لغزش‌های منفی به طور سیستماتیک بزرگ‌تر از لغزش‌های مثبت باشند، این نشانه یک رفتار غیرمنصفانه است و امتیاز کیفیت اجرای کارگزار کاهش می‌یابد.

تحلیل زمانی (Timeframe Analysis)

این قابلیت جدید به شما اجازه می‌دهد عملکرد یک کارگزار را در بازه‌های زمانی مختلف ارزیابی کنید. سیستم میانگین امتیاز کیفیت را در بازه‌های ۱۵ دقیقه، ۳۰ دقیقه، ۱ ساعت، ۴ ساعت و ۸ ساعت گذشته محاسبه و نمایش می‌دهد.

نصب و راه‌اندازی

برای استفاده از پروژه Griffin، باید دو بخش بک‌اند (سرور پایتون) و فرانت‌اند (اکسپرت متاتریدر) را راه‌اندازی کنید.

۱. راه‌اندازی بک‌اند (سرور پایتون)

1. پیش‌نیازها: مطمئن شوید پایتون نسخه 3.8 یا بالاتر روی سیستم شما نصب است.
2. نصب وابستگی‌ها: یک فایل `requirements.txt` با محتوای زیر ایجاد کرده و سپس دستور `pip install -r requirements.txt` را اجرا کنید.

   fastapi
   uvicorn[standard]
   numpy
   pandas
   scipy

3. اجرای سرور: در پوشه اصلی پروژه، دستور زیر را در ترمینال اجرا کنید.

   uvicorn main:app --host 127.0.0.1 --port 5000 --reload

   پرچم `--reload` باعث می‌شود سرور با هر تغییر در کد به صورت خودکار مجدداً راه‌اندازی شود که برای توسعه بسیار مفید است.

۲. راه‌اندازی فرانت‌اند (اکسپرت MQL5)

1. نصب اکسپرت: فایل `GriffinTickSender.mq5` را در پوشه `MQL5/Experts` در محل نصب متاتریدر خود کپی کنید.
2. پیکربندی: اکسپرت را روی چارت مورد نظر خود بکشید. در پنجره تنظیمات، آدرس سرور پایتون خود را در فیلد `InpServerUrl` وارد کنید (مثلاً `http://127.0.0.1:5000`).
3. فعال‌سازی WebRequest:

   این مرحله بسیار مهم است. در متاتریدر به منوی `Tools > Options` بروید. در تب `Expert Advisors`، گزینه `Allow WebRequest for listed URL` را فعال کرده و آدرس سرور خود را به لیست اضافه کنید.

   
4. فعال‌سازی AutoTrading: روی دکمه `Algo Trading` در نوار ابزار متاتریدر کلیک کنید تا سبز شود.

مستندات API

سرور Griffin از طریق یک API ساده مبتنی بر HTTP داده‌ها را دریافت و نتایج را ارائه می‌دهد.

Endpoints دریافت داده

Endpoint دریافت نتایج

{
  "EURUSD": {
    "Errante Trading LLC": {
      "broker_name": "Errante Trading LLC",
      "is_leader": true,
      "quality_score": 92.5,
      "score_integrity": 100.0,
      "score_authenticity": 95.8,
      "score_execution": 88.1,
      "score_feed_stability": 100.0,
      "score_history": [90.1, 91.3, 92.5, ...],
      "timeframe_averages": {
        "15m": 91.7,
        "30m": 90.5,
        "1h": 89.9,
        "4h": 85.1,
        "8h": 82.4
      },
      "verified_glitches_log": [
        { "time_str": "14:30:05", "bid": 1.05100, "severity": 15.2 }
      ],
      // ... and other raw KPIs
    },
    // ... other brokers
  },
  // ... other symbols
}

راهنمای داشبورد

داشبورد نهایی Griffin یک نمای مینیمال و داده-محور برای تحلیل سریع فراهم می‌کند. در ادامه به معرفی بخش‌های مختلف آن می‌پردازیم.

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