إنشاء مصدر بيانات مخصص

استخدم مصدر بيانات مخصصًا لربط AQE ببورصة أو خدمة لبيانات السوق أو مجموعة بيانات تاريخية خاصة بك. لا يرسل مصدر البيانات أوامر تداول، ويمكنه العمل مع PaperBroker أو مهايئ تنفيذ منفصل.

يتبع هذا الدليل واجهات AQE 0.2.0. استخدم تعريفات السمات من نسخة شيفرة AQE نفسها التي تستخدمها استراتيجيتك، خصوصًا عند ترقية تكامل موجود.

1. تنفيذ السمتين

أنشئ نوع Rust يمتلك عميلك وحالة الاتصال ومهام الاشتراك. نفّذ aq_engine::core::broker::traits::{DataFeed, DataProvider} لهذا النوع. يجب أن يكون Send + Sync.

السمة	الدوال المطلوبة	المسؤولية
DataFeed	connect, disconnect, is_connected	إنشاء النقل وتحريره؛ والإبلاغ عن حالته الفعلية.
DataProvider	get_ticker_info	إعادة Asset في AQE يتضمن الرمز وقواعد التداول والدقة.
DataProvider	get_history	إعادة DataFrame من Polars للرمز والنطاق الزمني بتوقيت UTC وTimeFrame المطلوبة.
DataProvider	get_latest_bar, get_latest_quote	إعادة Bar أو Quote مع طابع المصدر الزمني.
DataProvider	subscribe_to_data_stream, unsubscribe_from_data_stream	إدارة دوال استدعاء الشموع للرموز والإطار الزمني المطلوبَين.

تستخدم السمات دوال Rust غير المتزامنة الأصلية. وتتطلب connect وget_latest_quote صراحةً قيمًا مستقبلية تحقق قيد Send؛ ويمكن لتنفيذ async fn تلبية ذلك عندما تحقق الحالة التي يحتفظ بها قيد Send. لا تحتفظ بحارس قفل غير Send عبر .await.

عند إلغاء محاولة الاتصال، يجب أن تبقى مواردها تحت ملكية المهايئ حتى تتمكن disconnect من تحريرها. أوقف المهام الخلفية وحرّر الاشتراكات عند قطع الاتصال، وتجنّب مهام العمل المنفصلة التي تواصل تسليم البيانات بعد ذلك.

إعلان القدرات المدعومة فقط

أعِد تعريف DataFeed::get_features() بشريحة ثابتة من قيم DataFeedFeature. القيمة الافتراضية شريحة فارغة.

• السجل والأسعار الحالية: HistoricalCandles وLatestCandle وLatestQuote.
• تسليم الشموع: CandleStream، وIntraCandleStream فقط عند تنفيذها.
• عروض الأسعار المستقلة: QuoteStream، إلى جانب NativeBidAsk أو SyntheticQuotes بحسب الملائم.

تظل دوال السمات المطلوبة بحاجة إلى تنفيذ حتى عند غياب قدرة معينة. أعِد BrokerError واضحًا للعملية غير المدعومة بدلًا من بيانات مختلقة أو عملية لا تفعل شيئًا وتعيد نجاحًا. يمكن لمهايئ يوفّر السجل فقط أن يفيد الاختبارات التاريخية دون إعلان البث المباشر.

إعادة البيانات الوصفية الكاملة للأداة المالية

تعيد get_ticker_info كائن Asset، لا مجرد رمز. املأ هوية الأداة ونوع الأصل والبورصة وأذونات التداول وقواعد التنفيذ التالية من البيانات الوصفية للمزوّد:

