Magento 2 | SeekGist

تعمل وحدة SeekGist مع Magento Open Source وAdobe Commerce بالإصدار 2.4.x مع OpenSearch أو Elasticsearch، على PHP 8.1 أو أحدث مع cURL. جُرّبت على Magento Open Source 2.4.9 (PHP 8.3 وMySQL 8.4 وOpenSearch 3.9 وقالب Luma).

1. احصل على مفاتيحك

أنشئ متجرك في لوحة تحكم SeekGist، ثم افتح الإعدادات > مفاتيح API: مفتاح عام (sg_pub_...، آمن في صفحات الويب) ومفتاح سري (sg_sec_...، للخادم فقط).

2. ثبّت الوحدة

إما عبر Composer، من ملف الحزمة seekgist-module-search-1.0.0.zip:

mkdir -p artifacts && cp seekgist-module-search-1.0.0.zip artifacts/
composer config repositories.seekgist artifact ./artifacts
composer require seekgist/module-search:1.0.0

أو بنسخ الملفات: فك ضغط الحزمة داخل app/code/SeekGist/Search/.

ثم، داخل مجلد Magento:

bin/magento module:enable SeekGist_Search
bin/magento setup:upgrade
bin/magento setup:di:compile               # في وضع الإنتاج فقط
bin/magento setup:static-content:deploy    # في وضع الإنتاج فقط
bin/magento cache:flush

تضيف الوحدة أربعة جداول صغيرة (seekgist_*) ومهمة مجدولة (seekgist_cron، كل 5 دقائق). ويجب أن تعمل المهام المجدولة في Magento نفسه (وهي تعمل في كل متجر Magento عادي).

3. الإعدادات

افتح Stores > Configuration > Catalog > SeekGist Search.

المجموعة	الإعداد	ماذا تضع
Connection	Use SeekGist	Yes. وNo يعني بحث Magento نفسه فورًا.
	API address	`https://api.seekgist.com` (أبقِ القيمة الافتراضية)
	Public key / Secret key	مفتاحاك. يُحفظ المفتاح السري مشفّرًا.
Features	Search results	Yes: يرتّب SeekGist صفحة نتائج البحث، ويعرض قالبك المنتجات.
	Suggest box	Yes: اقتراحات ومنتجات أثناء كتابة المتسوق (ويُخفى الإكمال التلقائي في Magento).
	Click and sales tracking	Yes. لا تُرسل أي بيانات شخصية.
	Product sync	Yes.
	AI query understanding	إيقاف (الأسرع).
	Only in-stock products	فعّله أيضًا إذا كان «Display Out of Stock Products» على No.
Storefront	Search box selector	الفراغ يناسب Luma ومعظم القوالب (`#search`).
	Catalog language	الفراغ يعني لغة عرض المتجر (store view).
Translations	Write back translations for	مثلًا `ar`، إذا كان لديك عرض متجر عربي.

احفظ، ثم من Status and actions اضغط Test connection (يظهر «Public key: OK» و«Secret key: OK»، ويظهر المتجر في لوحة تحكم SeekGist)، ثم Sync all products now.

يمكن أن تختلف الإعدادات لكل موقع ولكل عرض متجر (مثلًا: تشغيل البحث لعرض المتجر العربي فقط). أما المفاتيح والمزامنة فتُضبط مرة واحدة.

كيف تعمل

تبقى صفحة البحث catalogsearch/result/?q=.... يختار SeekGist منتجات الصفحة ويرتّبها، ويحمّل Magento قائمة منتجاته ويعرضها، فتبقى الأسعار والأسعار الخاصة والضرائب وأسعار مجموعات العملاء صحيحة.
إذا كان SeekGist بطيئًا (أكثر من 300 ملّي ثانية) أو رد بأي خطأ، يجيب بحث Magento نفسه فورًا، ولا تُحفظ تلك الصفحة في ذاكرة الصفحات الكاملة. وبعد 5 أخطاء خلال 60 ثانية يُتجاوز SeekGist لمدة 30 ثانية. راجع الرجوع إلى بحث المتجر.
ترسل الوحدة طلبها إلى SeekGist أولًا، ويعمل بحث Magento نفسه في أثناء انتظار الرد. لذا عندما يبطئ SeekGist، لا تنتظر الصفحة أكثر من 300 ملّي ثانية إضافية.
مع مرشّح من التصفية الجانبية (التصنيف، السعر، الخاصية) أو ترتيب غير الصلة والسعر، يخدم بحث Magento نفسه.
تُحسب الإضافة إلى السلة والطلبات على خادمك وتُرسل لاحقًا عبر المهمة المجدولة، فلا تنتظر السلة ولا صفحة الدفع SeekGist أبدًا.
المنتجات: تُرسل المنتجات المفعّلة الظاهرة في الكتالوج أو البحث، ويُرسل المنتج القابل للتهيئة مرة واحدة (بأقل سعر بين فروعه). وكل عرض متجر بلغة أخرى يضيف أسماءه وأوصافه.
الترجمات: تُكتب النصوص المعتمدة على أنها قيمة عرض المتجر (اسم المنتج، الوصف، اسم التصنيف) في كل عرض متجر بتلك اللغة. ولا يُستبدل أبدًا نص كتبه شخص.

الأوامر

bin/magento seekgist:test                 # اختبار الاتصال
bin/magento seekgist:cron --task=full     # all | delta | full | outbox | writeback
bin/magento seekgist:products --ids=12,13 # المنتجات كما يستلمها SeekGist تمامًا

الإزالة

bin/magento module:disable SeekGist_Search && bin/magento setup:upgrade

ثم احذف app/code/SeekGist/Search (أو شغّل composer remove seekgist/module-search). تبقى الترجمات التي كتبتها الوحدة (أصبحت من محتوى متجرك).

مشكلات وحلول

ما تراه	ماذا تفعل
«Public key: not accepted»	انسخ المفتاح مرة أخرى، وتحقق من عنوان API.
البحث كما كان من قبل	هل «Use SeekGist» على Yes لعرض المتجر هذا؟ ترويسة الرد `X-SeekGist-Search` تبيّن السبب (`ok`، `off`، `native_filter`، `fallback_timeout` وغيرها).
لا شيء يُزامن	هل المهام المجدولة في Magento تعمل؟ شغّل `bin/magento seekgist:cron --task=full` واقرأ الناتج.
تقارير سياسة أمان المحتوى (CSP)	تسمح الوحدة بـ `api.seekgist.com` في `connect-src`. وإذا استخدمت عنوان API خاصًا بك فأضفه إلى قائمة CSP المسموح بها.