الحقول	البيانات المطلوبة
min_order_size, quantity_base	الحد الأدنى للكمية ودقة الكمية المعتمدان في AQE. حافظ على اتساقهما مع قواعد الكمية لدى جهة التداول.
max_order_size, max_total_size	حد الأمر الواحد والحد الإجمالي للرمز، على الترتيب. استخدم None عندما لا يبلّغ المزوّد عن حد؛ ولا تخلط بينهما.
min_price_increment, price_base, contract_size	خطوة السعر ودقته ومضاعف العقد عند معرفتها. لا تفترض أن كل أداة تستخدم الأسهم وحدةً للكمية أو أن مضاعفها يساوي واحدًا.
trading_calendar	قيمة Option<String> تحتوي على جدول التداول بصيغة JSON كما سجّله منتج البيانات، بما في ذلك مصدره. أبقِها None عندما يكون الجدول غير معروف؛ ولا تستنتج استمرار التداول دون انقطاع من غياب البيانات الوصفية.
fees	بيانات AssetFees للعمولات ورسوم التبييت عند توفرها. تستخدم بيانات العمولات الحالية commission.entry وcommission.exit، ولكل منهما قيم للمراكز الطويلة والقصيرة؛ وتستخدم رسوم التبييت swap.long وswap.short.

توفّر AssetFees::default() إعدادات رسوم فارغة؛ وليست دليلًا على أن جهة التداول لا تفرض رسومًا. يظل حقلا الرسوم القديمان entry وexit خيارَين احتياطيَّين للتوافق. قد تختلف قواعد جهة تنفيذ منفصلة وتكاليفها عن قواعد مزوّد البيانات وتكاليفه: تحقّق من البيانات الوصفية بالرجوع إلى حساب التنفيذ، ولا تفترض أن بيانات السوق وحدها تخوّل إرسال أمر.

2. توحيد تنسيق الشموع وعروض الأسعار

حوّل سجلات المزوّد إلى قيم Bar في AQE، باستخدام طوابع زمنية بتوقيت UTC ورموز متسقة. عالج تقسيم النتائج إلى صفحات والترتيب الزمني والتكرارات والأطر الزمنية المطلوبة صراحةً. لا تُعِد إطارًا زمنيًا مختلفًا بصمت ولا تستبدل السجل المفقود بالأسعار الحالية.

تحتاج إطارات البيانات التاريخية إلى هذه الأعمدة:

العمود	التمثيل القياسي
symbol	سلسلة نصية
open, high, low, close, volume	f64
timestamp	ميلي ثانية Unix بتوقيت UTC من نوع i64، كما ينتجها المحوّل الافتراضي في AQE

فضّل المحوّل الموجود على إنشاء إطار يدويًا. تفترض هذه الدالة المساعدة أنك فككت استجابة المزوّد وتحققت منها بالفعل بصيغة Vec<Bar>:

use aq_engine::core::broker::{
    traits::DataProvider,
    types::{Bar, BarData, BrokerError},
};
use polars::prelude::DataFrame;

pub fn normalise_history<D: DataProvider>(
    provider: &D,
    bars: Vec<Bar>,
) -> Result<DataFrame, BrokerError> {
    provider
        .format_on_bar(BarData::Bars(bars))
        .map_err(BrokerError::DataFeedError)
}

استخدم إصدار Polars متوافقًا مع اعتمادية AQE لديك. تتحقق format_on_bar(BarData::Frame(...)) من أسماء الأعمدة المطلوبة؛ لكنها لا تتحقق بالكامل نيابةً عنك من الأنواع أو الترتيب أو جودة بيانات السوق.

يتضمن Quote الأصلي symbol وbid وask والأحجام وقيمًا اختيارية لآخر صفقة وطابعًا زمنيًا بتوقيت UTC. يجب أن تكون الأسعار أعدادًا منتهية وموجبة، وأن يتحقق الشرط ask >= bid، وأن تكون الأحجام غير سالبة. للمصدر الذي يعتمد على الشموع فقط، تنشئ Quote::from_bar_close(&bar) عرض سعر اصطناعيًا bid=ask دون اختلاق حجم لدفتر الأوامر. أعلن SyntheticQuotes، لا NativeBidAsk، لهذا التمثيل.

تضمين حقل تقييم عرض السعر الجديد

يتضمن Quote الآن أيضًا الحقل profit_model. أضف هذا الحقل إلى صيغ إنشاء هياكل Rust الموجودة، حتى إذا لم يستطع مزوّدك توفير نموذج تقييم. تتيح السمة #[serde(default)] قراءة عروض الأسعار القديمة المحفوظة بصيغة تسلسلية؛ لكنها لا تملأ حقلًا مفقودًا في شيفرة Rust المصدرية.

لمصدر بيانات عام، استخدم profit_model: None. يفترض هذا المثال أن الأسعار الواردة وطابعها الزمني قد خضعت للتحقق بالفعل؛ وتعني الأحجام الصفرية عدم الإبلاغ عن الحجم، لا اختلاق سيولة:

use aq_engine::core::broker::types::Quote;
use chrono::{DateTime, Utc};

pub fn quote_without_valuation(
    symbol: String,
    bid: f64,
    ask: f64,
    timestamp: DateTime<Utc>,
) -> Quote {
    Quote {
        profit_model: None,
        symbol,
        bid,
        ask,
        bid_size: 0.0,
        ask_size: 0.0,
        last: None,
        last_size: None,
        timestamp,
    }
}

لا تُرفق نموذج BrokerQuoteProfit إلا عندما يستطيع وسيط التنفيذ توفير معاملات صالحة بعملة الحساب لذلك الحساب والرمز وعرض السعر. يسجّل النموذج version وaccount_id وcurrency وsymbol وas_of_us، ومعاملات مستقلة هي buy_gain وbuy_loss وsell_gain وsell_loss. الإصدار الحالي هو 1؛ ويجب أن تكون المعاملات أعدادًا منتهية وموجبة. يُقاس وقت الرصد بميكروثواني Unix بتوقيت UTC، بينما يكون الحقل Quote.timestamp من نوع DateTime بتوقيت UTC.

هذه المعاملات قيم نقدية يعايرها الوسيط لكل وحدة سعر ووحدة كمية معتمدة لديه، وليست تحويلًا عامًا للعملات الأجنبية أو سجلًا للأرباح المحققة. حافظ على ارتباطها بحسابها وعملتها ورمزها وعلى حداثتها؛ ولا تنقلها بين الحسابات أو تختلقها من سعر إغلاق شمعة. تترك Quote::from_bar_close النموذج غائبًا عن قصد. ولا تحل هذه البيانات الوصفية محل علامات قدرات عروض الأسعار الموجودة.

3. تنفيذ الاشتراكات

تتلقى subscribe_to_data_stream الرموز وTimeFrame وDataStreamMode ودالة استدعاء Arc<dyn Fn(Bar) + Send + Sync>. التزم بالوضع المحدد: يسلّم CompletedBar الشموع المكتملة، ويسمح Intrabar بتحديثات الشمعة التي لا تزال قيد التكوّن. أبقِ تنفيذ دالة الاستدعاء قصيرًا وغير حاجب.

لمزوّد يعتمد الاستطلاع الدوري، افحص DataStreamManager ومهايئ Yahoo الموجودَين قبل كتابة مجدول آخر. قد يدير مزوّد websocket مهام القراءة الخاصة به، لكنه يظل ملزمًا بعقد دوال الاستدعاء وإلغاء الاشتراك نفسه.

بث عروض الأسعار اختياري. لإعلان QuoteStream، أعِد تعريف كل من subscribe_to_quote_stream وunsubscribe_from_quote_stream. لكل اشتراك معرّفه الخاص: يجب ألا يؤدي حذفه إلى إيقاف عروض أسعار مستهلك آخر أو شموعه. تعيد دالة الاشتراك الافتراضية خطأ عدم الدعم. ولا تضمن واجهة عروض الأسعار كل تحديث سعري في البورصة.

4. ربط المزوّد بـAQE

بمجرد تنفيذ نوعك لكلتا السمتين، مرّر نسخة منه إلى UnifiedBroker. تقبل هذه الدالة المساعدة القابلة لإعادة الاستخدام أي مزوّد متوافق؛ ولا تنفّذ واجهة الشبكة الخاصة بالمزوّد:

use aq_engine::core::broker::{
    paper_broker::PaperBroker,
    traits::{DataFeed, DataProvider},
    types::AccountType,
    UnifiedBroker,
};

pub fn backtest_with<D>(datafeed: D) -> UnifiedBroker<PaperBroker, D>
where
    D: DataFeed + DataProvider,
{
    let execution = PaperBroker::new(AccountType::Paper, 100_000.0, 1);
    UnifiedBroker::new_backtest(execution, datafeed)
}

للتشغيل المباشر أو التجريبي المباشر، استخدم UnifiedBroker::new(execution, datafeed). أبقِ إعادة التشغيل التاريخي على new_backtest؛ إذ تأتي عروض أسعار إعادة التشغيل من الشموع المستهلكة لا من نقطة نهاية أسعار السوق الحالية.

يتيح تنفيذ هذه السمات الاستخدام في استراتيجيات Rust. وتتطلب إضافة نموذج اتصال أو خيار مزوّد في AQS تكاملًا مستقلًا لسطح المكتب.

نقاط الاستدعاء الاختيارية للمزوّد

تعيد supports_historical_stream(symbol, timeframe) افتراضيًا Ok(true). أعِد تعريفها لمجموعات البيانات المحدودة حتى يمكن تجاوز رمز أو إطار زمني غير متاح عن قصد. أبقِ أخطاء الشبكة والمصادقة والبيانات الفعلية أخطاءً؛ ولا تستخدم نقطة الاستدعاء هذه لإخفاء طلب فاشل أو استبدال إطار زمني آخر بصمت.

الدالة configure_live_session نقطة استدعاء اختيارية لسياق الجلسة، ولا يفعل تنفيذها الافتراضي شيئًا. وهي لا تجعل بيانات التقييم الوصفية أو الاتصال السحابي إلزاميَّين لمصدر بيانات مخصص.

5. التحقق قبل الاستخدام المباشر

1. اختبر الرموز غير الصالحة والسجل الفارغ وتقسيم النتائج إلى صفحات وتحويل الطوابع الزمنية والأطر الزمنية غير المدعومة.
2. تحقّق من قيم OHLCV والترتيب الزمني بمقارنتها بمجموعة بيانات صغيرة معروفة.
3. اختبر تسليم الشموع المكتملة والتحديثات داخل الشمعة كلًا على حدة، بما في ذلك إعادة الاتصال والرسائل المكررة.
4. أنشئ اشتراكَين لعروض الأسعار، وأزل أحدهما، وتأكّد من بقاء الآخر نشطًا.
5. اختبر قطع الاتصال أثناء محاولة الاتصال وأثناء البث؛ وتحقّق من تحرير جميع الموارد المملوكة.
6. شغّل اختبارًا تاريخيًا حتميًا باستخدام PaperBroker قبل ربط حساب تنفيذ مباشر.
7. راجع كل صيغة إنشاء لهيكلَي Asset وQuote بعد ترقية AQE. اختبر غياب بيانات التقييم الوصفية والنماذج المتقادمة أو التابعة لحساب آخر وعروض الأسعار الاصطناعية، دون اعتبار القيم غير المتاحة أرباحًا صفرية.

مرجع المصدر

في نسخة AQE المحلية، ابدأ بما يلي:

• src/core/broker/mod.rs: DataFeed وDataProvider وDataStreamMode وUnifiedBroker.
• src/core/broker/types/mod.rs: Asset وBar وQuote وBarData وBAR_DATAFRAME_COLUMNS.
• src/core/broker/features.rs: علامات القدرات المدعومة.
• src/core/broker/data_feeds/yahoo.rs: جلب السجل والتطبيع والاستطلاع الدوري.
• src/core/broker/data_stream.rs: إدارة اشتراكات الشموع المشتركة.
• live-sync-protocol/src/quote_profit.rs: نطاق BrokerQuoteProfit ومعاملاته والتحقق من حداثته.

التالي: إنشاء وسيط مخصص أو الوسطاء ومصادر البيانات.